Client-side interface to a PixInsight module-defined action object. More...

#include <Action.h>

Inheritance diagram for pcl::Action:

Public Member Functions
	Action (Action &&x)

	Action (const String &menuItem, const IsoString &iconSVGSource, int, const String &toolBar=String())

	Action (const String &menuItem, const String &iconSVGFile=String(), const String &toolBar=String())

	~Action () override

void	EnsureUnique () override

virtual void	Execute ()

void	GetAccelerator (int &keyModifiers, int &keyCode) const

bool	HasAccelerator () const

Bitmap	Icon () const

virtual bool	IsEnabled (ActionInfo info) const

String	MenuItem () const

String	MenuText () const

Action &	operator= (Action &&x)

void	RemoveAccelerator ()

void	SetAccelerator (int keyModifiers, int keyCode)

void	SetIcon (const Bitmap &icon)

void	SetIconSVG (const IsoString &svgSource)

void	SetIconSVGFile (const String &filePath)

void	SetMenuText (const String &text)

void	SetToolTip (const String &tip)

String	ToolBar () const

String	ToolTip () const

Public Member Functions inherited from pcl::UIObject
virtual	~UIObject () noexcept(false)

bool	IsAlias () const

bool	IsGarbage () const

bool	IsNull () const

bool	IsSameObject (const UIObject &o) const

bool	IsUnique () const

String	ObjectId () const

IsoString	ObjectType () const

bool	operator< (const UIObject &o) const

bool	operator== (const UIObject &o) const

size_type	RefCount () const

void	SetObjectId (const String &id)

Static Public Member Functions
static Action &	Null ()

Static Public Member Functions inherited from pcl::UIObject
static UIObject &	Null ()

Additional Inherited Members
Protected Member Functions inherited from pcl::UIObject
	UIObject ()=default

	UIObject (const UIObject &x)

	UIObject (UIObject &&x)

UIObject &	operator= (const UIObject &x)

UIObject &	operator= (UIObject &&x)

Detailed Description

Module-defined actions manage integration of external processes and tools with the main menu and tool bars of the PixInsight core application.

Integration of actions is governed by two main properties: menu item and tool bar.

Menu Item

This is a string indicating a menu item where an action will be integrated within the PixInsight's main menu structure.

The menu item string describes a path on PixInsight's main menu structure. Multiple menu items can be specified, separated with the ">" character.

If this parameter is an empty string, the newly created action won't be integrated with the main menu. This can be useful for actions that only respond to keyboard accelerators, or actions that only integrate with tool bars (see the Tool Bar section below).

Integrating actions into existing top-level main menu items

"Image >> Geometry > Rotate 180 degrees" "View > Memory Status"

The above strings will integrate actions into existing top-level main menu items (Image and View, respectively). In the first example, a submenu entitled "Geometry" will be created under the Image top-level menu item, if it doesn't exist yet. The sequence '>>' can be used to insert a separator menu item, as has been done before "Geometry" in the example above. Then a new item "Rotate 180 degrees" will be created and associated to the corresponding action. Note that in this case the PixInsight core application decides where exactly new actions are inserted within existing menu items, applying different criteria for each menu. In general, in these cases new actions are inserted on a per-module basis, in strict order of creation.

Creating custom top-level main menu items

Custom main menu top-level entries can also be created. For example, the following menu item string:

"MyTools > Color Tools > A better color saturation process"

Will create a new custom "MyTools" top-level item in the main menu, if it doesn't already exist. Custom top-level main menu items are inserted after the standard Process menu item, in strict order of creation. Common sense and care must be observed when creating custom top-level menu items. If possible, it is always preferable to integrate actions into existing top-level items; one must be motivated by a really strong reason to create a custom menu.

Tool Bar

This is an optional parameter. This is the name of a tool bar where the action will be integrated.

If this string is empty, the action will not be integrated in a tool bar. Otherwise, the string must be the name of a tool bar where a new tool button will be created and associated to the action.

