Defines classes for Actions and lists of Actions for use in LCL components.

actnlist.pas contains classes which implements actions used in LCL components. The following components are added to the Lazarus IDE component palette:

Standard Tab

TActionList

Registered but not displayed:

TAction

Implements an Action class which has a category and parent action list.

TContainedAction is a TBasicAction descendant which allows an action to be given a category, and grouped with related actions. It provides additional properties and methods used to assign an action to the category and an associated list of actions. These values are used at design-time in the Action List editor.

TContainedAction is the ancestor for the TCustomAction class.

TBasicAction Reads properties and child components for the class instance.

ReadState is an overridden method in TContainedAction used to read values for the class instance during LCL component streaming. It calls the inherited method to read properties and child components using the specified TReader class instance. When the Parent in Reader is a TCustomActionList instance, it is stored in the ActionList property.

TComponent TReader.Parent TReader instance used to read values for the component. Sets the parent component for the class instance.

SetParentComponent is an overridden method used to set the property in the class instance which contains the parent component. It re-implements the method from the ancestor class.

In TContainedAction, it sets the ActionList property to the value in AParent when AParent is derived from TCustomActionList.

TComponent Value assigned to the parent component for the class. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. When ActionList has been assigned, its RemoveAction method is called to delete the current class instance.

Destroy calls the inherited method to free the class instance and unregister any action link clients.

TBasicAction.Destroy TComponent.Destroy Executes the action using a available OnExecute event handler.

Execute is an overridden method in TContainedAction. It checks for an available OnExecute event handlers in ActionList, the Application singleton, and the class instance. If an OnExecute event handler is not found, it posts a CM_ACTIONEXECUTE control message to the application.

TComponent.ExecuteAction TBasicAction.Execute True if the action was executed using one of the available execution options. Gets the parent component for the class instance.

GetParentComponent is an overridden method used to get the property in the class instance which is the parent component for the class instance. It re-implements the method from the ancestor class.

In TContainedAction, it gets the value in the ActionList property (when assigned) or calls the inherited method.

TComponent Parent component for the class instance, or Nil when not assigned. Indicates if a value has been assigned to the property with the parent component for the class instance.

HasParent is an overridden method in TContainedAction. It checks for an assigned value in the ActionList property, and sets the return value to True when assigned. Otherwise, the inherited method is called to get the return value.

TComponent.HasParent True when the parent component has been assigned. Signals an available OnUpdate event handler to update values in the Action. TBasicAction.Update True if an OnUpdate event handler was found and executed for the Action. The ActionList where the action is stored, and its parent component. Ordinal position for the action in ActionList. The Category of this action. Class type for TContainedAction instances. Implements an enumerator for the Actions in TCustomActionList.

TActionListEnumerator implements an enumerator for TContainedAction values stored in TCustomActionList. It allows navigation of values in the Actions property using the "for .. in" loop syntax. TActionListEnumerator is the type returned from the TCustomActionList.GetEnumerator method.

Constructor for the class instance.

Stores the value passed in AList to the member variable for the Actions property. Sets the value for the internal position member to -1.

Action list with the values for the enumerator. Moves to the next value for the enumerator. True if the next value was available. False when no more values exist for the enumerator. Current value for the enumerator.

Current is a read-only TContainedAction property with the current value for the enumerator. The property value is retrieved from Actions using the position in an internal member.

Specifies an event handler signalled to implement an action in TCustomActionList.

Arguments passed to the event handler include the Action for the notification and a return value that indicates if the action was executed.

TActionEvent is the type used for the OnExecute and OnUpdate properties in TCustomActionList.

TBasicAction for the event notification. True if the action was executed in the action list for t he handler. Represents state values for an action list.

TActionListState is the type used for the State property in TCustomActionList.

The action list is enabled, and can update and execute its actions. The action list is disabled, and the Enabled state for its actions is ignored. The action list is disabled, but the Enabled state for its actions is set to True. TCustomActionList - the ancestor class for TActionList.

TCustomActionList - the ancestor class for TActionList. If you want to define your own action list class, you should derive it from this class.

TActionList, TAction, TActionLink and TContainedAction are used to centralize the implementation of user commands, and can then be linked to the appropriate button, menu or another component. This is an Object-Oriented programming strategy to reuse the code, as opposed to the Event-Oriented approach of writing an OnClick event for each component.

