This reference page is linked to from the following overview topics: Classes Involved in the Action System, Building Action Tables, When to Derive from ActionTable and ActionItem, New Classes and Methods.
#include <actiontable.h>
Represents an operation contained in an ActionTabls.
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 built with the ActionTable::BuildActionTable() method. However, developers may want to specialize this class for more special-purpose applications. For example, MAXScript does this to export macroScripts to an ActionTable. Methods that are marked as internal should not be used.
Public Types |
|
enum | IconSize { k16x16, k24x24, k32x32, kIconSizeCount } |
Icon size parameter. More... |
|
enum | ActionItemFps
{ kGetId, kIsVisible, kIsEnabled, kIsChecked, kGetDescription, kGetCategory, kGetButtonText, kGetMenuText, kHasIcon, kGetIconFileName, kGetIconIndex } |
Function IDs for function published (Fps)
methods and properties. More... |
|
Public Member Functions |
|
CoreExport | ActionItem () |
Constructor. |
|
virtual CoreExport | ~ActionItem () |
Destructor. |
|
virtual int | GetId ()=0 |
Retrieves a unique identifier for the
action. |
|
virtual BOOL | ExecuteAction ()=0 |
Executes the operation associated with the
action item. |
|
virtual CoreExport void | EmitMacro () |
Called by 3ds Max to allow the ActionItem
to customize macroRecorder output for this action. |
|
CoreExport BOOL | Execute () |
Calls ExecuteAction()
and handles macro recording etc. |
|
virtual void | GetButtonText (MSTR &buttonText)=0 |
Retrieves the text that will be used when
the ActionItem
is on a text button. |
|
virtual void | GetMenuText (MSTR &menuText)=0 |
Retrieves the text to use when the item is
on a menu (either Quad menu or main menu bar). |
|
virtual void | GetDescriptionText (MSTR &descText)=0 |
Retrieves the text that will be used for
tool tips and menu help. |
|
virtual void | GetCategoryText (MSTR &catText)=0 |
Retrieves the text for the category of the
operation. |
|
virtual BOOL | IsChecked ()=0 |
Returns whether a menu item is in a checked
state, or if a button is in a pressed state. |
|
virtual BOOL | IsItemVisible ()=0 |
Determines if an item is visible on a
context menu. |
|
virtual BOOL | IsEnabled ()=0 |
Determines if the operation is available to
the user. |
|
CoreExport MaxIcon * | GetIcon () |
Returns an icon associated with an ActionItem.
|
|
virtual void | DeleteThis ()=0 |
Called by 3ds Max to delete the ActionItem.
|
|
virtual CoreExport ActionTable * | GetTable () |
Returns a pointer to the table that owns the
ActionItem.
|
|
virtual CoreExport void | SetTable (ActionTable *pTable) |
Sets the table that owns the item. |
|
CoreExport const MCHAR * | GetShortcutString () |
Returns the string that describes all the
keyboard shortcuts associated with the item. |
|
virtual CoreExport MacroEntry * | GetMacroScript () |
Returns the representation of the
macroScript for the item, if it's implemented by a macroScript, it
returns NULL otherwise. |
|
virtual CoreExport BOOL | IsDynamicMenu () |
Determines if a menu is created or if an
action takes place. |
|
virtual CoreExport void | SetIsDynamicMenu () |
This method may be called after an action
item is created to tell the system that it is a dynamic menu
action. |
|
virtual CoreExport IMenu * | GetDynamicMenu (HWND hwnd, IPoint2 &m) |
If the ActionItem
does produce a menu, this method is called to return a pointer to
the menu. |
|
virtual CoreExport BOOL | IsDynamicAction () |
ActionItems that are deleted after they
execute should return TRUE. |
|
CoreExport BOOL | HasIcon () |
Returns TRUE if the ActionItem
specifies an icon. |
|
CoreExport bool | GetIconFileName (MSTR &fileName) |
If the ActionItem
specifies an icon, accesses the icon filename. |
|
CoreExport int | GetIconIndex () |
If the ActionItem
specifies an icon, returns the icon index. |
|
CoreExport MSTR | GetTooltipKey () |
Get the Action's tooltip key. |
|
CoreExport void | SetTooltipKey (const MCHAR *tooltipKey) |
Set the Action's tooltip key. |
|
CoreExport MaxSDK::Util::Path | GetIconPath (IconSize size) |
Get the Action's path to the icon of size
specified by param. |
|
CoreExport void | SetIconPath (IconSize size, const MaxSDK::Util::Path &path) |
Sets the Action's path to the icon of size
specified by the input param. |
|
CoreExport MSTR | GetMetadata () |
Gets the Action's metadata. |
|
CoreExport void | SetMetadata (const MCHAR *metadata) |
Sets the Action's metadata. |
|
virtual
CoreExport FPInterfaceDesc * |
GetDescByID (Interface_ID id) |
virtual
CoreExport FPInterfaceDesc * |
GetDesc () |
virtual CoreExport BaseInterface * | GetInterface (Interface_ID id) |
virtual CoreExport Interface_ID | GetID () |
Protected Member Functions |
|
BEGIN_FUNCTION_MAP | RO_PROP_FN (kGetId, GetId, TYPE_DWORD) |
RO_PROP_FN (kIsVisible, IsItemVisible, TYPE_BOOL) | |
RO_PROP_FN (kIsEnabled, IsEnabled, TYPE_BOOL) | |
RO_PROP_FN (kIsChecked, IsChecked, TYPE_BOOL) | |
VFN_1 (kGetDescription, GetDescriptionText, TYPE_TSTR_BR) | |
VFN_1 (kGetCategory, GetCategoryText, TYPE_TSTR_BR) | |
VFN_1 (kGetButtonText, GetButtonText, TYPE_TSTR_BR) | |
VFN_1 (kGetMenuText, GetMenuText, TYPE_TSTR_BR) | |
FN_0 (kHasIcon, TYPE_BOOL, HasIcon) | |
FN_1 (kGetIconFileName, TYPE_bool, GetIconFileName, TYPE_TSTR_BR) | |
FN_0 (kGetIconIndex, TYPE_INDEX, GetIconIndex) | |
END_FUNCTION_MAP
virtual CoreExport MaxIcon * |
GetIconImp () |
Returns an icon associated with an ActionItem.
|
|
Protected Attributes |
|
ActionTable * | mpTable |
Points to the table that owns the action.
|
enum IconSize |
Icon size parameter.
k16x16 |
icon of size 16x16 |
k24x24 |
icon of size 24x24 |
k32x32 |
icon of size 32x32 |
kIconSizeCount |
{ k16x16, k24x24, k32x32, kIconSizeCount };
enum ActionItemFps |
Function IDs for function published (Fps) methods and properties.
CoreExport ActionItem | ( | ) |
Constructor.
virtual CoreExport ~ActionItem | ( | ) | [virtual] |
Destructor.
virtual int GetId | ( | ) | [pure virtual] |
Retrieves a unique identifier for the action.
This action must be unique in the table, but not does not have to be unique between tables.
Implemented in ActionItemStandin.
virtual BOOL ExecuteAction | ( | ) | [pure virtual] |
Executes the operation associated with the action item.
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.
Implemented in ActionItemStandin.
virtual CoreExport void EmitMacro | ( | ) | [virtual] |
Called by 3ds Max to allow the ActionItem to customize macroRecorder output for this action.
CoreExport BOOL Execute | ( | ) |
Calls ExecuteAction() and handles macro recording etc.
Called by 3ds Max.
virtual void GetButtonText | ( | MSTR & | buttonText | ) | [pure virtual] |
Retrieves the text that will be used when the ActionItem is on a text button.
The text is stored into the buttonText parameter.
[out] | buttonText | - The retrieved text. |
Implemented in ActionItemStandin.
virtual void GetMenuText | ( | MSTR & | menuText | ) | [pure virtual] |
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.
[out] | menuText | - The retrieved text. |
Implemented in ActionItemStandin.
virtual void GetDescriptionText | ( | MSTR & | descText | ) | [pure virtual] |
Retrieves 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.
[out] | descText | - The retrieved text. |
Implemented in ActionItemStandin.
virtual void GetCategoryText | ( | MSTR & | catText | ) | [pure virtual] |
Retrieves the text for the category of the operation.
This is used in the customization dialog to fill the "category" drop-down list.
[out] | catText | - The retrieved text. |
Implemented in ActionItemStandin.
virtual BOOL IsChecked | ( | ) | [pure virtual] |
Returns whether a menu item is in a checked state, or if a button is in a pressed state.
For menus, this means that this function will return TRUE if a check mark appears next to the item. 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).
Implemented in ActionItemStandin.
virtual BOOL IsItemVisible | ( | ) | [pure virtual] |
Determines if an item is visible on a context 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.
Implemented in ActionItemStandin.
virtual BOOL IsEnabled | ( | ) | [pure virtual] |
Determines if the operation is available to the user.
If this method returns FALSE, and the ActionItem it is on a menu, or button, the item is grayed out. If it assigned to a keyboard shortcut, then it will not execute the operation if invoked. If your plugin performs an operation that requires the CUI buttons to be redrawn, you need to call the method CUIFrameMgr::SetMacroButtonStates(TRUE)
Implemented in ActionItemStandin.
CoreExport MaxIcon* GetIcon | ( | ) |
Returns an icon associated with an ActionItem.
First checks the result of GetIconImp(), then looks at ActionTable::GetIcon(int). If both functions return NULL, then this action has no Icon associated with it.
virtual void DeleteThis | ( | ) | [pure virtual] |
Called by 3ds Max to delete the ActionItem.
This normally happens when the table that owns it is deleted.
Implemented in ActionItemStandin.
virtual CoreExport ActionTable* GetTable | ( | ) | [virtual] |
Returns a pointer to the table that owns the ActionItem.
An item can only be owned by a single table.
{ return mpTable; }
virtual CoreExport void SetTable | ( | ActionTable * | pTable | ) | [virtual] |
Sets the table that owns the item.
Used internally. May be used if you implement a custom sub-class of ActionItem.
pTable | - Points to the table to set. |
{ mpTable = pTable; }
CoreExport const MCHAR* GetShortcutString | ( | ) |
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".
virtual CoreExport MacroEntry* GetMacroScript | ( | ) | [virtual] |
Returns the representation of the macroScript for the item, if it's implemented by a macroScript, it returns NULL otherwise.
{ return NULL; }
virtual CoreExport BOOL IsDynamicMenu | ( | ) | [virtual] |
Determines if a menu is created or if an action takes place.
{ return FALSE; }
Reimplemented in ActionItemStandin.
virtual CoreExport void SetIsDynamicMenu | ( | ) | [virtual] |
This method may be called after an action item is created to tell the system that it is a dynamic menu action.
Dynamic menus may be added to the quad menus procedurally (via the IMenuManager API) or 'manually'.
Reimplemented in ActionItemStandin.
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.
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. |
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 NULL; }
Reimplemented in ActionItemStandin.
virtual CoreExport BOOL IsDynamicAction | ( | ) | [virtual] |
ActionItems that are deleted after they execute should return TRUE.
CoreExport BOOL HasIcon | ( | ) |
Returns TRUE if the ActionItem specifies an icon.
CoreExport bool GetIconFileName | ( | MSTR & | fileName | ) |
If the ActionItem specifies an icon, accesses the icon filename.
fileName | - If the ActionItem specifies an icon, then the icon filename is returned through this parameter. |
CoreExport int GetIconIndex | ( | ) |
If the ActionItem specifies an icon, returns the icon index.
CoreExport MSTR GetTooltipKey | ( | ) |
Get the Action's tooltip key.
The tooltip key may be associated with a product tooltip. By default, the tooltip key is built as "actionTableID-actionID" for native actions and as "Category-MacroName" for macros.
CoreExport void SetTooltipKey | ( | const MCHAR * | tooltipKey | ) |
Set the Action's tooltip key.
The function does not verify if the key is unique or not.
CoreExport MaxSDK::Util::Path GetIconPath | ( | IconSize | size | ) |
Get the Action's path to the icon of size specified by param.
This path can be relative to the Theme- specific Resources folder under the folder, or it can be an absolute path.
size | an enum specifying the icon path to get |
CoreExport void SetIconPath | ( | IconSize | size, |
const MaxSDK::Util::Path & | path | ||
) |
Sets the Action's path to the icon of size specified by the input param.
This path can be relative to the Theme- specific Resources folder under the folder, or it can be an absolute path.
size | an enum specifying the icon path to set |
path | The path to the icon of the size specified by the input parameter. |
CoreExport MSTR GetMetadata | ( | ) |
Gets the Action's metadata.
Metadata format is a single string with a comma separating each individual metadatum. Metadata is used in global search command to list similar command names in other software, etc
CoreExport void SetMetadata | ( | const MCHAR * | metadata | ) |
virtual CoreExport FPInterfaceDesc* GetDescByID | ( | Interface_ID | id | ) | [virtual] |
Reimplemented from FPMixinInterface.
virtual CoreExport FPInterfaceDesc* GetDesc | ( | ) | [virtual] |
Implements FPInterface.
virtual CoreExport BaseInterface* GetInterface | ( | Interface_ID | id | ) | [virtual] |
Reimplemented from FPMixinInterface.
Reimplemented in ActionItemStandin.
virtual CoreExport Interface_ID GetID | ( | ) | [virtual] |
Reimplemented from FPMixinInterface.
BEGIN_FUNCTION_MAP RO_PROP_FN | ( | kGetId | , |
GetId | , | ||
TYPE_DWORD | |||
) | [protected] |
RO_PROP_FN | ( | kIsVisible | , |
IsItemVisible | , | ||
TYPE_BOOL | |||
) | [protected] |
RO_PROP_FN | ( | kIsEnabled | , |
IsEnabled | , | ||
TYPE_BOOL | |||
) | [protected] |
RO_PROP_FN | ( | kIsChecked | , |
IsChecked | , | ||
TYPE_BOOL | |||
) | [protected] |
VFN_1 | ( | kGetDescription | , |
GetDescriptionText | , | ||
TYPE_TSTR_BR | |||
) | [protected] |
VFN_1 | ( | kGetCategory | , |
GetCategoryText | , | ||
TYPE_TSTR_BR | |||
) | [protected] |
VFN_1 | ( | kGetButtonText | , |
GetButtonText | , | ||
TYPE_TSTR_BR | |||
) | [protected] |
VFN_1 | ( | kGetMenuText | , |
GetMenuText | , | ||
TYPE_TSTR_BR | |||
) | [protected] |
FN_0 | ( | kHasIcon | , |
TYPE_BOOL | , | ||
HasIcon | |||
) | [protected] |
FN_1 | ( | kGetIconFileName | , |
TYPE_bool | , | ||
GetIconFileName | , | ||
TYPE_TSTR_BR | |||
) | [protected] |
FN_0 | ( | kGetIconIndex | , |
TYPE_INDEX | , | ||
GetIconIndex | |||
) | [protected] |
END_FUNCTION_MAP virtual CoreExport MaxIcon* GetIconImp | ( | ) | [protected, virtual] |
Returns an icon associated with an ActionItem.
To supply a custom icon for an action item, override this method and supply a custom implementation. Default implementation: returns NULL
ActionTable* mpTable
[protected] |
Points to the table that owns the action.