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.

See Also

BEGIN_MENU_ITEMS, MENU_ITEM, MENU_SEPARATOR, MENU_SUBMENU, MENU_SUBMENU_ITEM, END_MENU_ITEMS


Top
 

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.

See Also

DECLARE_MENU_ITEMS, MENU_ITEM, MENU_SEPARATOR, MENU_SUBMENU, MENU_SUBMENU_ITEM, END_MENU_ITEMS


Top
 

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:

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.

See Also

DECLARE_MENU_ITEMS, BEGIN_MENU_ITEMS, MENU_SEPARATOR, MENU_SUBMENU, MENU_SUBMENU_ITEM, END_MENU_ITEMS


Top
 

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:

See Also

DECLARE_MENU_ITEMS, BEGIN_MENU_ITEMS, MENU_ITEM, MENU_SUBMENU, MENU_SUBMENU_ITEM, END_MENU_ITEMS


Top
 

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.

See Also

DECLARE_MENU_ITEMS, BEGIN_MENU_ITEMS, MENU_ITEM, MENU_SEPARATOR, MENU_SUBMENU_ITEM, END_MENU_ITEMS


Top
 

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.

See Also

DECLARE_MENU_ITEMS, BEGIN_MENU_ITEMS, MENU_ITEM, MENU_SEPARATOR, MENU_SUBMENU, END_MENU_ITEMS


Top
 

END_MENU_ITEMS


   END_MENU_ITEMS( );

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

See Also

DECLARE_MENU_ITEMS, BEGIN_MENU_ITEMS, MENU_ITEM, MENU_SEPARATOR, MENU_SUBMENU


Top
 

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:


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.


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

See Also

DECLARE_MENU_ITEMS


Top
 

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


Top
 

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


Top
 

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.


Top