Adds the specified action to the action list.

Sets the parent component for the action, and adds the value to the internal list for the component. Raises an Exception if the Action has already been added to the action list.

TContainedAction instance added in the method. Removes the specified action from the action list. TContainedAction instance removed from the action list. Performs action needed when the action list or one of its Actions has been changed.

Change signals the OnChange event handler (when assigned) to perform user-specified operations for the action list. Change also visits each of the Actions in the action list, and calls its Change method to signal the OnChange event handler supplied at the action level. It calls the OwnerFormDesignerModified routine at design-time to notify the form designer of the change to the action list.

Change is called when a new TCustomImageList value is assigned to the Images property in the action list.

OwnerFormDesignerModified Executes the specified procedure for each of the children in Actions. TComponent TGetChildProc Object procedure to execute for each of the children in the component. Not used in the method. Handles the notification performed when a component is added to or removed from the class instance.

Calls the inherited method on entry. Sets Images to Nil when the image list is removed from the component. Calls the RemoveAction method when AComponent is a TContainedAction instance removed from the component.

TComponent Component of the notification. Action performed for the specified component. Set the order for the specified child (Action).

SetChildOrder is an overridden method in TCustomActionList. It sets the ordinal position for the action in Component to the value specified in Order. The IndexOf method in Actions is called to get the current position for Component. The value in Order is assigned to the Index property in the TContainedAction when it exists in Actions. No actions are performed in the method when Component is not stored in the Actions for the action list.

TComponent Child component (action) re-order in the method. New position in the Actions list. Sets the value for the Images property. New value for the Images property. Event handler signalled when the action list has been changed. OnExecute - event handler for execution of the action. OnUpdate - event handler for updating the action. Constructor for the class instance.

Create is the constructor for TCustomActionList, and calls the inherited constructor.

Create allocates resources needed for members in the class instance, and assigns the OnChange event handler used in the internal TChangeLink instance when the Images property is altered.

Create sets the default value in the State property to asNormal.

TChangeLink.OnChange TComponent.Create Destructor for the class instance.

Destroy is the destructor for TCustomActionList. It frees the internal TChangeLink instance used in the class, frees any class instance and resources allocated to the Actions property.

Destroy calls the inherited destructor prior to exiting from the method.

TLCLComponent.Destroy TChangeLink Returns an action identified by its name (as a string). Examines and executes the specified Action.

ExecuteAction checks whether Action handles the current component, and if yes, calls the ExecuteAction method, passing itself as a parameter. The function returns True if the action handles the current component.

TComponent.ExecuteAction Examines and updates the target for the specified Action.

UpdateAction checks whether Action handles the current component, and if yes, calls the UpdateTarget method, passing itself as a parameter. The function returns True if the action handles the current component.

TComponent.UpdateAction Gets an enumerator for the action list. TActionListEnumerator instance for the class. The Index value of the name of this action in the ActionList. This action is associated with a shortcut. The indexed list of actions. The total number of actions in the actionlist. Image list with images for the actions. ImageList with the Images that can be associated with the actions in the list., e.g. in a Menu display. State of the action : Normal, Suspended or SuspendedEnabled. TActionList - The basic actions list class.

TActionList - The basic actions list class. TActionList is the last component on the "Standard" component palette on the Lazarus IDE.

To use an ActionList, click on the icon on the IDE Standard Components toolbar, then click anywhere on the main form and an ActionList icon will appear. It does not matter where you position it, because it is not visible at run-time.

You can add, remove or modify actions on the list by right-clicking on the ActionList icon on the form editor and then choosing "Edit action list...", or by double-clicking on the icon with the left mouse button. This will open the "Action List Editor".

You can now use the "+" and "-" buttons to add and remove actions. The ActionList editor menu allows you to select standard actions from a selection (option 'New Standard Action') or create a new action (option 'New Action'). To edit an action, click it and then open the object inspector. To add code to be executed when an action is triggered, double-click the action's name on the "Action List Editor".

The TActionList class introduces very few properties of its own, but inherits a lot from its ancestor, TCustomActionList, and related components TAction, TCustomAction, TContainedAction and TBasicAction.

