Action Features Implemented in FireMonkey

Go Up to Actions in FireMonkey

Base action classes, with which user applications work, are in the FMX.ActnList.pas unit. Classes of standard actions are in the FMX.StdActns.pas files. These modules are in the FMX.dpk packages.

When creating new standard FMX actions, the programmer should, if possible, place them in FMX.StdActns.pas (also see FMX.ActnRes.pas).

FMX.ActnRes Unit

In the dclfmxstd.dpk package, the FMX.ActnRes unit is created as an analog to the ActnRes unit. This unit contains instances of standard actions with the specified default titles, shortcuts, and other properties that are used as the default values of properties when a new standard action is created in the Action List editor (see the image).

The FMX.ActnRes unit only keeps values, and should not contain any implementation of actions. This unit is not used in user applications, but only by the IDE's Action List editor, when it calls System.Actions.RegisterActions to register standard actions.

The FMX.ActnRes unit has the single TStandardActions class, which is the descendant of System.Classes.TDataModule.

Note: Developers should place standard actions with the properties defined by default, namely into the FMX.ActnRes unit.

Registering Actions in FireMonkey

You can register FMX actions in the same way as follows:

unit FmxReg;
...
Implementation
...
procedure Register;
begin
  ...
  { Standard action registration }
  RegisterActions('', [FMX.ActnList.TAction, TControlAction], nil);
  RegisterActions(SFileCategory, [TFileExit], TStandardActions);
  RegisterActions(SViewCategory, [TViewAction], TStandardActions);
end;

FMX.ActnList Unit

The FMX.ActnList unit contains the base classes for working with actions in FireMonkey.

TCustomActionList Class

The TCustomActionList class defines a list of actions that do not have published properties. This class contains the DialogKey method, which handles pressing of keyboard keys. This method sequentially calls similar methods from all actions in the list. If the pressed key corresponds to an operation shortcut, then handling of this operation is called and, if this handling is accomplished, then handling is terminated and True is returned.

TActionList Class

This class is intended for providing associations of actions with controls. This class is the common ancestor for all actions in FireMonkey.

TShortCutList Class

It defines a list of additional combinations of hot keys in FireMonkey. It provides the FMX implementation of the System.Actions.TCustomShortCutList class. The TShortCutList class inherits the published read-only field System.Actions.TCustomShortCutList.ShortCuts--a list of additional shortcuts. ShortCutList is created in the overloaded FMX.ActnList.TCustomAction.CreateShortCutList method.

TCustomAction Class

This class defines ordinary FireMonkey actions without published properties. All other action classes must be descendants of this class.

The most important members of the TCustomAction class:

Member	Description
Text	String property, the same as Caption. You can use both Text and Caption, but descendant classes should use only the Text published property, so that the Object Inspector shows only the Text property, as in most FireMonkey components.
CustomText	A user text. Some actions can, by default, automatically set the Text property. For example, in the TFileExit standard action, the Text property has the `Quit <Application.Title>` value; however, if you want to set a different value, you must set a value for the CustomText property.
ImageIndex	Now it is not supported. However, it is stored in fmx/dfm files if it is not equal to `-1`. The Object Inspector might not show this property.
IsSupportedInterface	Virtual method, which returns True (by default) if this action can be implemented on the current platform.
HideIfUnsupportedInterface	If this property is True, then the IsSupportedInterface function is used for retrieving the value of the Supported property. In this case, if IsSupportedInterface returns, then this action is always inaccessible and invisible. If the HideIfUnsupportedInterface property is False, then this action can be either visible or invisible, depending on other properties; a descendant or application should itself call IsSupportedInterface to retrieve the visibility and accessibility of the action.
UnsupportedArchitectures	Unsupported architectures. Can be set to `arIntelX86` and `arIntelX64`.
UnsupportedPlatforms	Unsupported platforms. Can be set to `pfWindows` and `pfMacOS`.
Supported	Read-only property that defines that the action can work on the current platform and CPU architecture. The value of this property is defined by the UnsupportedArchitectures and UnsupportedPlatforms properties and also by the IsSupportedInterface function. If Supported is False, then this action is always inaccessible and invisible.
ShortCutPressed	Read-only property that defines that the action handler is called by pressing a keyboard key, not by clicking a control.
Target	Read-only property that defines a component for which the action is executed. It can be nil. When several controls can be called with one shortcut, Target corresponds to the first matched control.

TAction Class

Ordinary action in FireMonkey. This class is used by default for creation of new actions. The System.Actions.TContainedAction.DisableIfNoHandler property is set to True during creation of an action, that is, the action is inaccessible if it does not have an OnExecute event handler.

FMX.Types Unit

IIsChecked Interface

It is used by actions for accessing the IsChecked property. All objects (TMenuItem, TcheckBox, and others) that support properties of the Checked kind must support this interface.

IGroupName Interface

It is used by actions to access to GroupIndex, GroupName, and other properties. The GroupName property is of the string type and it should keep an integer number. Otherwise, it is ignored and treated as 0.

