• Menus
• Toolbar controls (buttons, picklists)
• Popup menus

Typically, a particular action will be assigned to several related controls. For instance, Copy may be assigned to a menu selection, a toolbar button, and a pop-up menu selection (activated when you right click a control). By default, double clicking on the OnClick property of each control will create a separate method.

TForm1.Edit_CopyClick(Sender: TObject)
TForm1.Copy_UIButtonClick(Sender: TObject)
TForm1.Popup_Menu_CopyClick(Sender: TObject)

TForm1.CopyText(Sender: TObject)

Caption, Enabled, Visible, Checked, OnClick ...

• Adding an Action List component to your form (from the Standard palette)
• Add pre-defined or new actions to the list
• Reference the actions from their associated controls

• On the Standard palette, select the ActionList component and place that on the form.
• On the Win32 palette, select the ImageList component and place that on the form.
• In the Object Inspector, set the ActionList1.Images property to the ImageList.
• On the form, double click the ActionList component (this opens a dialog box).
• In the dialog box, there is only one active control on the toolbar - click on the down arrow next to it and select New Standard Action....
• Double click to select one action, or use the ctrl and/or shift keys to select several actions and click ok. This adds the actions to the list of available actions.
• Select a control on the form that has an action property - such as a Button or Menu option. Click the down arrow next to the action property and select one of the actions.

There are minor variations for other Delphi versions.

To begin, all Actions must be based on TBasicAction (an abstract class with many virtual methods), but they should be derived from TAction (which, itself, descends from TBasicAction).

The call sequence for executing an Action is pretty involved, and you should read the help for full details. What I am going to describe here is stripped down to the essentials.

When a menu option (or button or whatever) is clicked, Delphi looks in the ActionList for an Action with the same name as the Menu.Action property (this actually takes place at design time) and calls Action.Execute. The TContainedAction default for this calls many routines until one returns True. Eventually, the form calls the active control’s ExecuteAction method with the Action component as the parameter. (This example is from Classes.pas)

function TComponent.ExecuteAction(Action: TBasicAction): Boolean;
begin
  if Action.HandlesTarget(Self) then
  begin
    Action.ExecuteTarget(Self);
    Result := True;
  end
  else Result := False;
end;

function TComponent.UpdateAction(Action: TBasicAction): Boolean;//!
begin
  if Action.HandlesTarget(Self) then
  begin
    Action.UpdateTarget(Self);
    Result := True;
  end
  else Result := False;
end;

These are some of the default virtual methods for TBasicAction (in classes.pas).

function TBasicAction.HandlesTarget(Target: TObject): Boolean;
begin
  Result := False;
end;

procedure TBasicAction.ExecuteTarget(Target: TObject);
begin
end;

procedure TBasicAction.UpdateTarget(Target: TObject);
begin
end;

Basically, set Enabled and other parameters in UpdateTarget.

procedure TAction_mcFileSave.UpdateTarget (Target: TObject);
begin
  if (Control <> nil) and (Control.FFilename <> '') then
    Enabled := true
  else
    Enabled := false;
end;

If you want control over the default menu caption, you can override Create and set Caption.

constructor Create(AOwner: TComponent); override;

constructor TAction_mcFileSaveAs.Create(AOwner: TComponent);
begin
  inherited Create(AOwner);
  Caption := 'Save&As...';
end;

TAction is defined in actnlist.pas. Several examples are defined in stdactns.pas.

This is the relevant code (from forms.pas).

function TApplication.DispatchAction(Msg: Longint; Action: TBasicAction): Boolean;
var
  Form: TCustomForm;
begin
  Form := Screen.ActiveForm;
  Result := (Form <> nil) and (Form.Perform(Msg, 0, Longint(Action)) = 1) or
    (MainForm <> Form) and (MainForm <> nil) and
    (MainForm.Perform(Msg, 0, Longint(Action)) = 1);
  { Disable action if no "user" handler is available }
  if not Result and (Action is TCustomAction) and TCustomAction(Action).Enabled and
     TCustomAction(Action).DisableIfNoHandler then
    TCustomAction(Action).Enabled := Assigned(Action.OnExecute);