Each entry in the ActionList appears in the Object Inspector as an instance of TAction, and its properties are accessible and modifiable from the Object Inspector.

TShortCutList - a list of shortcuts for actions in an ActionList. Gets the value for the indexed Shortcuts property. Value for the indexed property. Add a shortcut with the specified text to the list. TShortcut instance added in the method. Text for the shortcut. The index number of the shortcut in the list. The indexed list of short cuts. Specifies an event handler signalled to get the hint text for an action.

THintEvent is an object procedure type which specifies an event handler signalled to get the hint text for a TCustomAction instance. THintEvent is the type used for the OnHint property in TCustomAction.

TControl.OnShowHint TApplication.OnShowHint Returns the hint text for the action instance. Indicates whether the hint text can be displayed for the action. TCustomAction is the ancestor class for TAction.

TCustomAction is a generic class for all components that represent actions that can be be set on the user interface for buttons and other controls. TCustomAction is the ancestor for TAction. If you want to define your own action class, you should derive it from this class.

You can assign a action to a component by using the Object Inspector.

Copies property from the class instance to the specified persistent object.

AssignTo is the generic function to assign the class' contents to another class. This method must be overridden by descendent classes to actually assign the content of the source instance to the destination instance.

The implementation of Assignto raises an EConvertError exception. This is done for the following reason: If the source class doesn't know how to assign itself to the destination class (using AssignTo), the destination class may know how get the data from the source class (using Assign). If all descendent methods are implemented correctly, then if neither of the two classes knows how to assign their contents to each other, execution will end up at , which will simply execute.

Dest.AssignTo(Self);

If neither of the classes knows how to assign to/from each other, then execution will end up at the TPersistent implementation of AssignTo, and an exception will be raised.

Raises an EConvertError exception if the current class cannot be assigned to the persistent class instance in Dest. TPersistent Persistent object where property values are stored. Sets the value for the Name property.

SetName is overridden in TCustomAction. It calls the inherited method to ensure that Value is a valid identifier name for the component and its owner (when assigned). The inherited method may raise an EComponentError exception if the name in value is not a valid identifier. The new property value is also assigned to the Caption property in the action when the number of control clients is 0.

TComponent New value for the Name property. Returns True if there if the action is enabled and executed successfully. SavedEnabledState - if True, the Enabled state has been saved. Constructor for the class instance.

Create is the constructor for TCustomAction, and calls the inherited Create method. It initializes local variables in the class instance.

TBasicAction.Create Owner of the class instance. Destroy - destructor for TCustomAction: frees various lists and images, then calls inherited Destroy. TBasicAction.Destroy DoHint - method for displaying the hint contained in HintStr if True value is returned. True if hint is to be displayed. HintStr - the text-string for display as a hint. Executes the action using an available OnExecute event handler.

Execute is an overridden method in TCustomAction. It checks the State for the ActionList to ensure that it is not suspended. No actions are performed in the method when ActionList.State contains a value other than asNormal.

Execute calls Update to signal an available OnUpdate event handler in the ActionList, the Application singleton, or the class instance. It toggles the value in the Checked property when AutoCheck is enabled. The inherited Execute method is called when the class instance is Enabled.

The return value is True if the action was executed in the method.

TBasicAction.Execute True if action is to be performed. AutoCheck - whether the control (e.g. a CheckBox) is to be automatically checked. The Caption to be used if this action is associated with a visible component. Whether the CheckBox associated with the action is Checked (default False). Prevents the action from executing if an OnExecute handler is not assigned in the action.

Used in the Application message processing loop. Whn enabled, the action must hande have an OnExecute event handler, even if an associated action list OnExecute handler has been provided.

Enabled - whether this action is able to be used (default True). GroupIndex- Index of the action within its group. HelpContext - the index for a context-based help message. HelpKeyWord - the keyword of a context-based help message. HelpType - the sort of help message to be offered: default Context-based. Hint - a pop-up message that appears when the mouse hovers over an object. ImageIndex - the index number of the image to be associated with this action. ShortCut- an index to a shortcut list. SecondaryShortCuts - a stringlist containing shortcuts. Visible - is this action visible? (default True). OnHint - action to be taken when a hint is required. TAction is the basic action object used in the LCL.

TAction is the basic action object used in the LCL. It redeclares many properties inherited from TCustomAction on the public section, but does not add any new features. For more details look at the See Also section for TCustomAction.

