ActionTable Class Reference

This reference page is linked to from the following overview topics: Major New Features, Classes Involved in the Action System, Building Action Tables, When to Derive from ActionTable and ActionItem.

---

Search for all occurrences

---

Detailed Description

A table of action items that can be used by plug-ins to export tables of action items that can be used by the UI to attach to keyboard shorcuts, assigned to toolbar buttons, and add to menus.

3ds Max's core code exports several ActionTables for built-in operations in 3ds Max. Plug-ins can also export their own action tables via methods available in ClassDesc.

Every ActionTable also has an ActionContextId associated with it. This ActionContextId can be shared with other tables. When assigning keyboard shortcuts to items in an ActionTable, tables that share a unique context id are forced to have unique shortcuts. Tables with different context ids can have overlapping keyboard shortcut assignments.

All methods of this class are implemented by the system. Note that this class may be sub-classed if required and that many functions can be overridden. See the Advanced Topics section UI Customization for details on sub-classing this class and ActionItem. For details on implementing an ActionTable please refer to the sample at /maxsdk/samples/modifiers/ffd.

Version:

4.0

See also:

Class FPMixinInterface, Class ClassDesc, Structure ActionDescription, Class ActionItem, Class ActionCallback, Class ActionContext, Class IActionManager, Class DynamicMenu, Class DynamicMenuCallback, Class Interface.

#include <actiontable.h>

Inheritance diagram for ActionTable:

List of all members.

Public Types
enum	ActionTableFps {   kGetId, kGetName, kGetContextId, kGetContextName,   kNumActionItems, kGetActionItem }
Public Member Functions
CoreExport	ActionTable (ActionTableId id, ActionContextId contextId, MSTR &name, HACCEL hDefaults, int numIds, ActionDescription *pOps, HINSTANCE hInst)
	This constructor builds the action table using an array of descriptors.
CoreExport	ActionTable (ActionTableId id, ActionContextId contextId, MSTR &name)
	This constructor builds a new empty action table with the given ID, context ID and name.
virtual CoreExport	~ActionTable ()
	Deletes all the operations maintained by the table and deletes the keyboard accelerator table if in use.
virtual CoreExport MSTR &	GetName ()
	Returns the name of the action table.
virtual CoreExport ActionTableId	GetId ()
	Returns the ActionTableID.
virtual CoreExport ActionContextId	GetContextId ()
	Returns the ActionContextId.
virtual CoreExport ActionCallback *	GetCallback ()
	Get the current callback associated with this table.
virtual CoreExport void	SetCallback (ActionCallback *pCallback)
	Sets the callback object used by this ActionTable.
virtual CoreExport int	Count ()
	Returns the number of ActionItems in the table.
virtual CoreExport ActionItem *	operator[] (int i)
	Returns a pointer to the nth ActionItem.
virtual CoreExport ActionItem *	GetAction (int cmdId)
	Returns a pointer to the ActionItem associated with the command ID passed.
virtual CoreExport ActionItem *	GetActionByIndex (int index)
	Returns a pointer to the nth ActionItem using the same algorithm as the operator[].
virtual CoreExport void	AppendOperation (ActionItem *pAction)
	Appends an ActionItem to the table.
virtual CoreExport BOOL	DeleteOperation (ActionItem *pAction)
	Removes an operation from the table.
virtual CoreExport void	DeleteThis ()
	Deletes this ActionItem.
virtual CoreExport BOOL	GetButtonText (int cmdId, MSTR &buttonText)
	Retrieves the text that will be used when the ActionItem is on a text button.
virtual CoreExport BOOL	GetMenuText (int cmdId, MSTR &menuText)
	Retrieves the text to use when the item is on a menu (either Quad menu or main menu bar).
virtual CoreExport BOOL	GetDescriptionText (int cmdId, MSTR &descText)
	Retrieves the text that is used for tool tips and menu help.
