PluginRegistrar.RegisterMenu

Registers a custom Menu in Softimage. The menu is loaded and initialized only when the user opens it from the UI. The location of a menu is specified by anchor points (see siMenuAnchorPoints for a complete list).

You can register the same menu at multiple locations, and multiple menus at the same location. A menu can be a submenu or a flat list of items. A menu can also be dynamic or static: a dynamic menu is rebuilt every time it is displayed, while a static menu is built once only.

See Menu for details about creating a custom menu.

C# Syntax

Scripting Syntax

Return Value

Parameters

Parameter Type Description

Anchor siMenuAnchorPoints Specifies the location of the menu.

Name String The name of the custom menu to register. It should begin with a letter and contain only letters, numbers and the underscore character.

If a menu name contains spaces (for example, "My Custom Menu"), the names of the menu callback functions must omit the spaces (for example, "MyCustomMenu_Init").

If the menu is a submenu (DisplayAsSubmenu == True), or if the menu is added to the top-level of the Softimage main menubar (Anchor == siMenuMainTopLevelID), then the menu name is used as the menu caption.

You cannot change the caption of a top-level menu. For all other menus, you can change the caption by setting the Menu.Name property in the Init callback.

DisplayAsSubmenu Boolean True to display the custom menu as a submenu.
Default Value: True

Dynamic Boolean Sets the menu as dynamic or static: a dynamic menu is always rebuilt before the menu opens whereas static menus are only built once.
Default Value: True

Examples

Parameter	Type	Description
Anchor	siMenuAnchorPoints	Specifies the location of the menu.
Name	String	The name of the custom menu to register. It should begin with a letter and contain only letters, numbers and the underscore character. If a menu name contains spaces (for example, "My Custom Menu"), the names of the menu callback functions must omit the spaces (for example, "MyCustomMenu_Init"). If the menu is a submenu (DisplayAsSubmenu == True), or if the menu is added to the top-level of the Softimage main menubar (Anchor == siMenuMainTopLevelID), then the menu name is used as the menu caption. You cannot change the caption of a top-level menu. For all other menus, you can change the caption by setting the Menu.Name property in the Init callback.
DisplayAsSubmenu	Boolean	True to display the custom menu as a submenu. Default Value: True
Dynamic	Boolean	Sets the menu as dynamic or static: a dynamic menu is always rebuilt before the menu opens whereas static menus are only built once. Default Value: True

JScript Example

/*-------------------------------------------------------------------
	This example shows how to register and implement 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 application's Window menu
-------------------------------------------------------------------*/
function  XSILoadPlugin( in_reg )
{
	in_reg.Author = "Softimage Co.";
	in_reg.Name = "PluginRegistrar.RegisterMenu Example";
	// register the menu item 
	in_reg.RegisterMenu( siMenuMainWindowID, "Window_Menu", false );
	// "Sample menu has been installed in the Window menu"
	return true;	
} 
function  Window_Menu_Init( in_ctxt )
{
	var oMenu = in_ctxt.source;
	oMenu.AddCallbackItem( "Sample", "OnWindowMenu");
}
function  OnWindowMenu( in_ctxt )
{
	var oMenuItem = in_ctxt.source;
	Application.LogMessage("OnWindowMenu: " + oMenuItem .name );
}
//--------------------------------------------------------------------
// Code to bootstrap example into system
//--------------------------------------------------------------------
function ExampleSourceCode()
{
	return "// XSISDK Doc Example\n" +	
		Window_Menu_Init.toString() + "\n" + 
		OnWindowMenu.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 	= "ExPluginRegistrarRegisterMenu";
	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);	
	}
}