A standard tool bar name can be used (i.e. View, File, and so on). If the specified name does not correspond to an existing tool bar, a new, custom tool bar will be created, and a new tool button corresponding to this action will be added to it.

The specified tool bar name can start with a ">" character to insert a tool bar separator (a vertical or horizontal line, depending on the tool bar's orientation) before the newly created tool button.

Definition at line 173 of file Action.h.

Constructor & Destructor Documentation

◆ Action() [1/3]

pcl::Action::Action	(	const String &	menuItem,
		const String &	iconSVGFile = `String()`,
		const String &	toolBar = `String()`
	)

Constructs a new Action object.

Parameters

menuItem	Specifies the menu item that will be associated with this action.
iconSVGFile	Path to an existing file in the local file system, which must store a valid SVG document defining the icon image that will be associated with this action. The SVG source code must be encoded in UTF-8. The icon will be used for menu items and tool bar buttons associated with this action. If this parameter is not specified, or if the specified SVG document does not exist, is not valid, or cannot be rendered, no icon will be used to represent this action.
toolBar	The name of a tool bar where this action will be integrated. If this parameter is not specified, the action will not be integrated in a tool bar.

Automatic Resource Location

The specified iconSVGFile string can be prefixed with the "@module_icons_dir/" special token to let the PixInsight core application load the corresponding SVG document automatically from the a standard distribution directory. See the documentation for MetaProcess::IconImageSVGFile() for complete information.

To learn how the menu item and tool bar parameters work for actions, see the description of the Action class.

◆ Action() [2/3]

pcl::Action::Action	(	const String &	menuItem,
		const IsoString &	iconSVGSource,
		int	,
		const String &	toolBar = `String()`
	)

Constructs a new Action object.

Parameters

menuItem	Specifies the menu item that will be associated with this action.
iconSVGsource	The source code of a valid SVG document defining the icon image that will be associated with this action. The SVG source code must be encoded in UTF-8. The icon will be used for all menu items and tool bar buttons associated with this action. If this parameter is not specified, or if the specified SVG document is not valid or cannot be rendered, no icon will be used to represent this action.
toolBar	The name of a tool bar where this action will be integrated. If this parameter is not specified, the action will not be integrated in a tool bar.

Note: The unused third int parameter serves to distinguish this constructor from the other one that takes a file path argument. This is necessary because both String and IsoString can be constructed from literal const char* arguments.

To learn how the menu item and tool bar parameters work for actions, see the description of the Action class.

◆ Action() [3/3]

pcl::Action::Action ( Action && x )

inline

Move constructor.

Definition at line 278 of file Action.h.

◆ ~Action()

pcl::Action::~Action ( )

inlineoverride

Destroys this Action object.

This destructor does not destroy the actual action object, which is part of the PixInsight core application. Only the managed alias object living in the caller module is destroyed.

Definition at line 289 of file Action.h.

Member Function Documentation

◆ EnsureUnique()

void pcl::Action::EnsureUnique ( )

inlineoverridevirtual

Ensures that the server-side object managed by this instance is uniquely referenced.

Since actions are unique objects, calling this member function has no effect.

Reimplemented from pcl::UIObject.

Definition at line 309 of file Action.h.

◆ Execute()

virtual void pcl::Action::Execute ( )

virtual

Callback routine for this action. This function will be called each time this action is activated, either by selecting the associated menu item or by clicking the corresponding tool button.

Despite this function has not been formalized as a pure virtual function, it is such conceptually, so it must be always reimplemented in descendant classes.

◆ GetAccelerator()

void pcl::Action::GetAccelerator	(	int &	keyModifiers,
		int &	keyCode
	)		const

Obtains the optional keyboard accelerator associated to this action.

Parameters

[out]	keyModifiers	Specifies an OR'ed combination of the Shift, Control and Alt keys. Use the KeyModifier namespace, defined in the pcl/ButtonCodes.h header, to decode this value.
[out]	keyCode	Any valid PCL key code, except those codes corresponding to modifier keys or system-managed keys. Use the KeyCode namespace, defined in the pcl/KeyCodes.h header, to decode the returned value.

If no keyboard accelerator has been associated to this action, zero is returned for both parameters.

See also: SetAccelerator(), HasAccelerator(), RemoveAccelerator()

◆ HasAccelerator()

bool pcl::Action::HasAccelerator ( ) const

inline

Returns true iff this action has an associated keyboard accelerator.

See also: GetAccelerator(), SetAccelerator(), RemoveAccelerator()

Definition at line 406 of file Action.h.

◆ Icon()

Bitmap pcl::Action::Icon ( ) const

Returns a Bitmap corresponding to the icon that has been assigned to this action object. Action icons are used to render the associated menu items and tool bar buttons.

If no icon has been associated to this object, a null Bitmap object is returned.

See also: SetIcon()

◆ IsEnabled()

virtual bool pcl::Action::IsEnabled ( ActionInfo info ) const

inlinevirtual

Returns the current enabled state of this Action object.

Disabled actions have their associated menu items and tool bar buttons disabled, and cannot be activated by the user.

The PixInsight application will call this function repeatedly to learn the current state of this action, with the purpose of keeping the associated interface elements up-to-date.

The caller of this function is a specialized idle-priority thread that is permanently running in the background. This means that this function will not be executed in the core application's main GUI thread, so all code in this function must be thread-safe. Reimplementations of this function in derived classes should decide the action's current state and return as quickly as possible.

An ActionInfo structure is passed to this function, describing the current state of the user interface. That description should be used by the IsEnabled() function to decide whether this action should be enabled or disabled, depending on the current interface context.

Note: The default implementation of this function always returns true, regardless of the current context. This means that all actions are enabled by default.

See also: ActionInfo

Definition at line 563 of file Action.h.

◆ MenuItem()

String pcl::Action::MenuItem ( ) const

Returns the menu item where this action has been integrated in the main menu of the PixInsight core application.

An action's menu item is a read-only property: its value can only be set with the constructor. In other words: Once an action has been created, its menu text can be freely changed, but it cannot be moved in the main menu structure.

See also: MenuText()

◆ MenuText()

String pcl::Action::MenuText ( ) const

Returns the text of the menu item where this action has been integrated in the main menu of the PixInsight core application.

See also: SetMenuText(), MenuItem()

◆ Null()

static Action& pcl::Action::Null ( )

static

Returns a reference to a null Action instance. A null Action does not correspond to an existing action in the PixInsight core application.

◆ operator=()

Action& pcl::Action::operator= ( Action && x )

inline

Move assignment operator. Returns a reference to this object.

Definition at line 296 of file Action.h.

◆ RemoveAccelerator()

void pcl::Action::RemoveAccelerator ( )

inline

Clears (deactivates) the keyboard accelerator associated to this action, if any. This is an overloaded function, provided for convenience. It is equivalent to SetAccelerator( 0, 0 ).

See also: GetAccelerator(), SetAccelerator(), HasAccelerator()

Definition at line 418 of file Action.h.

◆ SetAccelerator()

void pcl::Action::SetAccelerator	(	int	keyModifiers,
		int	keyCode
	)

Changes the keyboard accelerator associated to this action.

Parameters

keyModifiers	An OR'ed combination of the Shift, Control and Alt keys. Use the KeyModifier namespace, defined in the pcl/ButtonCodes.h header, to build this value.
keyCode	A valid PCL key code, except those codes corresponding to modifier keys or system-managed keys. Use the KeyCode namespace, defined in the pcl/KeyCodes.h header, to build this value. If this parameter is zero, no keyboard accelerator will be associated to this action.

See also: GetAccelerator(), HasAccelerator(), RemoveAccelerator()

◆ SetIcon()

void pcl::Action::SetIcon ( const Bitmap & icon )

Changes the icon associated with this Action object.

Parameters

icon	The new icon Bitmap that will be assigned to this Action.

The new icon will be used for all menu items and tool bar buttons associated with this action after calling this function. If a null bitmap is specified, no icon will be used to represent this action.

Deprecated:: This member function has been deprecated since core version 1.8.8-6. It is still available for compatibility with existing modules that depend on it, but it will be removed in a future version of PCL. All newly produced code must use the SetIconSVG() or SetIconSVGFile() member functions, which define action icon images in SVG format. Existing modules should be refactored in the same way to support scalable icons.

See also: Icon()

◆ SetIconSVG()

void pcl::Action::SetIconSVG ( const IsoString & svgSource )

Changes the icon associated with this Action to an image specified in SVG format.

Parameters

svgSource The source code of a valid SVG document defining the icon image that will be associated with this action. The SVG source code must be encoded in UTF-8.

The new icon will be used for all menu items and tool bar buttons associated with this action after calling this function. If an empty string is specified, or if the specified SVG document is not valid, no icon will be used to represent this action.

See also: SetIconSVGFile()

◆ SetIconSVGFile()

void pcl::Action::SetIconSVGFile ( const String & filePath )

Changes the icon associated with this Action to an image specified in SVG format.

Parameters

filePath Path to an existing file in the local file system, which must store a valid SVG document representing the icon image that will be associated with this action. The SVG source code must be encoded in UTF-8.

The new icon will be used for all menu items and tool bar buttons associated with this action after calling this function. If an empty string is specified, or if the specified SVG document does not exist or is not valid, no icon will be used to represent this action.

Automatic Resource Location

The specified filePath string can be prefixed with the "@module_icons_dir/" special token to let the PixInsight core application load the corresponding SVG document automatically from the a standard distribution directory. See the documentation for MetaProcess::IconImageSVGFile() for complete information.

See also: SetIconSVG()

◆ SetMenuText()

void pcl::Action::SetMenuText ( const String & text )

Changes the text of the menu item where this action has been integrated in the main menu of the PixInsight core application.

Parameters

text	A string representing the new menu text for this action object.

See also: MenuText()

◆ SetToolTip()

void pcl::Action::SetToolTip ( const String & tip )

Changes the tool tip text for this action. Tool tips are used for tool buttons corresponding to the integration of actions in tool bars.

Parameters

tip	A string that represents the new tool tip text for this action object.

If this action has not been integrated in a tool bar, this function is ignored.

See also: ToolTip()

◆ ToolBar()

String pcl::Action::ToolBar ( ) const

Returns the name of a tool bar where this action has been integrated in the PixInsight core application.

Integration of actions with tool bars is optional. If this action has not been integrated in a tool bar, this function returns an empty string.

An action's tool bar is a read-only property whose value can only be set with the constructor.

See also: SetToolBar()

◆ ToolTip()

String pcl::Action::ToolTip ( ) const

Returns the tool tip text that has been assigned to this action. Tool tips are used for tool buttons corresponding to the integration of actions in tool bars.

If this action has not been integrated in a tool bar, this function has no meaning, and an empty string is always returned.

See also: SetToolTip()

The documentation for this class was generated from the following file:

Action.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Action() [1/3]

◆ Action() [2/3]

◆ Action() [3/3]

◆ ~Action()

Member Function Documentation

◆ EnsureUnique()

◆ Execute()

◆ GetAccelerator()

◆ HasAccelerator()

◆ Icon()

◆ IsEnabled()

◆ MenuItem()

◆ MenuText()

◆ Null()

◆ operator=()

◆ RemoveAccelerator()

◆ SetAccelerator()

◆ SetIcon()

◆ SetIconSVG()

◆ SetIconSVGFile()

◆ SetMenuText()

◆ SetToolTip()

◆ ToolBar()

◆ ToolTip()