Class ActionTable
See Also: Class BaseInterfaceServer, Class ClassDesc, Structure ActionDescription, Class ActionItem, Class ActionCallback, Class ActionContext, Class IActionManager, Class DynamicMenu, Class DynamicMenuCallback, Class Interface.
class ActionTable : public BaseInterfaceServer
Description:
This class is available in release 4.0 and later only.
This is the class used to create Action Tables. An ActionTable holds a set of ActionItems, which are operations that can be tied to various UI elements, such as keyboard shortcuts, CUI buttons, the main menu and the Quad menu. 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.
All methods of this class are implemented by the system. Note however that many methods are virtual and may be customized by the plug-in developer as this class may be sub-classed if required. 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 \MAXSDK\SAMPLES\MODIFIERS\FFD
Methods:
public:
Prototype:
ActionTable(ActionTableId id, ActionContextId contextId, TSTR& name, HACCEL hDefaults, int numIds, ActionDescription* pOps, HINSTANCE hInst);
Remarks:
Constructor. 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.
At the same time the action table is built developers need to register the action context ID with the system. This is done using the IActionManager::RegisterActionContext() method.
Parameters:
ActionTableId id
The 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 the Class_ID program to generate this identifier: See Class Class_ID for more details. Simply use one of the two DWORDs that comprise the Class_ID for the ActionTableId.
ActionContextId contextId
The ActionContextID associated with this table. Several tables may share the same ActionContextID.
TSTR& name
The name for the ActionTable.
HACCEL hDefaults
The handle of the a windows accelerator table that gives default keyboard assignments for the operations.
int numIds
The number of items in the description array below.
ActionDescription* pOps
Points to the array of the operator descriptors.
HINSTANCE hInst
The handle to the instance of the module where the string resources in the array of operator descriptors are stored.
Prototype:
ActionTable(ActionTableId id, ActionContextId contextId, TSTR& name);
Remarks:
Constructor. This constructor build 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 described below.
Parameters:
ActionTableId id
The unique ID for the ActionTable.
ActionContextId contextId
The ActionContextID associated with this table. Several tables may share the same ActionContextID.
TSTR& name
The name for the ActionTable.
Prototype:
~ActionTable();
Remarks:
Destructor. Deletes all the operations maintained by the table and deletes the keyboard accelerator table if in use.
Prototype:
HACCEL GetHAccel();
Remarks:
Returns the handle of the current keyboard accelerator for the table.
Prototype:
void SetHAccel(HACCEL hAccel);
Remarks:
Sets the current keyboard accelerator for the table.
Prototype:
HACCEL GetDefaultHAccel();
Remarks:
Get the default keyboard accelerator table. This is used when the user has not assigned any accelerators.
Prototype:
TSTR& GetName();
Remarks:
Returns the name of the ActionTable. This is the name in the Customize UI dialog drop-down.
Prototype:
ActionTableId GetId();
Remarks:
Returns the ActionTableId for this ActionTable.
Prototype:
ActionContextId GetContextId();
Remarks:
Returns the ActionContextId for this ActionTable.
Prototype:
ActionCallback* GetCallback();
Remarks:
Get the current callback associated with this table. Returns NULL if the table is not active.
Prototype:
void SetCallback(ActionCallback* pCallback);
Remarks:
Sets the callback object used by this ActionTable.
Parameters:
ActionCallback* pCallback
Points to the callback to set.
Prototype:
int Count();
Remarks:
Returns the number of ActionItems in the table.
Prototype:
ActionItem* operator[](int i);
Remarks:
This operator returns a pointer to the 'i-th' ActionItem.
Parameters:
int i
The zero based index in the list of ActionItems.
Prototype:
ActionItem* GetAction(int cmdId);
Remarks:
Returns a pointer to the ActionItem associated with the command ID passed.
Parameters:
int cmdId
The command ID.
Prototype:
void AppendOperation(ActionItem* pAction);
Remarks:
This method adds an operation to the table.
Parameters:
ActionItem* pAction
Points to the ActionItem to append.
Prototype:
BOOL DeleteOperation(ActionItem* pAction);
Remarks:
Remove an operation from the table
Parameters:
ActionItem* pAction
Points to the ActionItem to delete.
Return Value:
TRUE if the operation was deleted; FALSE if it could not be found and wasn't.
Prototype:
void DeleteThis();
Remarks:
Deletes this ActionItem.
Default Implementation:
{ delete this; }
Prototype:
virtual BOOL GetButtonText(int cmdId, TSTR& buttonText);
Remarks:
This method retrieves the text that will be used when the ActionItem is on a text button.
Parameters:
int cmdId
The unique ID of the command whose button text is retrieved.
TSTR& buttonText
Storage for the text.
Return Value:
TRUE if the command is in the table; otherwise FALSE.
Prototype:
virtual BOOL GetMenuText(int cmdId, TSTR& menuText);
Remarks:
This method 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:
int cmdId
The unique ID of the command whose menu text is retrieved.
TSTR& menuText
Storage for the text.
Return Value:
TRUE if the command is in the table; otherwise FALSE.
Default Implementation:
{ return GetButtonText(cmdId, menuText); }
Prototype:
virtual BOOL GetDescriptionText(int cmdId, TSTR& descText);
Remarks:
This method gets the text that will be 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:
int cmdId
The unique ID of the command whose description text is retrieved.
TSTR& descText
Storage for the text.
Return Value:
TRUE if the command is in the table; otherwise FALSE.
Prototype:
virtual BOOL IsChecked(int cmdId);
Remarks:
Returns TRUE if the menu item should be checked or a CUI button should be in the pressed state.
Parameters:
int cmdId
The unique ID of the command.
Default Implementation:
{ return FALSE; }
Prototype:
virtual BOOL IsItemVisible(int cmdId);
Remarks:
This method determines if an item is to be visible on a menu. Returns TRUE if visible; FALSE if not.
Parameters:
int cmdId
The unique ID of the command.
Default Implementation:
{ return TRUE; }
Prototype:
virtual BOOL IsEnabled(int cmdId);
Remarks:
This method determines if the operation is currently enabled and available. Returns TRUE if enabled; FALSE if disabled.
Parameters:
int cmdId
The unique ID of the command.
Default Implementation:
{ return TRUE; }
Prototype:
virtual void WritePersistentActionId(int cmdId, TSTR& idString);
Remarks:
This method will write an action identifier to a *.CUI file or *.KBD file. It’s default implementation is to write the integer ID but will be over-riden when command IDs are not persistent.
Parameters:
int cmdId
The unique ID of the command.
TSTR& idString
The action ID placed in the string.
Prototype:
virtual int ReadPersistentActionId(TSTR& idString);
Remarks:
This method will read an action identifier from a *.CUI file or *.KBD file. It’s default implementation is to read the integer ID but will be over-riden when command IDs are not persistent.
Parameters:
TSTR& idString
The action ID string.
Return Value:
This method returns -1 if the command was not found in the table.
Prototype:
virtual MaxIcon* GetIcon(int cmdId);
Remarks:
Returns an optional icon for the command, or NULL if there is none.
Parameters:
int cmdID
The unique ID of the command.
Prototype:
void BuildActionTable(HACCEL hDefaults, int numIds, ActionDescription* pOps, HINSTANCE hInst);
Remarks:
This method will fill the action table with the given action descriptions.
Parameters:
HACCEL hDefaults
The handle of the a windows accelerator table that provides keyboard assignments for the operations.
int numIds
The number of ID’s to add to the action table.
ActionDescription* pOps
The array of action descriptions to build the table from.
HINSTANCE hInst
The handle to the instance of the module.
Prototype:
ActionItem* GetCurrentAssignment(ACCEL accel);
Remarks:
Get the action assigned to the given accelerator, if any.
Parameters:
ACCEL accel
The accelerator key you wish to check the assignment for.
Prototype:
void AssignKey(int cmdId, ACCEL accel);
Remarks:
Assign the command to the given accelerator. Also removes any previous assignment to that accelerator.
Parameters:
int cmdId
The command ID.
ACCEL accel
The accelerator key you wish to assign.
Prototype:
void RemoveShortcutFromTable(ACCEL accel);
Remarks:
removes the given assignment from the shortcut table
Parameters:
ACCEL accel
The accelerator key you wish to remove from the shortcut table.