plActionMap Class Reference

Defines the structure of how actions are organized in a particular context. More...

#include <ActionMap.h>

Public Types
using	TreeNode = plTreeNode<plActionMapDescriptor>

Public Member Functions
void	MapAction (plActionDescriptorHandle hAction, plStringView sPath, float fOrder)
	Adds the given action to into the category or menu identified by sPath.
void	MapAction (plActionDescriptorHandle hAction, plStringView sPath, plStringView sSubPath, float fOrder)
	An overload of MapAction that takes a dedicated sPath and sSubPath argument for convenience.
plResult	UnmapAction (plActionDescriptorHandle hAction, plStringView sPath)
	Removes the named action from the action map. The same rules for 'global' names apply as for MapAction().
plResult	SearchPathForAction (plStringView sUniqueName, plStringBuilder &out_sPath) const
	Searches for an action with the given name and returns the full path to it.
const TreeNode *	GetRootObject () const
const plActionMapDescriptor *	GetDescriptor (const plTreeNode< plActionMapDescriptor > *pObject) const

Detailed Description

Defines the structure of how actions are organized in a particular context.

Actions are usually commands that are exposed through UI. For instance a button in a toolbar or a menu entry.

Actions are unique. Each action only exists once in plActionManager.

An action map defines where in a menu an action shows up. Actions are usually grouped by categories. So for example all actions related to opening, closing or saving a document may be in one group. Their position within that group is defined through an 'order' value. This allows plugins to insert actions easily.

A window might use multiple action maps to build different structures. For example, usually there is one action map for a window menu, and another map for a toolbar. These will contain different actions, and they are organized differently.

Action maps are created through plActionMapManager and are simply identified by name.

Member Function Documentation

MapAction() [1/2]

void plActionMap::MapAction	(	plActionDescriptorHandle	hAction,
		plStringView	sPath,
		float	fOrder )

Adds the given action to into the category or menu identified by sPath.

All actions added to the same path will be sorted by 'fOrder' and the ones with the smaller values show up at the top.

sPath must either be a fully qualified path OR the name of a uniquely named category or menu. If sPath is empty, the action (which may be a category itself) will be mapped into the root. This is common for top-level menus and for toolbars.

If sPath is a fully qualified path, the segments are separated by slashes (/) and each segment must name either a category (see PL_REGISTER_CATEGORY) or a menu (see PL_REGISTER_MENU).

sPath may also name a category or menu WITHOUT it being a full path. In this case the name must be unique. If sPath isn't empty and doesn't contain a slash, the system searches all available actions that are already in the action map. This allows you to insert an action into a category, without knowing the full path to that category. By convention, categories that are meant to be used that way are named "G.Something". The idea is, that where that category really shows up (and whether it is its own menu or just an area somewhere) may change in the future, or may be different in different contexts.

To make it easier to use 'global' category names combined with an additional relative path, there is an overload of this function that takes an additional sSubPath argument.

MapAction() [2/2]

void plActionMap::MapAction	(	plActionDescriptorHandle	hAction,
		plStringView	sPath,
		plStringView	sSubPath,
		float	fOrder )

An overload of MapAction that takes a dedicated sPath and sSubPath argument for convenience.

If sPath is a 'global' name of a category, it is searched for (see SearchPathForAction()). Afterwards sSubPath is appended and the result is forwarded to MapAction() as a single path string.

SearchPathForAction()

plResult plActionMap::SearchPathForAction	(	plStringView	sUniqueName,
		plStringBuilder &	out_sPath ) const

Searches for an action with the given name and returns the full path to it.

This is mainly meant to be used with (unique) names to categories (or menus).

---

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

• Code/Tools/Libs/GuiFoundation/Action/ActionMap.h
• Code/Tools/Libs/GuiFoundation/Action/Implementation/ActionMap.cpp