end;

TApplication.Run / TApplication.HandleMessage / TApplication.Idle / TApplication.DoActionIdle / TCustomForm.UpdateActions / TControl.InitiateAction / TBasicActionLink.Update / FAction.Update (Assy) / SendAppMessage / SendMessage (Assy) / WndProc / TApplication.DispatchAction

It should be noted that FAction.Update is followed by calls to Assembly code, TApplication.UpdateAction and TBasicAction.Update before SendAppMessage is called. However, the way this works is not obvious to me.

Interestingly, UpdateTarget is called via one of the 2 Preform commands in TApplication.DispatchAction (I'm not sure which one).

TApplication.DispatchAction / TControl.Perform (Assy) / TCustomForm.CMActionUpdate (Assy) / TComponent.UpdateAction (calls Action.HandlesTarget) / TComponent.UpdateTarget

This is also relevant (from classes.pas).

function TBasicAction.Execute: Boolean;
begin
  if Assigned(FOnExecute) then
  begin
    FOnExecute(Self);
    Result := True;
  end
  else Result := False;
end;

In order to collect this information, I had to enable the use of Debug DCUs - Project / Options... / Compiler / Use Debug DCUs - which allows you to step through the VCL files.

Loaded overrides the inherited method in order to initialize the control from its associated Action. To change the properties the control copies from its action, override the ActionChange method.

// from classes.pas
  // It just disables the Loading bit in the State flag (aka a Set)
procedure TComponent.Loaded;
begin
  Exclude(FComponentState, csLoading);
end;

// from controls.pas
procedure TControl.Loaded;
begin
  inherited Loaded;
  if Action <> nil then ActionChange(Action, True);
  UpdateAnchorRules;
end;

procedure TControl.ActionChange(Sender: TObject; CheckDefaults: Boolean);
begin
  if Sender is TCustomAction then
    with TCustomAction(Sender) do
    begin
      if not CheckDefaults or (Self.Caption = '') or (Self.Caption = Self.Name) then
        Self.Caption := Caption;
      if not CheckDefaults or (Self.Enabled = True) then
        Self.Enabled := Enabled;
      if not CheckDefaults or (Self.Hint = '') then
        Self.Hint := Hint;
      if not CheckDefaults or (Self.Visible = True) then
        Self.Visible := Visible;
      if not CheckDefaults or not Assigned(Self.OnClick) then
        Self.OnClick := OnExecute;
    end;
end;

procedure TWinControl.ActionChange(Sender: TObject; CheckDefaults: Boolean);
begin
  inherited ActionChange(Sender, CheckDefaults);
  if Sender is TCustomAction then
    with TCustomAction(Sender) do
    if not CheckDefaults or (Self.HelpContext = 0) then
      Self.HelpContext := HelpContext;
end;

// from comctrls.pas
procedure TToolButton.ActionChange(Sender: TObject; CheckDefaults: Boolean);
begin
  inherited ActionChange(Sender, CheckDefaults);
  if Sender is TCustomAction then
    with TCustomAction(Sender) do
    begin
      if not CheckDefaults or (Self.Down = False) then
        Self.Down := Checked;
      if not CheckDefaults or (Self.ImageIndex = -1) then
        Self.ImageIndex := ImageIndex;
    end;
end;

// from stdctrls.pas
procedure TButtonControl.ActionChange(Sender: TObject; CheckDefaults: Boolean);
begin
  inherited ActionChange(Sender, CheckDefaults);
  if Sender is TCustomAction then
    with TCustomAction(Sender) do
    begin
      if not CheckDefaults or (Self.Checked = False) then
        Self.Checked := Checked;
    end;
end;

  TAction_mcFileExit = class(TAction)
  public
    constructor Create(AOwner: TComponent); override;
    function  HandlesTarget(Target: TObject): Boolean; override;
    procedure ExecuteTarget(Target: TObject); override;
  end;

  procedure Register;

implementation

procedure Register;
begin
  RegisterActions('mcFileExit', [TAction_mcFileExit], nil);
end;

Basically, there are 2 ways to add the unit (*.pas file) to an existing package.

• Open the existing package, add the unit, select compile.
• From the Delphi 5 menu select Component / Install Component.... In the dialog box, enter the Unit file name (*.pas file) and the Package file name. When you click ok, you will be prompted if you want to recompile the *.bpl file - just click yes.

TEditCopy	Copies highlighted text to the Clipboard
TEditCut	Cuts highlighted text from the target to the Clipboard
TEditPaste	Pastes text from the Clipboard to the target
TEditDelete	Deletes the highlighted text
TEditSelectAll	Selects all the text in the target edit control
TEditUndo	Undoes the last edit made to the target edit control.

All of these actions are based on TEditAction which ensures that the target control is based on the TCustomEdit class and that it currently has the focus. (Implemented via the HandlesTarget method.)

For examples, see

C:\Program Files\BORLAND\Delphi5\Source\Vcl\stdactns.pas

In Windows programs, it is fairly common to provide a Toggle Button on the toolbar and to provide a second way to perform the same action - perhaps a menu option which allows a check mark. (When possible, there should always be a way to control a program using only the keyboard.) For instance, suppose that a toolbar has a toggle button. Also suppose that the menu has a related selection which contains a checkmark. However, because the button position is controlled via the Down property and the Menu check mark is controlled via the Checked property, you will need to provide extra code to synchronize the control states. Typical code to handle this might be

Menu_Edit_Check.Checked := not Menu_Edit_Check.Checked;
UISpeedButton.Down      :=     Menu_Edit_Check.Checked;

The TToolbar component provides a TToolButton which also implements this capability. Just set the Style property to tbsCheck.

When you create your own action, you must verify that the target components have a property (such as Enabled or Checked) before you set it.

Parts of the Action code are executed at design time. This way, if you set one of the linked properties, all realeated controls will have the same property value.

By default, if a new TAction is added without an OnExecute method, the associated components automatically have Enabled set to false.

FileAccessObject

To perform an action, xxx.FileAccess must be set
to an object of type TFileAccessObject (or a descendant).

If Object is set, then the default extension and read/write
actions are used, otherwise, OnRead and OnWrite must be set.

Any edit field, .txt .ini 
image, .bmp, .jpg

This notifies the remote control that this control has a pointer (ie, that its Notification method must be called when the remote control is destroyed).

if Ctrl <> nil then Ctrl.FreeNotification(Self);

procedure TEditAction.Notification(AComponent: TComponent;
  Operation: TOperation);
begin
  inherited Notification(AComponent, Operation);
  if (Operation = opRemove) and (AComponent = Control) 
    then Control := nil;
end;

Somehow (I still haven't found it in the source code), the Delphi standard actions add images to the ImageList (win32 / ImageList) associated with TActionList.Images. Then, when those actions are associated with various components, the component's image (or glyph) is automatically assigned.

For example, when the EditCut action is added to a SpeedButton, the Glyph property is automatically set to a pair of scissors. (Simply changing the action will not change the glyph. To automatically assign a new glyph, first delete (clear) the existing glyph, then set the new action.)

It is important to add the ImageList to the ActionList before any actions are added to the ActionList. You should also associate the same ImageList with your MainMenu component before any of the MenuItem actions are set.

Kudzu explains that the image, and other default values, are associated with actions by defining a form that contains your actions and a TImageList. Then you set the actions' default values, place images in the list, and assign the list index. To use this,

• Add the form to the package
• Set the resource parameter of the RegisterActions command to the form name

Note:

According to the Delphi developer team (via Delphi by Design), you should actually use a TDataModule (File / New... / Data Module) to hold the ActionList and ImageList components. At any rate, both Forms and Data Modules work and both are stored as *.dfm files.

When creating your own images

• They must be 16x16 bitmaps. (I prefer 16 color images.)
• These can be created via Tools / Image Editor.
• As a test, I double clicked an ImageList with contained several action images and Exported a bitmap. I was unable to edit it using Tools / Image Editor - too many colors - they contained 16 bits per pixel.
• You can edit and save an exported bitmap with Start / Programs / Accessories / Paint.

According to the help file, Delphi 6 does not automatically load the images for the selected images - instead, with the Personal edition you must add each one manually, with the Enterprise and Professional editions, you need to manually copy a special ImageList component from Delphi6\Source\Vcl\ActnRes.pas and then you need to manually set the ImageIndex property for each action. Delphi 5's method seems much better to me.

Though the 3 properties mentioned above can be set either way - Create constructor or *.dfm file - the ImageIndex property should be set using an *.dfm file.

What's weird here is that if an image is associated with a registered Action (via an *.dfm file), and the ActionList in the current form is associated with an ImageList, then the image is copied from the *.dfm file to the form's ImageList and the Action's ImageIndex property is set to this image. (Notice that the two ImageIndex's - the one in the current form and the one used when the action was registered - will normally be different. Delphi performs this conversion automatically.)

In general, leave the Category property alone - it is initialized based on the parameter used to register the action.

Note:

According to the Delphi developer team (via Delphi by Design), when creating Actions that will be Registerd, you should use a TDataModule (File / New... / Data Module) to hold the ActionList and ImageList components. Because the author was not aware that images could be associated with registered Actions (perhaps Delphi 4 did not support this feature), he suggests that using the constructor makes more sense (because that is how other objects are initialized).

If you use a form, be sure to change its name from Form1

When you set a form's name to FormName, Delphi automatically derives a type of TFormName. You will use this type name in the register command.

You can not place your Actions on a form (or DataModule) until they are registered

That's right, you must first register your actions, then place them on the form, associate them with images, set the default values, and then register them a second time. This is an iterative process.

Be sure to always un-register an action before registering it a second time

If this is not done, then you will get multiple copies of your actions in the pick list of Standard Actions.

Include the form with the initial values in the same package as the Actions

You will also have to include it in the uses clause where the Actions are defined

Always check the default values

Several times, I made changes, saved everything, and re-compiled the package only to discover that some of the changes were not available. If this happens, just close and re-open Delphi, then re-compile the package again.

User-defined published properties can not be initialized this way

procedure Register;
begin
  RegisterComponents('mc', [TmcFile_IO]);
  unRegisterActions( [TAction_mcFileOpen, TAction_mcFileSave,
                      TAction_mcFileSaveAs,
                      TAction_mcFileNew, TAction_mcFileSaveAll]);
  RegisterActions('mcFile_IO', [TAction_mcFileOpen, TAction_mcFileSave,
                      TAction_mcFileSaveAs,
                      TAction_mcFileNew, TAction_mcFileSaveAll],
                   TmcActionImages);
end;

• Place the Win32 / ToolBar component on the form.
• In the Object Inspector, set the ToolBar1.Images property to the same ImageList used with the ActionList.
• Right click the ToolBar and select New Button and/or New Separator. (Ignore the icons, they will be changed when you assign the actions.)
• Set the button's Action property.

Delphi 6 Professional provides additional action components that support drag and drop capabilities. For instance, dragging a group of actions to an ActionMainMenuBar will actually create the menu options. Dropping actions on an ActionToolBar will create the buttons.

There are also components to save the state when a user redefines the toolbars.

References:

• ActionBands information including an ActionBands Tutorial

I do not suggest writing Actions based on these instructions and the help alone. You really should refer to the Delphi source files (which do not ship with the Standard edition).

• Delphi 6 adds some new Action components. Among other things, they support drag-n-drop to build menus and toolbars, and save the state when a user redefines the toolbars. - ActionBands information including an ActionBands Tutorial

• Here is an Action tutorial that will walk you through some of the steps. Contains very good annotated screen shots.

URL: http:// cpcug.org / user / clemenzi / technical / Languages / Delphi / UserInterfaceDesign.html