virtual CoreExport BOOL	IsChecked (int cmdId)
	Returns TRUE if the menu item should be checked or a CUI button should be in the pressed state.
virtual CoreExport BOOL	IsItemVisible (int cmdId)
	Determines if an item is to be visible on a menu.
virtual CoreExport BOOL	IsEnabled (int cmdId)
	Determines if the operation is currently enabled and available.
virtual CoreExport void	WritePersistentActionId (int cmdId, MSTR &idString)
	Converts an action item identifier to a string representation The textual representation of action item ids are used in .CUI and .KBD files.
virtual CoreExport int	ReadPersistentActionId (MSTR &idString)
	Converts an action table string id to the action items numeric id.
virtual CoreExport MaxIcon *	GetIcon (int cmdId)
	Returns an optional icon for the command, or NULL if there is none.
CoreExport void	BuildActionTable (HACCEL hDefaults, int numIds, ActionDescription *pOps, HINSTANCE hInst)
	Fills the action table with the given action descriptions.
virtual CoreExport ActionItem *	GetCurrentAssignment (ACCEL accel)
	Gets the action assigned to the given accelerator, if any.
virtual CoreExport void	AssignKey (int cmdId, ACCEL accel)
	Assigns the command to the given accelerator.
virtual CoreExport void	RemoveShortcutFromTable (ACCEL accel)
	Removes the given assignment from the shortcut table.
CoreExport FPInterfaceDesc *	GetDescByID (Interface_ID id)
CoreExport FPInterfaceDesc *	GetDesc ()
virtual CoreExport BaseInterface *	GetInterface (Interface_ID id)
virtual CoreExport Interface_ID	GetID ()
Keyboard Accelerator Functions
virtual CoreExport HACCEL	GetHAccel ()
	Returns the handle of the current keyboard accelerator for the table.
virtual CoreExport void	SetHAccel (HACCEL hAccel)
	Sets the current keyboard accelerator for the table.
virtual CoreExport HACCEL	GetDefaultHAccel ()
	Gets the default keyboard accelerator table used when the user has not assigned any accelerators.
virtual CoreExport void	SetDefaultHAccel (HACCEL accel)
	Sets the default keyboard accelerator table used when the user has not assigned any accelerators.
Protected Member Functions
BEGIN_FUNCTION_MAP	RO_PROP_FN (kGetId, GetId, TYPE_DWORD)
	RO_PROP_FN (kGetName, GetName, TYPE_STRING)
	RO_PROP_FN (kGetContextId, GetContextId, TYPE_DWORD)
	RO_PROP_FN (kGetContextName, fpGetContextName, TYPE_STRING)
	RO_PROP_FN (kNumActionItems, Count, TYPE_INT)
	FN_1 (kGetActionItem, TYPE_INTERFACE, GetActionByIndex, TYPE_INDEX)
END_FUNCTION_MAP CoreExport const MCHAR *	fpGetContextName () const
	Used internally by function publishing.
Protected Attributes
Tab< ActionItem * >	mOps

---

Member Enumeration Documentation

enum ActionTableFps

Search for all occurrences

Enumerator:

kGetId	Search for all occurrences
kGetName	Search for all occurrences
kGetContextId	Search for all occurrences
kGetContextName	Search for all occurrences
kNumActionItems	Search for all occurrences
kGetActionItem	Search for all occurrences

    {
        kGetId,
        kGetName,
        kGetContextId,
        kGetContextName,
        kNumActionItems,
        kGetActionItem,
    };

---

Constructor & Destructor Documentation

CoreExport ActionTable	(	ActionTableId	id,
		ActionContextId	contextId,
		MSTR &	name,
		HACCEL	hDefaults,
		int	numIds,
		ActionDescription *	pOps,
		HINSTANCE	hInst
	)

This constructor builds the action table using an array of descriptors.

It takes the ID of the table, the context id, a name for the table, a windows accelerator table that gives default keyboard assignments for the operations, the number of items, the table of operation descriptions, and the instance of the module where the string resources in the table are stored. When the action table is constructed the action context ID must be registered with the system using the IActionManager::RegisterActionContext() method.

Parameters:

id	A unique ID for the ActionTable. Every ActionTable has a unique 32-bit integer ID. For new tables exported by plug-ins, the developer should choose a random 32-bit integer. You can use one of the two DWORDS generated by the gencid.exe program as an ActionTableId.
contextId	The ActionContextID associated with this table. Several tables may share the same ActionContextID.
name	The name for the ActionTable.
hDefaults	The handle of the a windows accelerator table that gives default keyboard assignments for the operations.
numIds	The number of items in the description array
pOps	Points to the array of the operator descriptors.
hInst	The handle to the instance of the module where the string resources in the array of operator descriptors are stored.

CoreExport ActionTable	(	ActionTableId	id,
		ActionContextId	contextId,
		MSTR &	name
	)

This constructor builds a new empty action table with the given ID, context ID and name.

You then need to add ActionItems to the table separately using the AppendOperation() method.

Parameters:

id	The unique ID for the ActionTable.
contextId	The ActionContextID associated with this table. Several tables may share the same ActionContextID.
name	The name for the ActionTable.

virtual CoreExport ~ActionTable

(

)

[virtual]

Deletes all the operations maintained by the table and deletes the keyboard accelerator table if in use.

---

Member Function Documentation

virtual CoreExport HACCEL GetHAccel

(

)

[virtual]

Search for all occurrences

Returns the handle of the current keyboard accelerator for the table.

virtual CoreExport void SetHAccel

(

HACCEL

hAccel

)

[virtual]

Search for all occurrences

Sets the current keyboard accelerator for the table.

virtual CoreExport HACCEL GetDefaultHAccel

(

)

[virtual]

Search for all occurrences

Gets the default keyboard accelerator table used when the user has not assigned any accelerators.

virtual CoreExport void SetDefaultHAccel

(

HACCEL

accel

)

[virtual]

Search for all occurrences

Sets the default keyboard accelerator table used when the user has not assigned any accelerators.

virtual CoreExport MSTR& GetName

(

)

[virtual]

Search for all occurrences

Returns the name of the action table.

virtual CoreExport ActionTableId GetId

(

)

[virtual]

Search for all occurrences

Returns the ActionTableID.

virtual CoreExport ActionContextId GetContextId

(

)

[virtual]

Search for all occurrences

Returns the ActionContextId.

virtual CoreExport ActionCallback* GetCallback

(

)

[virtual]

Search for all occurrences

Get the current callback associated with this table.

Returns NULL if the table is not active.

virtual CoreExport void SetCallback

(

ActionCallback *

pCallback

)

[virtual]

Search for all occurrences

Sets the callback object used by this ActionTable.

Parameters:

pCallback

Points to the callback to set.

virtual CoreExport int Count

(

)

[virtual]

Search for all occurrences

Returns the number of ActionItems in the table.

virtual CoreExport ActionItem* operator[]

(

int

i

)

[virtual]

Returns a pointer to the nth ActionItem.

Parameters:

i	The zero based index in the list of ActionItems.

virtual CoreExport ActionItem* GetAction

(

int

cmdId

)

[virtual]

Search for all occurrences

Returns a pointer to the ActionItem associated with the command ID passed.

Parameters:

cmdId

The command ID.

virtual CoreExport ActionItem* GetActionByIndex

(

int

index

)

[virtual]

Search for all occurrences

Returns a pointer to the nth ActionItem using the same algorithm as the operator[].

Parameters:

index

The zero based index of the action.

Returns:

A pointer to the ActionItem

virtual CoreExport void AppendOperation

(

ActionItem *

pAction

)

[virtual]

Search for all occurrences

Appends an ActionItem to the table.

Parameters:

pAction

A pointer the ActionItem to append.

virtual CoreExport BOOL DeleteOperation

(

ActionItem *

pAction

)

[virtual]

Search for all occurrences

Removes an operation from the table.

Parameters:

pAction

Points to the ActionItem to delete.

Returns:

TRUE if the operation was deleted; FALSE if it could not be found and wasn't.

virtual CoreExport void DeleteThis

(

)

[virtual]

Search for all occurrences

Deletes this ActionItem.

Default implementation:

    { delete this; }

virtual CoreExport BOOL GetButtonText	(	int	cmdId,
		MSTR &	buttonText
	)		[virtual]

Search for all occurrences

Retrieves the text that will be used when the ActionItem is on a text button.

Parameters:

	cmdId	The unique ID of the command whose button text is retrieved.
[out]	buttonText	The retrieved text.

Returns:

TRUE if the command is in the table; otherwise FALSE.

virtual CoreExport BOOL GetMenuText	(	int	cmdId,
		MSTR &	menuText
	)		[virtual]

Search for all occurrences

Retrieves the text to use when the item is on a menu (either Quad menu or main menu bar).

This can be different from the button text.

Parameters:

cmdId	The unique ID of the command whose menu text is retrieved.
menuText	Storage for the text.

Returns:

TRUE if the command is in the table; otherwise FALSE.

Default Implementation:

    { return GetButtonText(cmdId, menuText); }

virtual CoreExport BOOL GetDescriptionText	(	int	cmdId,
		MSTR &	descText
	)		[virtual]

Search for all occurrences

Retrieves the text that is used for tool tips and menu help.

This is also the string that is displayed for the operation in all the lists in the customization dialogs.

Parameters:

cmdId	The unique ID of the command whose description text is retrieved.
descText	The retrieved text.

Returns:

TRUE if the command is in the table; otherwise FALSE.

virtual CoreExport BOOL IsChecked

(

int

cmdId

)

[virtual]

Search for all occurrences

Returns TRUE if the menu item should be checked or a CUI button should be in the pressed state.

Parameters:

cmdId

The unique ID of the command.

Default Implementation:

    { return FALSE; }

virtual CoreExport BOOL IsItemVisible

(

int

cmdId

)

[virtual]

Search for all occurrences

Determines if an item is to be visible on a menu.

Returns TRUE if visible; FALSE if not.

Parameters:

cmdId

The unique ID of the command.

Default Implementation:

    { return TRUE; }

virtual CoreExport BOOL IsEnabled

(

int

cmdId

)

[virtual]

Search for all occurrences

Determines if the operation is currently enabled and available.

Returns TRUE if enabled; FALSE if disabled.

Parameters:

cmdId

The unique ID of the command.

Default Implementation:

    { return TRUE; }

virtual CoreExport void WritePersistentActionId	(	int	cmdId,
		MSTR &	idString
	)		[virtual]

Search for all occurrences

Converts an action item identifier to a string representation The textual representation of action item ids are used in .CUI and .KBD files.

The default implementation is to convert the integer action item ID directly to a string.

Parameters:

cmdId	The unique command or action item ID.
idString	The string where the action item ID is written to.

virtual CoreExport int ReadPersistentActionId

(

MSTR &

idString

)

[virtual]

Search for all occurrences

Converts an action table string id to the action items numeric id.

This method can be used to convert string based action item identifiers read from a .CUI or *.KBD file to a numeric identifier. It's default implementation expects the string passed in as argument to contain one number.

Parameters:

idString

The action ID string.

Returns:

Returns -1 if the id could not be converted.

virtual CoreExport MaxIcon* GetIcon

(

int

cmdId

)

[virtual]

Search for all occurrences

Returns an optional icon for the command, or NULL if there is none.

Parameters:

cmdID

The unique ID of the command.

CoreExport void BuildActionTable	(	HACCEL	hDefaults,
		int	numIds,
		ActionDescription *	pOps,
		HINSTANCE	hInst
	)

