MenuItem

Object Hierarchy | Related C++ Class: MenuItem

Inheritance

SIObject

UIObject

MenuItem

Introduced

v4.0

Description

The MenuItem object represents an individual item of a custom Menu. With the MenuItem object you can attach a command or a callback function to a menu item and fire it when you click on the menu item.

Other features of custom menu items include:

- Menu items set with a command are greyed out if the command is disabled.

- Menu items will show the origin of the command or callback ([u] for user, [w] for workgroup).

- Menu items that point to a command will show the hotkey associated with the command.

- Set them with a Filter to validate the menu items against the selected/target object(s) before opening the menu. Custom menus are greyed out or removed if the filter criteria is not satisfied.

- Callback functions are undoable provided that commands or object model methods they used supports undo and redo.

A menu item can be defined as a standard menu item on which you can attach a command or callback function (Note: If for some reasons you assign both a command and a callback to your menu item, the callback will have precedence over the command when the menu item is selected). You can also create a menu item as a separator or as a sub menu. See the Menu object documentation for more details about adding menu items to a custom menu.

Methods

IsClassOf operator IsEqualTo operator SetBackgroundColor  
       

Properties

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

Examples

JScript Example

// JScript implementation example of a custom menu item 
// This function is required to register the menu in Softimage
//
// README: Copy and paste the example into the script editor 
// and run (F5).
//
// The menu will install itself into the main window menu
//-------------------------------------------------------------------
function  XSILoadPlugin( in_reg )
{
	// register plug-in information
	in_reg.Author = "Softimage Co." ;
	in_reg.Name = "MenuItem Example";
	//  the version number of this plug-in
	in_reg.Major = 1;
	in_reg.Minor = 0 ;
	// install a custom menu in the window menu 
	in_reg.RegisterMenu( siMenuMainWindowID, "ExMenuItem", true, true );
	return true;
}
// This is the callback function used for building the menu. Since the menu is
// dynamic, the function is called each time the menu opens.
function  ExMenuItem_Init( in_ctxt )	
{
	// retrieve the menu object to build 
	menu = in_ctxt.Source;
	// attach a menu item to the menu along with its function handler
	menu.AddCallbackItem( "Custom menu item", "OnMenuItem" );
	return true;
}
//This callback function is called by Softimage when the menu item is 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" +	
		ExMenuItem_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 	= "ExMenuItem";
	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

Menu