Moray Plugin SDK Documentation

This release of the Plugin SDK can be used by Moray V3.5 (Build 9065) and later.

Scene Interface	Files Interface	Menu Interface	Import Interface
Export Interface	Object Interface	Controller Interface	External Interface
Data Structures	C++ Support	Compiler Settings

What's New

Menu Interface

The Menu Interface allows a plugin to add menu items and submenus to Morays menu. It also handles mapping the IDs in your menu resource so that it doesn't conflict with either Morays menu IDs or those of other plugins.

The menu interface now has an easier way to setup the menu items which supercedes the somewhat cumbersome use of the GetItemInfo function.

The new way requires you to not implement any of the functions of this interface. The default implementation automatically builds everything it needs with the macros.

Reference List of Functions
By Function Group	Alphabetically
DECLARE_MENU_ITEMS BEGIN_MENU_ITEMS MENU_ITEM MENU_SEPARATOR MENU_SUBMENU MENU_SUBMENU_ITEM END_MENU_ITEMS GetItemInfo GetItemInfoEx GetItemState ItemSelected	BEGIN_MENU_ITEMS DECLARE_MENU_ITEMS END_MENU_ITEMS GetItemInfo GetItemInfoEx GetItemState ItemSelected MENU_ITEM MENU_SEPARATOR MENU_SUBMENU MENU_SUBMENU_ITEM

DECLARE_MENU_ITEMS

DECLARE_MENU_ITEMS( );

The macro DECLARE_MENU_ITEMS allows you to easily define menu items of the menu interface.

This macro should be included in the class definition of the CMenuInterface-derived class (in the header file).

Use the BEGIN_MENU_ITEMS, MENU_ITEM, MENU_SEPARATOR, MENU_SUBMENU, MENU_SUBMENU_ITEM macros to create the menu in the C++ code file.

BEGIN_MENU_ITEMS

BEGIN_MENU_ITEMS(theClass );

The macro BEGIN_MENU_ITEMS starts the definition of the menu structure that this interface creates.

theClass is the name of this Menu Interface class.

This macro should start off the menu definition of the CMenuInterface-derived class in the source file.

MENU_ITEM

MENU_ITEM(nWhereToAdd, pszItemText, rFuncToCall);

The macro MENU_ITEM defines a menu item and the action that should be taken when it is selected.

nWhereToAdd defines where the menu item is to be added and should be one of the following values:

MRY_MNU_ADD_TO_EDIT - if the menu item should be added to the Edit menu.
MRY_MNU_ADD_TO_VIEW - if the menu item should be added to the View menu.
MRY_MNU_ADD_TO_SCENE - if the menu item should be added to the Scene menu.
MRY_MNU_ADD_TO_RENDER - if the menu item should be added to the Render menu.
MRY_MNU_ADD_TO_PLUGINS - if the menu item should be added to the Plugins menu (default).
MRY_MNU_ADD_TO_TOOLS - if the menu item should be added to the Tools menu.
MRY_MNU_ADD_TO_HELP - if the menu item should be added to the Help menu.

pszItemText defines the menu items text.

rFuncToCall defines the function that should be called when the menu item is selected. This will be a member function of the CMenuInterface-derived class.

MENU_SEPARATOR

MENU_SEPARATOR(nWhereToAdd );

The macro MENU_SEPARATOR allows you to define a separator in the menu being defined.

nWhereToAdd defines where the menu item is to be added and should be one of the following values:

MRY_MNU_ADD_TO_EDIT - if the menu item should be added to the Edit menu.
MRY_MNU_ADD_TO_VIEW - if the menu item should be added to the View menu.
MRY_MNU_ADD_TO_SCENE - if the menu item should be added to the Scene menu.
MRY_MNU_ADD_TO_RENDER - if the menu item should be added to the Render menu.
MRY_MNU_ADD_TO_PLUGINS - if the menu item should be added to the Plugins menu (default).
MRY_MNU_ADD_TO_TOOLS - if the menu item should be added to the Tools menu.
MRY_MNU_ADD_TO_HELP - if the menu item should be added to the Help menu.

MENU_SUBMENU

MENU_SUBMENU(pszSubMenu, resID);

The macro MENU_SUBMENU allows you to add a submenu from a resource to the menu defined by this menu interface.

pszSubMenu defines the text of the submenu to be defined.

resID defines the resource ID of the submenu in the resource of the DLL containing the plugin. Note that you must use the MENU_SUBMENU_ITEM to associate the actions with each menu item in the submenu that this entry adds.

MENU_SUBMENU_ITEM

MENU_SUBMENU_ITEM(nID, rFuncToCall);

The macro MENU_SUBMENU_ITEM allows you to define actions that should be taken when menu items of a submenu defined by this menu interface are selected.

nID is the ID that defines the menu item that you want to associate with an action.