The properties of each Action can be modified at design time in the Object Inspector.

Event called when action is executed.

OnExecute is the event triggered when the action is activated (executed). The event is triggered e.g. when the user clicks e.g. on a menu item or a button associated to the action. The application programmer should provide a OnExecute event handler to execute whatever code is necessary when the button is pressed or the menu item is chosen.

Note that assigning an OnExecute handler will result in the Execute method returning a True value. Predefined actions (such as dataset actions) will check the result of Execute and will not perform their normal task if the OnExecute handler was called.

Since version 1.1 setting OnExecute no longer sets the owner's OnClick. You can now specify an event for the action and a more specific OnClick for control and both are called. OnClick is called before OnExecute.

TBasicAction.OnExecute Event handler signalled to update an action when the application is idle.

OnUpdate is the event triggered when the application is idle, and the action is being updated. The OnUpdate event can be used to set the state of the action, for instance disable it if the action cannot be executed at this point in time.

TBasicAction.OnUpdate A link between an action and a client class.

The class definition includes a number of protected procedures for setting properties for the action (as defined in ), and a number of public boolean functions to indicate which part of the action is linked to the client.

SetAutoCheck - specifies the value of AutoCheck, whether True or False. SetCaption - specifies the string to be used as caption. SetChecked - specifies the value of the Checked property: True or False. SetEnabled - specifies the value of the Enabled property: True or False. SetGroupIndex - specifies the value for the Group Index. SetHelpContext - specifies the value to be used for context-sensitive Help. SetHelpKeyword - specifies the keyword to be used for Help. SetHelpType - specifies the type of Help to be used. SetHint - specifies the string to be used for Hints. SetImageIndex - specifies the index value for the image associated with the action. SetShortCut - specifies the shortcut for the action. SetVisible - specifies whether or not the control for the action is Visible. Is the action's Caption linked to the client? Is the action's Checked property linked to the client? Is the action's Enabled property linked to the client? Is the action's GroupIndex property linked to the client? Is the action's HelpContext property linked to the client? Is the action's Help property linked to the client? Is the action's Hint property linked to the client? Indicates if the action's ImageIndex property linked to the client. Is the action's ShortCut property linked to the client? Is the action's Visible property linked to the client? TActionLinkClass - class of TActionLink. Specifies a routine used to perform actions when enumerating actions.

TEnumActionProc is an object procedure type with the routine executed when enumerating actions. The type is passed as an argument to the EnumRegisteredActions routine, and used in the Lazarus IDE Action List editor.

Category name for the action in Info. Class type for the action in Info. Pointer to the action class instance. Registers the array of action classes using the specified category name.

RegisterActions is a procedure used to register the specified array of action class types. Category contains the category name for the action used to group related actions in an action list. Resource contains the optional class type for a resource used in the action classes.

RegisterActions calls RegisterActionsProc to perform the actions needed to register the action class types. An Exception is raised with the message in SInvalidActionRegistration if The RegisterActionsProc constant has not been assigned.

Category name for the actions. Array of action class types registered in the routine. Option resource class type for the actions. Unregisters the specified array of action class types.

Calls UnRegisterActionsProc to unregister the action class types.

Array of action class types unregistered in the routine. Enumerates the registered actions and calls a routine for values in Info. Routine called to process the values in Info. Pointer to the action(s) processed in the routine. Creates a new TBasicAction instance with the specified owner and class type.

CreateAction is a TBasicAction function used to create a new instance of the action class type in ActionClass with the TheOwner as the owner of the new class instance. Calls the CreateActionProc routine to create the new class instance. Raises an Exception with the message in SInvalidActionCreation if the CreateActionProc constant has not been assigned.

TBasicAction instance allocated in the routine. Component which owns the new class instance. Class type for the action instance created in the routine. Address of the routine used to register actions used in the action list editor. Address of the routine used to unregister actions used in the action list editor. Address of the routine used to enumerate actions in the action list editor. Address of the routine used to create a new action in the action list editor. Registers components for use in the Lazarus IDE.

Register is the procedure used to register components in the unit for use in the Lazarus IDE. The following components are added to the Lazarus IDE component palette:

Standard Tab

TActionList

Registered but not displayed:

TAction