xiiActionMap Class Reference

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

#include <ActionMap.h>

Public Types
using	TreeNode = xiiTreeNode<xiiActionMapDescriptor>

Public Member Functions
	xiiActionMap (xiiStringView sParentMapping)
void	MapAction (xiiActionDescriptorHandle hAction, xiiStringView sPath, float fOrder)
	Adds the given action to into the category or menu identified by sPath.
void	MapAction (xiiActionDescriptorHandle hAction, xiiStringView sPath, xiiStringView sSubPath, float fOrder)
	An overload of MapAction that takes a dedicated sPath and sSubPath argument for convenience.
void	HideAction (xiiActionDescriptorHandle hAction, xiiStringView sPath)
	Hides an action from the action map. The same rules for 'global' names apply as for MapAction(). If the target action is in this mapping, prefer not calling MapAction in the first place. Use this for actions to be removed that might be in a parent mapping and thus can't be modified directly.
const TreeNode *	BuildActionTree ()
	Builds an action tree out of all mapped actions of this and any parent mappings.
const xiiActionMapDescriptor *	GetDescriptor (const xiiTreeNode< xiiActionMapDescriptor > *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 xiiActionManager.

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 xiiActionMapManager and are simply identified by name.

Member Function Documentation

MapAction() [1/2]

void xiiActionMap::MapAction	(	xiiActionDescriptorHandle	hAction,
		xiiStringView	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 XII_REGISTER_CATEGORY) or a menu (see XII_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 xiiActionMap::MapAction	(	xiiActionDescriptorHandle	hAction,
		xiiStringView	sPath,
		xiiStringView	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.

---

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

• /home/runner/work/XII/XII/Source/Tools/Libs/GuiFoundation/Action/ActionMap.h
• /home/runner/work/XII/XII/Source/Tools/Libs/GuiFoundation/Action/Implementation/ActionMap.cpp