Represents a custom menu in Softimage and provides the basic support for creating them.
The most important features of custom menus are:
Custom menus are self-installed plug-ins and are integrated in Softimage by dropping the plug-in file in the Application/Plugins folder.
A custom menu must be registered at startup time with PluginRegistrar::RegisterMenu. The registration function doesn't load the custom menu explicitly in memory; Softimage loads the menu only when it is requested by the user.
You must implement a callback function in order to build a menu and add menu items, this function is called by Softimage when the user opens the menu. The signature of this callback function is the following:
CStatus MyMenu_Init( const XSI::CRef& in_context )
{plugin_item_name}_Init
plugin_item_name
is the string passed to PluginRegistrar::RegisterMenu to identify the menu plug-in item.CStatus XSILoadPlugin( PluginRegistrar& in_reg ) { // register plugin information in_reg.PutAuthor( L"Softimage Corp." ); in_reg.PutName( L"Deform menu plugin" ); // set the version number of this plugin in_reg.PutVersion( 1, 0 ); // install a dynamic custom menu in the spatial section of the // toolbar panel deform menu bool bDynamic = true; bool bDisplayAsSubmenu = true; in_reg.RegisterMenu( siMenuToolbarDeformSpatialID, L"Custom", bDisplayAsSubmenu, bDynamic ); return CStatus::OK; } // This is the callback function used for building the menuItem. Since the // menu is dynamic, the function is called each time the menu opens. CStatus Custom_Init( XSI::CRef& in_ref ) { // retrieve the menu object to build Menu menu = Context( in_ref ).GetSource(); // set the menu caption menu.PutName( L"&Custom Deform" ); // attach the Twist command to the first menu item MenuItem menuItem; menu.AddCommandItem( L"&Twist", L"Twist", menuItem ); // adds a separator menu.AddSeparatorItem(); // adds other menu items and attach a function callback menu.AddItem( L"Custom &1", siMenuItem, menuItem ); menuItem.PutCallback( L"OnMenuItem" ); menu.AddCallbackItem( L"Custom &2", L"OnMenuItem", menuItem ); menu.AddCallbackItem( L"Custom &3", L"OnMenuItem", menuItem ); menu.AddSeparatorItem(); Menu subMenu = menuItem; menu.AddItem( L"&Sub menu", siMenuItemSubmenu, menuItem ); subMenu.AddCommandItem( L"Sub÷", L"Subdivide", menuItem ); // set the submenu menu with a polygon filter, the menu will be enabled // only if polygon mesh objects are selected subMenu.PutFilter( L"Polygon" ); return CStatus::OK; } // This callback function is called by Softimage when either // menu item 1 or 2 is selected XSI::CStatus OnMenuItem( XSI::CRef& in_ref ) { Context ctxt = in_ref; MenuItem menuItem = ctxt.GetSource(); Application app; app.LogMessage( menuItem.GetName() + L":" + menuItem.GetCallback() ); return CStatus::OK; }
#include <xsi_menu.h>
Public Member Functions | |
Menu () | |
~Menu () | |
Menu (const CRef &in_ref) | |
Menu (const Menu &in_obj) | |
bool | IsA (siClassID in_ClassID) const |
siClassID | GetClassID () const |
Menu & | operator= (const Menu &in_obj) |
Menu & | operator= (const CRef &in_ref) |
CStatus | AddItem (const CString &in_strLabel, const siMenuItemStyle in_pStyle, MenuItem &out_menuItem) |
Menu | AddSubMenu (const CString &in_strLabel) |
CStatus | AddCommandItem (const CString &in_strLabel, const CString &in_strCmd, MenuItem &out_menuItem) |
CStatus | AddCallbackItem (const CString &in_strLabel, const CString &in_strCallback, MenuItem &out_menuItem) |
CStatus | AddSeparatorItem () |
CStatus | PutFilter (const CString &in_strFilter) |
Menu | ( | ) |
Default constructor.
~Menu | ( | ) |
Default destructor.
bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
in_ClassID | class type. |
Reimplemented from MenuItem.
siClassID GetClassID | ( | ) | const [virtual] |
Creates an object from another object. The newly created object is set to empty if the input object is not compatible.
in_obj | constant class object. |
CStatus AddItem | ( | const CString & | in_strLabel, |
const siMenuItemStyle | in_pStyle, | ||
MenuItem & | out_menuItem | ||
) |
Adds a menu item at the end of the menu. This function doesn't attach a callback or command to the newly created menu item. You must call the proper function to do so (ie., Menu::AddCommandItem or Menu::AddCallbackItem).
in_strLabel | The menu item label |
in_pStyle | The menu item style. |
out_menuItem | The new MenuItem object. |
Add a sub-menu item to this menu onto which further MenuItem objects can be attached. This is useful for grouping similar actions together when there are many options in the menu. This method is similar to Menu::AddItem called with siMenuItemSubmenu.
in_strLabel | The sub-menu item label. |
CStatus AddCommandItem | ( | const CString & | in_strLabel, |
const CString & | in_strCmd, | ||
MenuItem & | out_menuItem | ||
) |
Adds a menu item at the end of the menu and attaches a command. The command is fired when the menu item is selected.
You can attach any native or custom commands you want to a menu item. If your menu is attached to a contextual menu and one of your command's arguments takes the selected objects by default, then the current selected object(s) is passed in to your command. The target object under the cursor is also passed in as part of the selected objects. However if no objects are selected then only the target is passed in.
in_strLabel | The menu item label |
in_strCmd | The name of a command. The API requires the command name not the command scripting name. Use EditCommand to find out the command name. |
out_menuItem | The new MenuItem object. |
CStatus AddCallbackItem | ( | const CString & | in_strLabel, |
const CString & | in_strCallback, | ||
MenuItem & | out_menuItem | ||
) |
Adds a menu item at the end of the menu and attaches a callback function. The callback is fired when the menu item is selected.
If your menu is attached to a contextual menu, the currently selected objects are passed into your callback. The target object under the cursor is also passed in as part of the selected objects. However if no objects are selected then only the target is passed in. The objects can be retrieved through the Context::GetAttributeValue function using the Target
attribute. The selected/target objects are not passed into the callback of a custom menu item attached to a regular menu.
in_strLabel | The menu item label |
in_strCallback | The name of the callback. |
out_menuItem | The new MenuItem object. |
CStatus AddSeparatorItem | ( | ) |
Adds a separator at the end of the menu.
Sets the filter for this menu. Softimage uses the filter for validating the menu against the target or selected objects before it gets displayed. If the filter criteria are not satisfied then the custom menu is greyed out or simply removed if attached to a contextual menu.
in_strFilter | Filter name. |
Reimplemented from MenuItem.