TFmxObject Class

This class added some protected methods and properties. Descendants should provide overriding of virtual methods.

The most important members of the TFmxObject class:

Member	Description
InitiateAction	If the Action property is set, then its value is updated. Otherwise, nothing happens.
Action	The action that is used by an object.
ActionLink	An object of the class that performs linking between an object and an action. This object is created when a non-`nil` value is assigned to Action, and is destroyed when `nil` is assigned.
ActionChange	Virtual method that is called when the Action property of an object is changed.
GetActionLinkClass	Virtual method that should return a descendant of TActionLink. Objects of this class are created when a non-`nil` value is assigned to Action. If GetActionLinkClass returns `nil`, an exception is raised.
ActionClient	Read-only property. It specifies that the object uses an action. It is True when Action is non-`nil`, False otherwise. This property can be used for fast checking whether some action exists.

TControl Class

The Click virtual method is changed. If the Action property is set, EnableExecuteAction = True, and the OnClick event handler is not assigned (or is equal to Action.OnExecute), then the assigned action is executed, otherwise the OnClick event handler is executed.

Important! Component developers should not call the OnClick event handler explicitly; they should call the Click method.

if Assigned(onClick) then OnClick(self); // bad
inherited Click;                         // correct

The EnableExecuteAction property defines whether the control can use Action.OnExecute for mouse clicks. In descendants of TTextControl, this property is True, while in all others is False.

TCustomControlAction Class

Ordinary action, without published properties, that is used by controls. It can have additional properties from the set of properties that controls can have. Currently, the only additional property is PopupMenu. Unlike in TAction, during creation of an action, the DisableIfNoHandler property is set to False. That is, the accessibility of an action is not changed if the OnExecute event handler is not defined.

TControlAction Class

This class is similar to TCustomControlAction, but with published properties.

TCustomViewAction Class

This class does not have published properties. It is useful for creating commands in the View menu. It has the additional Component property. Use the ExecuteTarget method to set the Visible property to True. If Component is not set, but the OnCreateComponent event handler is defined, then the component is created.

If Component is a form, pane, or another similar object, then values of its IsChecked, GroupIndex, Enabled, OnExecute, and Visible properties are not linked with an action. That is, if you hide ViewAction, this does not entail automatic hiding of the form or pane. The programmer can manage its state in the OnUpdate event handler.

ComponentText is a virtual method that returns the corresponding text to the Component property. If this is a descendant of FMX.Forms.TCommonCustomForm, then Caption is returned. If this is a descendant of FMX.Controls.TTextControl, then Text is returned; in other cases Name is returned.

TControlActionLink Class

The TControlActionLink class is used by controls to link property values with actions. Functions of the IsCaptionLinked kind can be used to determine whether a property should be saved in an .fmx file. If IsCaptionLinked returns True, then the text of the control is the same as in the action; therefore, storing it is not necessary.

FMX.Forms Unit

TApplication Class

The most important members of the TApplication class:

Member Description

ActionUpdateDelay

Delay of all the actions' updating, in milliseconds (the default value is 100):

If ActionUpdateDelay > 0, then updating is managed by the timer.
If ActionUpdateDelay = 0, then updating executes directly in DoIdle.
If ActionUpdateDelay < 0, then no updating is executed.

You can also use the ActionUpdateDelayNever constant.

DoIdle

This method calls the OnIdle event handler. After that, the FIdleDone field is set to Done. Then, if FIdleDone is True, depending on the ActionUpdateDelay property, all actions' states are updated. The output field Done can be set to False in the event handler, for example, if the application is idle for a long time.

TCommonCustomForm Class

The most important members of the TCommonCustomForm class:

Member	Description
UpdateActions	Executes successive updates of the states of all actions in a form. Usually you do not need to call this method manually, because the Application object periodically executes this method for all forms.
GetActionLinkClass	Returns TFormActionLink, by default.

TFormActionLink Class

Forms use this class to link property values with actions. Unlike in the TControlActionLink class, TFormActionLink links only the Caption and Visible properties with actions.

FMX.Menus Unit

TMainMenu Class

The logic of this class working has changed. On MacOS, the first visible item of the main menu is always accessible, and it has the same text as the application title. That is, this is the system menu item. If no visible menu item exists, then the system menu item is created anyway and it contains the single subitem Quit <Application>. (In the image, it is Quit DemoView ^Q.) Using UnsupportedPlatforms, you can manage the visibility of menu items for different platforms.

FMX.StdActns Unit

This unit contains standard actions.

TFileExit Class

Handles closing of applications.

The most important members of the TFileExit class:

Member	Description
Text	A value of this property is set automatically. This property is not shown in the Object Inspector. The value can be either `Quit <Application.Title>` if `CustomText="`, or the `<CustomText>` stored in the CustomText property, otherwise.
CustomText	If the value of this property is set, then this value is used as the action Text.
OnCanActionExec	The event handler of this event can be used for confirmation that the user really wants to close an application. You can analyze the value of the ShortCutPressed property to define whether the event is activated by pressing a keyboard key or by mouse clicking.

