MenuItem

Object Hierarchy | Related C++ Class: MenuItem

Inheritance

    SIObject
       UIObject
           MenuItem

Introduced

4.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

Properties

Application | Callback | Categories | 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 bootscrap 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

Autodesk Softimage v7.5