Return to Sender

Return to Sender

The Lowly Sender Parameter Can Make Applications Shine

 The humble Sender parameter could be one of Delphi's most useful tools for modular, extensible programming. Although Sender is normally used to simply determine which object called a particular procedure, with some creativity, this parameter can be extended to allow robust modular programming with simple, reusable code.

 Sender Basics

The Sender parameter is so ingrained in Delphi programming that it appears in practically every program procedure. Even the Form's OnCreate event - which has no sender - includes the (Sender: TObject) parameter in its definition.

 Despite its ubiquity, the Sender parameter is not necessary for a procedure to function. Removing Sender from a procedure that doesn't use it results in perfectly functional code, as long as the parameter is also removed from the procedure's type statement in the form object's interface section. Delphi will generate an "incompatible parameter" warning at compile time, but this can be safely ignored. In fact, removing any unused Sender parameters results in slightly leaner and meaner code.

 Not only can Sender be omitted from any procedure, but when used, it doesn't even have to be called Sender. This name is only used by convention. The common term makes understanding code simpler, but there's no reason not to name it Caller, Origin, or Banana if the developer prefers.

 So the Sender parameter doesn't have to be called Sender, and is, in fact, unnecessary. So what is it? And why is it important enough to add to practically every Delphi procedure?

 Sender is simply a parameter passed from the component that called the event handler. Sender (or whatever it's called by the event handler) is a parameter of the type TObject. Because TObject is the ancestor of all components, Sender can accommodate any Delphi object that can possibly trigger an event. Sender forms a two-way link between an object and an event handler; it tells the procedure what object triggered it to be called. In other words, if an event handler was a letter, the Sender parameter would be the return address.

 Using Sender

The simplest and most common way to use Sender is with an if...then or case statement that performs a certain action depending on what object triggered the procedure. Here's a typical example:

 procedure Form1.ButtonClick(Sender: TObject);

begin

   if Sender is StopButton

     then Stop(Sender);

end;

 This code examines the Sender parameter to see if it's the object, StopButton. If so, the event handler calls another procedure, Stop, passing the Sender parameter to that procedure as well. The Stop procedure can call another procedure and so on, passing the Sender parameter through the program code. Because each procedure is simply passing along the parameter it received, wherever the parameter is ultimately used, it will reflect the object that called the original event handler.

 Not only can Delphi developers use Sender to identify the object that called a procedure, but they can also use it to access that object's properties. The form in Figure 1 uses a number of colored panels as a palette. When the user clicks on a panel, the large panel on the left changes to the color of the selected panel.

 

Figure 1: This mini-program sets the color of the panel at right to the color of the panel selected by the user.

 This procedure does not need the name of the panel selected, only its color property. Therefore, each panel in the palette can have its own color, but all share the following OnClick event handler:

 procedure TForm1.Panel1Click(Sender: TObject);

begin

  Panel1.Color := TPanel(Sender).Color;

end;

 Since Sender provides a "return address" to the calling object, that object's properties can be read and set as well. This way, the procedure can also change the panel's Color property without actually working with the panel object's name. For example:

 TPanel(Sender).Color := clRed;

 Any type of property can be accessed using this framework, provided it's a property belonging to the specified type. In the previous example, the procedure specifies that Sender is a TPanel, which therefore has a Color property. While Sender is declared as a TObject in the procedure header, the following line would return a compiler error.

 TPanel1.Color := TObject(Sender).Color;

 As TPanel's ancestor type, TObject is perfectly valid in other respects; but it does not contain a Color property. Since TObject contains no properties, developers cannot use it to determine the properties of a wide range of objects. This means a program cannot find the color of a TPanel, TLabel, or TForm all with the same TObject(Sender).Color code.

 In fact, these three component types all contain the Color property. However, because they do not share this property in common ancestor classes, programmers cannot easily create one block of code to get the Color property from these various types of objects. The simplest solution a developer could use would be this:

 if Sender is TPanel then

  Brush.Color := TPanel(Sender).Color;

if Sender is TLabel then

  Brush.Color := TLabel(Sender).Color;

if Sender is TForm then

  Brush.Color := TForm(Sender).Color;

 Fortunately for developers, the Delphi designers added the Tag property. Tag is a little catch-all integer parameter that developers can use for whatever purpose they choose. What makes Tag especially useful is that it resides well up the inheritance tree in the TComponent class. Just two steps down the ladder from TObject, TComponent is the ancestor of all controls. This means that any of these objects will have the Tag property. Unlike the Color property cited above, the Tag property of any object can be accessed with a simple line of code:

 TForm.Tag := TComponent(Sender).Tag;

 Sender Impostors

I mentioned earlier that as procedures pass the Sender parameter from one to another, it never changes. It always points back to the object that called the original event handler. This is true provided each procedure along the path passes the original parameter. However, you can also substitute another parameter for the original Sender, fooling subsequent procedures into acting on another object as if it were the true Sender.

 This is the basis of our sample application, SENDER.DPR. It uses Sender and the Tag property so that Delphi can be "fooled" into having similar menu and button commands perform special actions on the buttons. Traditionally, this wouldn't require special Sender parameters - both buttons and menu items will share an event handler that can update the button as part of its functionality:

 procedure Button1Click(Sender: TObject);

begin

  { Main functionality }

  Button1.Font.Style := [fsBold];

end;

 However, when several components share a single event handler, the programmer cannot simply assume to act on a specific object. Modifying the code in question to read:

 TButton(Sender).Font.Style := [fsBold];

 is fine provided the code is always called by a TButton. However, this makes it troublesome to call the same event handler from a corresponding menu item because the menu item will cause an error each time it calls the event handler.

 The Sample Application's Framework

The sample application provides the framework for a modular, easily-extendible application. It also demonstrates how to make the simple Sender parameter do a lot of high-powered work, and shows how to get around some of the limitations mentioned earlier.

 Most applications contain menu items and buttons that perform the same action. Delphi makes it simple to do this by routing multiple events to a shared event handler. If multiple buttons and menu items all use the same event handler, it's simple to determine which control called the procedure. However, it becomes more difficult to determine, say, which menu item corresponds to the calling event if the control was actually a button. The user may obviously find that the Word Wrap button and the Word Wrap menu command are synonymous in functionality. However, to have Delphi understand this and update the menu item's Checked property - regardless of which control was the Sender - takes some special programming.

 The sample application contains four SpeedButtons, as well as main and pop-up menu items that correspond to each (see Figure 2). The buttons and menu items each perform similar functions, in this case, using a database to track the amount of time spent on each of a number of tasks. Program users can configure any number of tasks, all of which call the same event handler. (For the sake of clarity, the sample application illustrates only the Sender functions.)

 
Figure 2: The layout of the sample application's components.

 While a task is active, its SpeedButton remains depressed. Pressing a depressed button releases it and ends the task. Pressing a button while another is depressed releases the first and depresses the new button, causing the timesheet database to be simultaneously updated. The trick, of course, is to handle a number of MenuItems and SpeedButtons all with one event handler. This technique enables the programmer to allow for any number of tasks without having to write a new handler for each.

 Implementing this functionality requires one more ingredient: the Components property. Like Tag, Components is a property of TComponent, meaning that it's accessible to all components. Components is a property of every component, but in most cases it's only used on TForms. In this case, the Components property is an array of all components owned by the form.

 Build It

To build the sample application, create a single form named Form1. Add four SpeedButtons (used here to easily allow two-state buttons), a Label, a MainMenu (with an item called File1 and four sub-items), and a pop-up menu (also with four menu items). Set the properties as shown in Figure 3.

 

SpeedButtons
Name/Caption	AllowAllUp	GroupIndex	Tag	OnClick event handler
SpeedButton1	True	1	1	SpeedButtonClick
SpeedButton2	True	1	2	SpeedButtonClick
SpeedButton3	True	1	3	SpeedButtonClick
SpeedButton4	True	1	4	SpeedButtonClick

 

MenuItems
Name/Caption	Tag	OnClick event handler
File1	0	--
MainItem1	1	SpeedButtonClick
MainItem2	2	SpeedButtonClick
MainItem3	3	SpeedButtonClick
MainItem4	4	SpeedButtonClick
PopupItem1	1	SpeedButtonClick
PopupItem2	2	SpeedButtonClick
PopupItem3	3	SpeedButtonClick
PopupItem4	4	SpeedButtonClick

Figure 3: Setting the values of properties for the sample application's SpeedButton and MenuItem components.

 Note that all the buttons and menu items have the same event handler, namely SpeedButtonClick (see Figure 4). This procedure is called from any of the SpeedButtons or menu items on the form (except MenuItem File1). It references two external procedures, PushButton and ReleaseButton.

 procedure TForm1.SpeedButtonClick(Sender: TObject);

var

  A : Integer;

begin

   if Sender is TSpeedButton then

     if TSpeedButton(Sender).Down then

      PushButton(Sender)

     else

      ReleaseButton(Sender)

   else

     for A := 0 to ComponentCount-1 do

      if Components[A] is TSpeedButton then

        with Components[A] as TSpeedButton do

          if Tag = TComponent(Sender).Tag then

            begin

              Down := not Down;

              if Down then

                PushButton(Self.Components[A])

              else

                ReleaseButton(Self.Components[A]);

            end;

end;

Figure 4: Referencing PushButton and ReleaseButton with the SpeedButtonClick procedure.

 SpeedButtonClick first determines which object sent the event. If it's a TSpeedButton, it simply passes that object to the PushButton or ReleaseButton procedure, depending on the button's state (up or down). These procedures simply allow convenient spots for the messages to be handled. In the following example, the Caption of Label1 is set to report the event that occurred:

 procedure TForm1.PushButton(Sender: TObject);

begin

  Label1.Caption :=

    TComponent(Sender).Name + ' was clicked.';

end;

 procedure TForm1.ReleaseButton(Sender: TObject);

begin

  Label1.Caption :=

    TComponent(Sender).Name + ' was released.';

end;

 If the Sender of the event is not one of the buttons, we must determine which button to click. This is where the Tag property and the Components array property come in. As you noticed in Figure 3, SpeedButton1 had a Tag value of 1. MainItem1 and PopupItem1 also have Tag values of 1. Therefore, if any of the menu items are selected, it's a simple matter of viewing their Tag values and transferring the event to the SpeedButton with the same Tag. This is handled in the SpeedButtonClick handler:

 for A := 0 to ComponentCount-1 do

   if Components[A] is TSpeedButton then

     with Components[A] as TSpeedButton do

      if Tag = TComponent(Sender).Tag then

 This code snippet scans the Components array and examines each component it finds. When a TSpeedButton is found, the code compares this object's Tag value with the Tag value of the object that originally fired the message. If the values are the same, then the code found the button that ultimately receives the event. Since the code has already determined that it's a TSpeedButton, this object's up/down state can now be toggled. Then, either the PushButton or ReleaseButton procedure is called with the selected SpeedButton passed as the parameter as follows:

 begin

  Down := not Down;

   if Down then

    PushButton(Self.Components[A])

   else

    ReleaseButton(Self.Components[A]);

end;

 This statement:

 

PushButton(Self.Components[A])

 calls the procedure PushButton, passing along the parameter:  

Self.Components[A]

 The PushButton procedure interprets this Self statement as the original Sender. The Self portion is required because we want to look at the Components property of Form1. Since the code uses a with statement to simplify readability, we must ensure that the code is viewing the correct Components property. In this case, SpeedButtons also have a Components property and without the Self qualifier, it will erroneously look there instead.

 The PushButton procedure is where the timesheet database would be updated or other functions would be performed. Since the previous procedure handled the bulk of the work, PushButton simply performs the actions necessary when the button has been pressed. Remember that SpeedButtonClick did not send the actual Sender parameter, but sent a modified one that points to the SpeedButton regardless of how the button was selected. SpeedButtonClick's other procedure call, ReleaseButton, is likewise called to handle whatever events should occur when the button is released.

 Conclusion

Alone, the Sender parameter is a simple return address, allowing functions to trace which component triggered their event. But used in conjunction with a few other properties, such as Tag and Components, Sender becomes a powerful tool for tracing and filtering program flow. This ability to work around program limitations allows developers to create single, modular event handlers for components of all types, without the need for multiple if..then statements. This, of course, is just one way of extending Sender's abilities. There are as many possibilities as there are programs to write.