TViewAction Class

This class is similar to TCustomViewAction, but with published properties.

The most important members of the TViewAction class:

Member	Description
FmxObject	This property points to an object, which executes an action and whose image becomes visible during the action execution.
OnCreateComponent	Only a TFmxObject type object can be created in the event handler of this event. If the created component is not a descendant of TFmxObject, then an exception is raised and a new object is destroyed.

TCustomValueRangeAction Class

It is the base class for actions (without published properties) that can be used by controls having the Value-type property, for example: TProgressBar, TCustomTrack, TCustomEditBox.

The ValueRange property keeps information about permitted ranges of floating-point values. See the FMX.StdActns.TCustomValueRange class.

IValueRange Interface

Each control that uses the TCustomValueRangeAction class must support this interface. IValueRange is used by an action for accessing the ValueRange property.

TBaseValueRange Class

This class associates a floating-point number Value to its ranges. This class only keeps data, it does not check whether a stored Value is acceptable.

The most important members of the TBaseValueRange class:

Member	Description
Min	Minimum permissible value.
Max	Maximum permissible value.
Value	A changeable floating-point parameter.
ViewportSize	Used by controls like TScrollBar to define the thumb size. Notice that the effective maximum value of Value is decreased according to `Max - ViewportSize`.
Frequency	The step of possible Value variations. Value can be multiple of Frequency, Min, or Max. For example, if Min = 0.1 Max = 2.1 ViewportSize = 0 Frequency = 1 then Value can be: 0.1 1 2 2.1 It cannot be Value = 1.1
Equals	Checks whether the values of all properties of the current `Obj` object are exactly equal to the values of the corresponding properties of the specified object. The function returns True if the values of all properties of the current object are equal to the values of the corresponding properties of `Obj`.
Same	Checks whether the values of all properties of the current object are close to the values of the corresponding properties of the specified `Obj` object. This function is similar to Equals, but it uses the SameValue function to compare values. That is, if between the values is a difference that is less than the possible rounding error, then the SameValue function estimates the values as equal and Same returns `True`.

TCustomValueRange Class

TCustomValueRange is the descendant of TBaseValueRange. It not only stores Value, but also provides features to control the correctness of Value. For example, if you set Max value so that Value > Max, then Value is changed to Value = Max.

The most important members of the TCustomValueRange class:

Member	Description
IsEmpty	Returns True, if all properties (Min, Max, Value, and so on) have the default values.
Clear	Assigns the default values to all properties (Min, Max, Value, and so on).
Tracking	If `Tracking = True`, then the BeforeChange and AfterChange] events are fired on each changing of any property. If `Tracking = False`, then the BeforeChange and AfterChange events are not raised.
IsChanged	Specifies that some properties have been changed, but values still are not recalculated.
Changed	This method is called immediately after the value of any property has been changed. It recalculates values, raises proper events (if needed), and sets IsChanged to False. If the Owner component of an action is loading or `UpdateCount > 0`, then no activities are produced and IsChanged is set to True. After loading is finished, the control should check the IsChanged property's value and call the Changed method (if needed).
New	Is the TBaseValueRange type property that keeps new values of properties declared in the TBaseValueRange class (Max, Min, Value, Frequency, and ViewportSize). It can be used in the BeforeChange event handler.
RelativeValue	This property is calculated relatively to `Value`, according to the following expression RelativeValue = (Value-Min)/(Max-Min-ViewportSize) It can be in the range from 0 through 1. It can be used for positioning a thumb in a control.
Owner	The owner component of this class instance.
BeginUpdate	Begin of updating.
EndUpdate	End of updating.
UpdateCount	Counter of how much times update changes have been started. If `UpdateCount > 0`, then no update changes will be actually implemented until the EndUpdate method that sets `UpdateCount = 0` is called. All Max, Min, Value, Frequency, and ViewportSize properties will have old values. To set new values to these properties, use the New property.
Changing	This property identifies that a TCustomValueRange type object is in the state of recalculation of values.
BeforeChange	This event is fired before new values of parameters become effective. For example, `Min` still contains an old value, while the new value is only in the `New.Min` parameter. The BeforeChange event is fired if `Tracking = True`.
OnChanged	This event is fired after a value of any parameter has changed, independently from the `Tracking` value.
AfterChange	This event is fired after a value of any parameter has changed, but only when `Tracking = True`.
OnTrackingChange	This event is fired after a value of the `Tracking` parameter has changed, independently from UpdateCount.
DoBeforeChange DoChanged DoAfterChange DoTrackingChange	These virtual methods fire corresponding events. If you create descendent classes, then you can override these methods instead of assigning corresponding event handlers.
MaxStored MinStored ValueStored FrequencyStored ViewportSizeStored	These virtual functions return True if the corresponding property value differs from the default.

TValueRange Class

This class is similar to TCustomValueRange, but with published properties.

Application Samples

FMX.ActionsDemo Sample