What Happens When an Action Fires

From RAD Studio
Jump to: navigation, search

Go Up to Handling VCL Actions Using an Action List


When an event fires, a series of events intended primarily for generic actions occurs. Then if the event does not handle the action, another sequence of events occurs.

Responding with events

When a client component or control is clicked or otherwise acted on, a series of events occurs to which you can respond. For example, the following code illustrates the event handler for an action that toggles the visibility of a toolbar when the action is executed:

procedure TForm1.Action1Execute(Sender: TObject);
begin
  { Toggle Toolbar1's visibility }
  ToolBar1.Visible := not ToolBar1.Visible;
end;
void __fastcall TForm1::Action1Execute(TObject *Sender)
{
    // Toggle Toolbar1's visibility
    ToolBar1->Visible = !ToolBar1->Visible;
}

Note: For general information about events and event handlers, see Working with Events and Event Handlers.

You can supply an event handler that responds at one of three different levels: the action, the action list, or the application. This is only a concern if you are using a new generic action rather than a predefined standard action. You do not have to worry about this if using the standard actions because standard actions have built-in behavior that executes when these events occur.

The order in which the event handlers will respond to events is as follows:

  1. Action list
  2. Application
  3. Action

When the user clicks on a client control, Delphi calls the action's Execute method which defers first to the action list, then the Application object, then the action itself if neither action list nor Application handles it. To explain this in more detail, Delphi follows this dispatching sequence when looking for a way to respond to the user action:

If you supply an OnExecute event handler for the action list and it handles the action, the application proceeds.

The action list's event handler has a parameter called Handled, that returns False by default. If the handler is assigned and it handles the event, it returns True, and the processing sequence ends here. For example:

procedure TForm1.ActionList1ExecuteAction(Action: TBasicAction; var Handled: Boolean);
begin
  Handled := True;
end;
void __fastcall TForm1::ActionList1ExecuteAction(TBasicAction *Action,
    bool &Handled) {
    Handled = true;
}

If you do not set Handled to True in the action list event handler, then processing continues.

If you did not write an OnExecute event handler for the action list or if the event handler does not handle the action, the application's OnActionExecute event handler fires. If it handles the action, the application proceeds.

The global Application object receives an Vcl.Forms.TApplication.OnActionExecute event if any action list in the application fails to handle an event. Like the action list's OnExecute event handler, the OnActionExecute handler has a parameter Handled that returns False by default. If an event handler is assigned and handles the event, it returns True, and the processing sequence ends here. For example:

procedure TForm1.ApplicationExecuteAction(Action: TBasicAction; var Handled: Boolean);
begin
  { Prevent execution of all actions in Application }
  Handled := True;
end;
void __fastcall TForm1::ApplicationExecuteAction(TBasicAction *Action,
    bool &Handled)
{
    // Prevent execution of all actions in Application 
    Handled = true;
}

If the application's OnExecute event handler does not handle the action, the action's OnExecute event handler fires.

You can use built-in actions or create your own action classes that know how to operate on specific target classes (such as edit controls). When no event handler is found at any level, the application next tries to find a target on which to execute the action. When the application locates a target that the action knows how to address, it invokes the action. See How Actions Find Their Targets for details on how the application locates a target that can respond to a predefined action class.

See Also