Object Model: Menu

The Menu object provides the basic support for creating custom menus. With custom menus, you can:

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

- Attach custom menus to a Softimage menu (sometimes called a "hosting menu"). The hosting menu can be a regular or contextual menu within a specific Softimage view.

- Create them as either a dynamic or static menu: a dynamic menu is always rebuilt each time the menu opens, whereas static menus are built once.

- Display them as either as a submenu or as a flat list of items in the hosting menu.

- Indentify anchor points indicating the of the custom menu. See siMenuAnchorPoints for a complete list.

- Make multiple views share the same custom menu. 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. You cannot create a custom menu by running a script from the script editor; rather, you must implement a menu plug-in. Therefore, you must register the custom menu at startup time by using PluginRegistrar.RegisterMenu, The registration function doesn't load the custom menu explicitly in memory; Softimage will load the menu only when it is requested by the user. See Registering Plug-in Items for more details regarding implementing these kinds of self-installing items.

You must implement a callback function in order to build a menu and add menu items. The callback function is called by Softimage when the user opens the menu. The function name must be formatted as {plug-in_item_name}_Init where plug-in_item_name is the string passed to PluginRegistrar.RegisterMenu to identify the menu plug-in item. For more information, see Definition Callbacks for Menus.

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

Methods

AddCallbackItem	AddCallbackItem2	AddCommandItem	AddCommandItem2
AddItem	AddItem2	AddSeparatorItem	AddSubMenu
IsClassOf	IsEqualTo	SetBackgroundColor

Properties

Application	Callback	Categories	Checked
Command	Enabled	Filter	FullName
Help	Name	NestedObjects	Origin
OriginPath	Parent	Style	Type

Examples

JScript Example

//-------------------------------------------------------------------
// JScript implementation example of a custom menu plug-in.
//
// README: Copy and paste the example into the script editor 
// and run (F5).
//
// The menu will install itself into the modelling toolbar
// in the modify deform section.
//-------------------------------------------------------------------
// This function is required to register the menu in Softimage
function XSILoadPlugin( in_reg )
{
        // register plug-in information
        in_reg.Author = "Softimage Corp.";
        in_reg.Name = "Menu Example";
        // var the version number of this plug-in
        in_reg.Major = 1;
        in_reg.Minor = 0;
        // install a dynamic custom menu in the spatial section in the deform menu (model toolbar)
        in_reg.RegisterMenu( siMenuTbDeformSpatialID, "MenuExample", true, true );
        return true;
}
// This is the callbackfunction used for building the menu. Since the menu is
// dynamic, thefunction is called each time the menu opens.
function MenuExample_Init( in_ctxt )    
{
        // retrieve the menu object to build 
        var menu = in_ctxt.Source;
        // var the menu caption
        menu.Name = "&Custom Deform";
        // attach the Twist command to the first menu item
        menu.AddCommandItem( "&Twist", "Twist" );
        // adds a separator     
        menu.AddSeparatorItem();
        // adds other menu items and attach afunction callback
        var item = menu.AddItem( "Custom &1", siMenuItem );
        item.Callback = "OnMenuItem";
        menu.AddCallbackItem( "Custom &2", "OnMenuItem" );
        menu.AddCallbackItem( "Custom &3", "OnMenuItem" );
        menu.AddSeparatorItem();
        var submenu = menu.AddSubMenu( "&function menu" );
        submenu.AddCommandItem( "Sub&divide", "Subdivide" );
        // var the submenu menu with a polygon filter, the menu will be enabled only 
        // if polygons are selected.
        submenu.Filter = "Polygon";
        return true;
}
// This callbackfunction is called by Softimage when the menu item 1 or 2 are 
// selected
function OnMenuItem( in_ctxt )
{
        var menuitem = in_ctxt.source;
        LogMessage( menuitem.name + ":" + menuitem.callback );
}
//--------------------------------------------------------------------
// Code to bootstrap example into system
//--------------------------------------------------------------------
function ExampleSourceCode()
{
        return "// XSISDK Doc Example\n" +      
                MenuExample_Init.toString() + "\n" + 
                OnMenuItem.toString() + "\n" + 
                XSILoadPlugin.toString();
}
// if we are running from script editor save code to 
// examples addon folder in the user's directory.
if (GetUserPref("ScriptingSessionActive"))
{
        var ex_name             = "ExMenu";
        var ex_subfolder        = "Plugins";
        var ex_folder           = "XSISDKDocExamples";
        var ex_langsuffix       = ".js";
        CreateAddonDirectories( InstallationPath(siUserPath), ex_folder );
        var fso = XSIFactory.CreateActiveXObject("Scripting.FileSystemObject");
        var filename = XSIUtils.BuildPath( 
                InstallationPath(siUserAddonPath), 
                ex_folder,
                "Application",
                ex_subfolder,
                ex_name+ex_langsuffix );
        if (!fso.FileExists(filename))
        {
                var f = fso.CreateTextFile ( filename );
                f.write( ExampleSourceCode() );
                f.close();
                Application.LoadPlugin(filename);       
        }
}

Menu

Inheritance

Introduced

Description

Methods

Properties

Examples

JScript Example

See Also