## 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 | 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 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