#include <xsi_menu.h>

Class Description

Represents a custom menu in Softimage and provides the basic support for creating them.

The most important features of custom menus are:

Built on demand through a callback function when the end-user opens the menu.

Can be attached to Softimage native menus (aka hosting menus) sof specific views.

Can be created either as a dynamic or static menu: a dynamic menu is always rebuilt before the menu opens whereas static menus are only built once.

Can be displayed either as a submenu or as a flat list of items in the hosting menu.

Can be set with a Filter for validating the menu items against the target/selected object(s) before opening the menu.

The location where custom menus can be attached are identified with anchor points, see siMenuAnchorPoints for a complete list.

Can be shared by multiple views, the same menu can be registered in different views with different anchor points and display options. This maximizes the code reusability of custom menus in Softimage.

Custom menus are self-installed plug-ins and are integrated in Softimage by dropping the plug-in file in the Application/Plugins folder.

Note:: Softimage doesn't allow you to create a custom menu by running a script from the scripting editor: you must implement a menu plug-in.

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 )

in_context

The Context object containing the menu to build. The function name must be formatted as

 {plugin_item_name}_Init

where plugin_item_name is the string passed to PluginRegistrar::RegisterMenu to identify the menu plug-in item.

Note:: The function return value is not required by Softimage.

See also:: MenuItem, cus_menus

Since:: 4.0

Example:: Example showing a simple custom menu plugin.

                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&divide", 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;
                }

Inheritance diagram for Menu:

List of all members.

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)

Constructor & Destructor Documentation

Menu ( )

Default constructor.

~Menu ( )

Default destructor.

Menu ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

Menu ( const Menu & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

Search for all occurrences

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID class type.

Returns:: true if the class is compatible, false otherwise.

Reimplemented from MenuItem.

siClassID GetClassID ( ) const [virtual]

Search for all occurrences

Returns the type of the API class.

Returns:: The class type.

Reimplemented from MenuItem.

Menu& operator= ( const Menu & in_obj )

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

in_obj constant class object.

Returns:: The new Menu object.

Menu& operator= ( const CRef & in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref constant class object.

Returns:: The new Menu object.

Reimplemented from MenuItem.

CStatus AddItem	(	const CString &	in_strLabel,
		const siMenuItemStyle	in_pStyle,
		MenuItem &	out_menuItem
	)

Search for all occurrences

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).

Parameters:

in_strLabel	The menu item label
in_pStyle	The menu item style.

Return values:

out_menuItem The new MenuItem object.

Returns:: CStatus::OK success; CStatus::Fail failure

Menu AddSubMenu ( const CString & in_strLabel )

Search for all occurrences

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.

Parameters:

in_strLabel The sub-menu item label.

Returns:: Newly added sub-menu object

CStatus AddCommandItem	(	const CString &	in_strLabel,
		const CString &	in_strCmd,
		MenuItem &	out_menuItem
	)

Search for all occurrences

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.

Parameters:

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.

Return values:

out_menuItem The new MenuItem object.

Returns:: CStatus::OK success; CStatus::Fail failure

CStatus AddCallbackItem	(	const CString &	in_strLabel,
		const CString &	in_strCallback,
		MenuItem &	out_menuItem
	)

Search for all occurrences

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.

Parameters:

in_strLabel	The menu item label
in_strCallback	The name of the callback.

Return values:

out_menuItem The new MenuItem object.

Returns:: CStatus::OK success; CStatus::Fail failure

CStatus AddSeparatorItem ( )

Search for all occurrences

Adds a separator at the end of the menu.

Returns:: CStatus::OK success; CStatus::Fail failure

CStatus PutFilter ( const CString & in_strFilter )

Search for all occurrences

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.

Parameters:

in_strFilter Filter name.

Returns:: CStatus::OK success; CStatus::Fail failure

Deprecated:: 6.0 This method is required for backward compatibility, use MenuItem::Filter instead.

Reimplemented from MenuItem.

The documentation for this class was generated from the following file:

xsi_menu.h

Class Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation