Show: Object Pascal C++
Display Preferences

Action Features Implemented in FireMonkey

From Appmethod Topics
Jump to: navigation, search

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).

Standard Action Classes dialog box

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_TMainMenu


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.

See Also

Application Samples

Personal tools
In other languages