What Happens When an Action Fires

When an event fires, a series of events intended primarily for generic actions occurs. Then if the event doesn't 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:

Copy Code

procedure TForm1.Action1Execute(Sender: TObject);
begin
{ Toggle Toolbar1's visibility }
ToolBar1.Visible := not ToolBar1.Visible;
end;

Copy Code

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:

Action list
Application
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:

Copy Code

procedure TForm1.ActionList1ExecuteAction(Action: TBasicAction; var Handled: Boolean);
begin
Handled := True;
end;

Copy Code

void __fastcall TForm1::ApplicationExecuteAction(TBasicAction *Action, bool &Handled)
{
  // Prevent execution of all actions in Application
Handled = true;
}

Copy Code

void __fastcall TForm1::ActionList1ExecuteAction(TBasicAction *Action, bool &Handled)
{
Handled = true;
}

If you don't 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 doesn't handle the action, the application's OnActionExecute event handler fires. If it handles the action, the application proceeds.

The global Application object receives an 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:

Copy Code

procedure TForm1.ApplicationExecuteAction(Action: TBasicAction; var Handled: Boolean);
begin
{ Prevent execution of all actions in Application }
Handled := True;
end;

If the application's OnExecute event handler doesn't 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.