Class ActionItem
See Also: Class ActionTable, Class ActionCallback, Structure ActionDescription, Class ActionContext, Class IActionManager, Class DynamicMenu, Class DynamicMenuCallback, Class MAXIcon, Class Interface.
class ActionItem : public InterfaceServer
Description:
This class is available in release 4.0 and later only.
The class ActionItem is used to represent the operation that live in ActionTables. ActionItem is an abstract class with operations to support various UI operations. The system provides a default implementation of this class that works when the table is build with the ActionTable::BuildActionTable() method. However, developers may want to specialize this class for more special-purpose applications. For example, MAXScipt does this to export macroScripts to an ActionTable. Methods that are marked as internal should not be used.
Data Members:
protected:
ActionTable* mpTable;
Points to the table that owns the action.
Methods:
public:
Prototype:
virtual int GetId() = 0;
Remarks:
This method retrieves the unique identifier for the action. This action must be unique in the table, but not does not have to be unique between tables.
Prototype:
virtual BOOL ExecuteAction() = 0;
Remarks:
Calling ExecuteAction causes the item to be run. This returns a BOOL that indicates if the action was actually executed. If the item is disabled, or if the table that owns it is not activated, then it won’t execute, and returns FALSE.
Return Value:
TRUE if the action is executed; otherwise FALSE.
Prototype:
virtual void GetButtonText(TSTR& buttonText) = 0;
Remarks:
This method retrieves the text that will be used when the ActionItem is on a text button. The text is stored into the buttonText parameter.
Parameters:
TSTR& buttonText
Storage for the retrieved text.
Prototype:
virtual void GetMenuText(TSTR& menuText) = 0;
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. This method is called just before the menu is displayed, so it can update the text at that time. For example, the "Undo" menu item in 3ds max’s main menu adds the name of the command that will be undone.
Parameters:
TSTR& menuText
Storage for the retrieved text.
Prototype:
virtual void GetDescriptionText(TSTR& descText) = 0;
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:
TSTR& descText
Storage for the retrieved text.
Prototype:
virtual void GetCategoryText(TSTR& catText) = 0;
Remarks:
This method retrieves the text for the category of the operation. This is used in the customization dialog to fill the "category" drop-down list.
Parameters:
TSTR& catText
Storage for the retrieved text.
Prototype:
virtual BOOL IsChecked() = 0;
Remarks:
This method determines if the action is in a "Checked" state. For menus, this means that a check mark will appear next to the item, if this returns TRUE. If the item is on a button, this is used to determine of the button is in the "Pressed" state. Note that button states are automatically updated on selection change and command mode changes. If your plug-in performs an operation that requires the CUI buttons to be redrawn, you need to call the method CUIFrameMgr::SetMacroButtonStates(TRUE).
Prototype:
virtual BOOL IsItemVisible() = 0;
Remarks:
This method determines if an item is visible on a menu. If it returns FALSE, then the item is not included in the menu. This can be used to create items that a context sensitive. For example, you may want an item to appear on a menu only when the selected object is of a particular type. To do this, you have this method check the class id of the current selection.
Prototype:
virtual BOOL IsEnabled() = 0;
Remarks:
This method determines if the operation is currently available. If it is on a menu, or button, the item is grayed out if this method returns FALSE. If it assigned to a keyboard shortcut, then it will not execute the operation if invoked. . If your plug-in performs an operation that requires the CUI buttons to be redrawn, you need to call the method CUIFrameMgr::SetMacroButtonStates(TRUE).
Return Value:
TRUE for enabled; FALSE for disabled.
Prototype:
virtual MaxIcon* GetIcon() = 0;
Remarks:
If you’ve provided an icon for this operation, you return it with this method. If no icon is available, this returns NULL. The icon is used on CUI buttons, and in the list of operations in the customization dialogs.
Prototype:
virtual void DeleteThis() = 0;
Remarks:
Called to delete the ActionItem. This normally happens when the table that owns it is deleted.
Prototype:
ActionTable* GetTable();
Remarks:
This returns a pointer to the table that owns the ActionItem. An item can only be owned by a single table.
Default Implementation:
{ return mpTable; }
Prototype:
void SetTable(ActionTable* pTable);
Remarks:
Sets the table that owns the item. Used internally. May be used if you implement a custom sub-class of ActionItem.
Parameters:
ActionTable* pTable
Points to the table to set.
Default Implementation:
{ mpTable = pTable; }
Prototype:
TCHAR* GetShortcutString();
Remarks:
Returns the string that describes all the keyboard shortcuts associated with the item. This will look something like "Alt+A" or "C, Shift+Alt+Q". This returns NULL if no keyboard shortcut is associated with the item.
Prototype:
virtual MacroEntry* GetMacroScript();
Remarks:
Returns the representation of the macroScript for the item, if it's implemented by a macroScript, it returns NULL otherwise.
Default Implementation:
{ return NULL; }
Prototype:
virtual BOOL IsDynamicMenu();
Remarks:
Determines if a menu is created or if an action takes place. If this method returns TRUE, then the ActionItem creates a menu. If it returns FALSE then an action is performed.
Default Implementation:
{ return FALSE; }
Prototype:
virtual void SetIsDynamicMenu();
Remarks:
This method may be called after an action item is created to tell the system that it is a dynamic menu action. Note: Dynamic menus may be added to the quad menus programmatically (via the IMenuManager API) or 'manually'.
Prototype:
virtual IMenu* GetDynamicMenu(HWND hwnd, IPoint2& m);
Remarks:
If the ActionItem does produce a menu, this method is called to return a pointer to the menu. See Class DynamicMenu for an easy way to produce these menus.
Parameters:
HWND hwnd
If the menu is requested by a right-click quad menu, then this hwnd is the handle of the window where the click occurred. If the item is used from a menu bar, this hwnd will be NULL.
IPoint2& m
If the menu is requested by a right-click quad menu, then this parameter is the point in the window where the user clicked.
Return Value:
A pointer to the menu.
Default Implementation:
{ return NULL; }