Search for all occurrences

Fills the action table with the given action descriptions.

hDefaults The handle of the a windows accelerator table that provides keyboard assignments for the operations.

Parameters:

numIds	The number of ID's to add to the action table.
pOps	The array of action descriptions to build the table from.
hInst	The handle to the instance of the module.

virtual CoreExport ActionItem* GetCurrentAssignment

(

ACCEL

accel

)

[virtual]

Search for all occurrences

Gets the action assigned to the given accelerator, if any.

Parameters:

accel

The accelerator key you wish to check the assignment for.

virtual CoreExport void AssignKey	(	int	cmdId,
		ACCEL	accel
	)		[virtual]

Search for all occurrences

Assigns the command to the given accelerator.

Also removes any previous assignment to that accelerator.

Parameters:

cmdId	The command ID.
accel	The accelerator key you wish to assign.

virtual CoreExport void RemoveShortcutFromTable

(

ACCEL

accel

)

[virtual]

Search for all occurrences

Removes the given assignment from the shortcut table.

Parameters:

accel

The accelerator key you wish to remove from the shortcut table.

CoreExport FPInterfaceDesc* GetDescByID

(

Interface_ID

id

)

[virtual]

Search for all occurrences

Remarks:

This method is used to directly implement FPInterface::GetDesc() in your public virtual base mixin class, like this;

FPInterfaceDesc* GetDesc() { return GetDescByID(THIS_INTERFACE_ID); }

Then implement a GetDescByID() in the implementing class to avoid link export issues.

Parameters:

Interface_ID id

The unique interface ID by which to get the FPInterfaceDesc.

Default Implementation:

{ return &nullInterface; }

Reimplemented from FPMixinInterface.

CoreExport FPInterfaceDesc* GetDesc

(

)

[virtual]

Search for all occurrences

Remarks:

Returns a pointer to the class which contains the interface metadata.

Implements FPInterface.

virtual CoreExport BaseInterface* GetInterface

(

Interface_ID

id

)

[virtual]

Search for all occurrences

Remarks:

Returns a pointer to the interface whose ID is specified.

Parameters:

Interface_ID id

The ID of the interface to return.

Default Implementation:

{ return NULL; }

Reimplemented from FPMixinInterface.

virtual CoreExport Interface_ID GetID

(

)

[virtual]

Search for all occurrences

Remarks:

This method overrides GetID() in those interfaces that do not publish metadata but instead have a unique Interface_ID for quick internal identification in implementation code that might be shared by a bunch of mixin interfaces.

Returns:

The Interface_ID.

Default Implementation:

{ return GetDesc()->ID; }

Reimplemented from FPMixinInterface.

BEGIN_FUNCTION_MAP RO_PROP_FN	(	kGetId	,
		GetId	,
		TYPE_DWORD
	)		[protected]

Search for all occurrences

RO_PROP_FN	(	kGetName	,
		GetName	,
		TYPE_STRING
	)		[protected]

Search for all occurrences

RO_PROP_FN	(	kGetContextId	,
		GetContextId	,
		TYPE_DWORD
	)		[protected]

Search for all occurrences

RO_PROP_FN	(	kGetContextName	,
		fpGetContextName	,
		TYPE_STRING
	)		[protected]

Search for all occurrences

RO_PROP_FN	(	kNumActionItems	,
		Count	,
		TYPE_INT
	)		[protected]

Search for all occurrences

FN_1	(	kGetActionItem	,
		TYPE_INTERFACE	,
		GetActionByIndex	,
		TYPE_INDEX
	)		[protected]

Search for all occurrences

END_FUNCTION_MAP CoreExport const MCHAR* fpGetContextName

(

)

const [protected]

Search for all occurrences

Used internally by function publishing.

---

Member Data Documentation

Tab<ActionItem*> mOps [protected]

Search for all occurrences