rFuncToCall is the function that should be called when the menu item is selected.

END_MENU_ITEMS

END_MENU_ITEMS( );

The macro END_MENU_ITEMS ends the menu layout for this menu interface.

GetItemInfo

The function GetItemInfo is used to query the plugin about any menu items it needs to add to the main menu.

long WINAPI fnGetItemInfo(int nIndex, int *pnFlags, char **ppszItemName, long *pnID);

Parameters

nIndex	Contains the index that Moray is querying. See Remarks.
pnFlags	Contains a pointer to the location where the plugin should write the flags. See Remarks.
ppszItemName	Contains a pointer to where the plugin should write the pointer that determines the item type. See Remarks.
pnID	Contains the location where the ID of the menu item is stored.

Return Values

MRY_SUCCESS	should be returned if there was a menu item to add.
MRY_ERR_NO_MORE_ITEMS	should be returned if there are no more menu items to add.

Remarks

The macro DECLARE_MENU_ITEMS and associated macros can be used to define menus instead of this function.

Moray calls this function until it returns MRY_ERR_NO_MORE_ITEMS, incrementing nIndex with each call. The plugin should initialize the rest of the three parameters according to the type of menu item it would like to add.

To add a simple menu item to an existing submenu set the fields as follows:

ppszItemName - should point to the text of the menu item. Include the ampersand if it should have an accelerator.
pnID - should be set to the ID that the plugin should receive when the user selectes this menu item.
pnFlags - should be set to zero (the item will be added to the Plugins submenu or one of the following values:
- MRY_MNU_ADD_TO_EDIT - if the menu item should be added to the Edit menu.
- MRY_MNU_ADD_TO_VIEW - if the menu item should be added to the View menu.
- MRY_MNU_ADD_TO_SCENE - if the menu item should be added to the Scene menu.
- MRY_MNU_ADD_TO_RENDER - if the menu item should be added to the Render menu.
- MRY_MNU_ADD_TO_PLUGINS - if the menu item should be added to the Plugins menu (default).
- MRY_MNU_ADD_TO_TOOLS - if the menu item should be added to the Tools menu.
- MRY_MNU_ADD_TO_HELP - if the menu item should be added to the Help menu.

To add a seperator at the end of a menu, set the fields as follows. Note that the plugin should only add separators BEFORE the plugins menu items, not after. That way there won't be multiple separators (with no items between) when multiple plugins add items to the same menu.

ppszItemName - should be set to NULL.
pnID - should be set to zero.
pnFlags - should be set to a combination of MRY_MNU_SEPARATOR and one of the fields listed above, according to which submenu the seperator should be added to.

To add a new submenu to the main menu set the fields as follows:

ppszItemName - should point to the text of the new submenu. Include the ampersand if you want to have an accelerator.
Be sure not to disable any of Morays hotkeys by this!
pnID - should contain the HMENU of the new submenu. The plugin can construct this menu either on-the-fly or load it from its resource script.
pnFlags - should be set to MRY_MNU_NEW_SUBMENU.

See Also

DECLARE_MENU_ITEMS

GetItemInfoEx

The function GetItemInfoEx is an enhanced way to query the plugin about any menu items it needs to add to the main menu.

long WINAPI fnGetItemInfoEx(int nIndex, LPMRY_MENU_COMMAND pCommand);

Parameters

nIndex	Contains the index that Moray is querying. See Remarks.
pCommand	Contains a pointer to a MRY_MENU_COMMAND struct that contains the details of the menu item. See Remarks.

Return Values

MRY_SUCCESS	should be returned if there was a menu item to add.
MRY_ERR_NO_MORE_ITEMS	should be returned if there are no more menu items to add.

Remarks

This function is an enhanced version of the GetItemInfo function and allows the plugin to also define up to two hotkeys for the menu item and to add commands without adding a menu item.
See MRY_MENU_COMMAND for details of the fields in the struct.

See Also

GetItemInfo, MRY_MENU_COMMAND

GetItemState

The function GetItemState is used to query the plugin about the state of one of its menu items.

long WINAPI fnGetItemState(int nID, LPMRY_MNU_ITEMSTATE pItemState);

Parameters

nID	Contains the ID of the menu item whose info is being retrieved.
pItemState	Contains the pointer to a MRY_MNU_ITEMSTATE structure that is to receive the info.

Return Values

MRY_SUCCESS

should be returned if the function was successful. Moray currently ignores the return value.

Remarks

This function is called by Moray just before displaying a submenu that contains a menu item associated with nID.

See Also

MRY_MNU_ITEMSTATE

ItemSelected

The function ItemSelected is called when the user has selected a menu item associated with the plugin.

long WINAPI fnItemSelected(int nID);

Parameters

nID

Contains the ID of the menu item that was selected.

Return Values

MRY_SUCCESS

should be returned if the function was successful. Moray currently ignores the return value.