FMX.ActnList.TActionLink

From RAD Studio API Documentation
Jump to: navigation, search

System.Actions.TContainedActionLinkSystem.Classes.TBasicActionLinkSystem.TObjectTActionLink

Delphi 

TActionLink = class(TContainedActionLink)

C++ 

class PASCALIMPLEMENTATION TActionLink : public System::Actions::TContainedActionLink

Properties

Type Visibility Source Unit Parent
class public
FMX.ActnList.pas
FMX.ActnList.hpp
 FMX.ActnList FMX.ActnList

Description

The action link connects an action to a client (a control, menu item, or tool button).

TActionLink extends TContainedActionLink by:

  • Providing implementations for methods setting values of client properties that are linked with action properties.


Special Behavior of Linking Among Properties of TCustomViewAction Action and Corresponding Properties of Clients

As implemented in TActionLink, several properties of TCustomViewAction actions does not linked with corresponding properties of clients. These are implemented in CheckedLinked, EnabledLinked, GroupIndexLinked, ShortCutLinked, VisibleLinked, and OnExecuteLinked properties. They returns False when an action assigned to a TActionLink action link belongs to TCustomViewAction. This means that changes of values of Enabled, Checked, GroupIndex, ShortCut, Visible, and OnExecute properties are not propagated to the corresponding properties of clients associated by the action link.

For actions do not belonging to TCustomViewAction, CheckedLinked, EnabledLinked, GroupIndexLinked, ShortCutLinked, VisibleLinked, and OnExecuteLinked properties return True; therefore, changes of values of Enabled, Checked, GroupIndex, ShortCut, Visible, and OnExecute properties are propagated to the corresponding properties of clients associated by the action link.


How and Why Action Links Are Used

When designing RAD Studio applications, the programmer typically assigns actions to clients (controls, menu items, tool buttons, or any other TFmxObject type components that support the Action property).

How to Assign an Action To a Client

At design time, you can make this assignment using the following algorithm:

  1. In the Form Designer, select your client component (an object that can be cast to the TFmxObject type). If the selected component has the published visibility of the Action property, then this property appears in the in the Object Inspector.
  2. In the Object Inspector, select the Action item and click the down arrow on the right. Choose the action you want to assign to the client.

At run time, you can simply assign the desired action to the Action (TFmxObject.Action) property of a client object.

How To Access an Action Property

Assigning or getting an action to or from the Action property is not a direct operation. The Action property has the following declaration: 

property Action: TBasicAction read GetAction write SetAction;

Notice that the TFmxObject class does not have an FAction field. The private setter SetAction and getter GetAction sets and retrieves, respectively, action values from the Action property of the proper TActionLink kind object. The setter and getter retrieve a TActionLink kind of object by calling GetActionLinkClass.

The core of the SetAction setter looks like this: 

 procedure TFmxObject.SetAction(const Value: TBasicAction);
 var
   lClass: TActionLinkClass;
 begin
    lClass := GetActionLinkClass;
    FActionLink := lClass.Create(Self);
    ActionLink.Action := Value;
 end;

Here: 

lClass: TActionLinkClass;

declares the lClass variable, whose value is the class reference for the TActionLink class or for one of its descendants. To understand this code, notice that the TFmxObject class declares the read-only ActionLink property, which is stored in the FActionLink field: 

property ActionLink: TActionLink read FActionLink;

The SetAction setter sets the ActionLink.Action property in the action link object associated with the client. This action link object is created and assigned to FActionLink by: 

FActionLink := lClass.Create(Self);

The following code retrieves the lClass class reference value: 

lClass := GetActionLinkClass;

GetActionLinkClass returns the associated action link class. To retrieve an Action, the client object calls GetAction: 

 function TFmxObject.GetAction: TBasicAction;
 begin
  if Assigned(FActionLink) then
    Result := FActionLink.Action
 end;

This example again uses the action link object stored in the FActionLink property. That is, client objects do not keep an associated action explicitly. The action is stored in the associated action link object. The getter GetAction and setter SetAction retrieve and set, respectively, an action from or to the Action property of this action link object. If GetActionLinkClass returns a non-nil value, then the action object is assigned to Action. If the control object does not support actions, then GetActionLinkClass should return nil. In this case, attempting to set a value to the Action property raises the following exception: 

StrEActionNoSuported = 'Class %s does not support the action'

Notice the ActionClient property: 

property ActionClient: boolean read FActionClient;

The ActionClient property depends on the value of Action:

  • If Action = nil then ActionClient = False. This means that this component object is not a client of any action.
  • If Action <> nil then ActionClient = True. This means that this component object is a client of some associated action. After changing of the ActionClient property, the virtual DoActionClientChanged method is called.


Note: Action link classes are an internal feature of RAD Studio. You do not need to use action link classes explicitly in an application, unless you create your own type of client components. If, for example, your client component has some new properties, then it needs that the proper action link object controls the states of these properties. Therefore, you may need to extend some action link class to handle these properties.

Code Examples

See Also

Retrieved from "https://docwiki.embarcadero.com/Libraries/Berlin/e/index.php?title=FMX.ActnList.TActionLink&oldid=762850"