RegisterMenu (PluginRegistrar)

Description

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.

Scripting Syntax

PluginRegistrar.RegisterMenu( Anchor, Name, [DisplayAsSubmenu], [Dynamic] )

C# Syntax

PluginItem PluginRegistrar.RegisterMenu( siMenuAnchorPoints in_menuID, String in_menuName, Boolean in_bDisplayAsSubmenu, Boolean in_bDynamicMenu );

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

Return Value

PluginItem

Examples

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);
   }
}

See Also

PluginItem

Definition Callbacks for Menus

Autodesk Softimage v7.5