The top-level menu. This element can have the following attributes:

Inside a <subMenu>, attaches a menu item that triggers a Python script when the user chooses it.

For context menu items, the given script runs in a Python scope containing a kwargs variable. This is a dictionary containing useful information about the item the user invoked the menu on. Different context menus provide different keys. See the menu files in $HFS/houdini for more information.

The <scriptItem> element can have the following sub-elements.

<scriptItem id="h.my_item">
    <label>Geometry...</label>
        <scriptCode><![CDATA[
        import soptoolutils

    soptoolutils.chooseAndOpenGeoFile({}, False)
    ]]></scriptCode>
</scriptItem>

<scriptItem id="my_action">
    <label>My Action</label>
    <scriptCode><![CDATA[
        arguments = '\n  '.join(['%s = %s' % (k,w) for (k,w) in kwargs.items()])
        hou.ui.displayMessage('My Action with kwargs:\n  ' + arguments)
        ]]>
    </scriptCode>
</scriptItem>

Inside <menuBar> (in main menu files), this attaches a top-level menu. Inside <menu> (in context menu files) or another <subMenu>, it creates a sub-menu.

The first child of the <subMenu> element should be a <label> element containing the menu’s label text.

<subMenu id="animation_menu">
    <label>Channels and Keyframes</label>

    <actionItem id="scope_append_channels" />
    <actionItem id="scope_channels"/>
        <separatorItem/>
        <actionItem id="set_keyframe"/>
        ...
    </subMenu>

The <subMenu> element can have the following attributes:

Inside a <menu> or <subMenu> element, creates a separator line.

Creates a read-only title to help categorize the items following it in the menu.

Creates a menu item that invokes a built-in Houdini command based on the hotkey symbol in the id attribute.

In the main menu files:

• The id attribute on the <actionItem> element identifies the internal Houdini command (hotkey symbol) invoked by the menu item.

• An <actionItem> element has a child <label> element containing the menu item’s label text.

<actionItem id="h.startuphelp">
    <label>Start Here</label>
</actionItem>

In context menus:

• The id attribute specifies a suffix to be appended to a common command (hotkey symbol) for all items in the menu.

  For example, in the PARMmenu.xml (parameter context menu) configuration file, all id attributes correspond to hotkeys with the h.pane.parms prefix. So, an item with id="revert_to_prev_val" would refer to the h.pane.parms.revert_to_prev_val hotkey action.

• The menu item labels for built-in functions are dynamically generated. Houdini will ignore any <label> element inside an <actionItem>.

<actionItem id="set_keyframe"/>

You can use <actionId> tag to create a menu item alias of another item. This way, a new item with a new label can be placed in any location, and it will perform the action of another menu item.

<actionItem id="set_keyframe_alias">
    <actionId>set_keyframe</actionId>
</actionItem>

Creates a strip of dynamically-generated menu items defined by a Python script. The strip must be contained in a <menu> or <subMenu> element. The id attribute on the <scriptMenuStripDynamic> element identifies and registers an internal Houdini command (hotkey symbol) invoked by the menu items in the strip.

The <scriptMenuStripDynamic> element can have the following sub-elements.

• <contentsScriptCode>:

  Contains a Python script that returns the strip’s menu items as a sequence of strings. The sequence stores the menu items' internal token names and their labels. For example, ['one', 'Apples', 'two', 'Cream Pie'] would correspond to two menu entries with internal token names "one" and "two" and labels "Apples" and "Cream Pie".

  If the Python script contains only one line, then Houdini evaluates it as a Python expression. If it contains multiple lines, then Houdini evalutes it as a function body and requires that the last line 'returns' the string sequence.

  A kwargs global dictionary variable is made available to the Python script. The dictionary stores information pertaining to the menu’s current context. For example, the parameter RMB-menu stores a parms entry in kwargs with a list of node parameters that the menu currently applies to. You can use the entries in kwargs to conditionally choose which menu items appear in the strip.

  Note

  When accessing kwargs entries in the contents script you should first check if the entries exist to ensure that your script does not raise an exception. This is required because the contents script may execute when the menu opens but before the menu strip opens and the kwargs dictionary is fully initialized.

  For example, access kwargs entries using the get(...) method:

  node = kwargs.get("node", None)
  if node:
      # Access node properties...
      ...
  

• <scriptCode>:

  Contains a Python script to be executed when the user chooses a menu item from this strip.

  A kwargs global dictionary variable is made available to the Python script. The dictionary stores information pertaining to the menu’s current context. It also contains selectedtoken and selectedlabel entries that store the internal token name and label of the selected menu item respectively.

  The script executes immediately when the menu item is selected. To defer script execution until after the menu closes, see Deferring execution of <scriptCode>.

Here is an example of a scripted dynamic menu strip:

<subMenu id="mySubMenuId">
    <label>Colors</label>
    <scriptMenuStripDynamic id="myUniqueDynamicStripId">
        <contentsScriptCode><![CDATA[
        menu_items = ["red", "The Color Red", "green", "The Color Green", "blue", "The Color Blue"]
        return menu_items
        ]]></contentsScriptCode>
        <scriptCode><![CDATA[
        import hou

        selected_token = kwargs["selectedtoken"]
        selected_label = kwargs["selectedlabel"]

        hou.ui.displayMessage("You have selected %s (%s)." % (selected_label, selected_token))
        ]]></scriptCode>
    </scriptMenuStripDynamic>
</subMenu>

Insert this item at the beginning of the menu, before existing items.

Insert this item before the item with id="id".

Insert this item at the end of the menu, after existing items.

Insert this item after the item with id="id".

Insert this item at the nthe position in the menu.

This tag inside <mainMenu> lets you add a single script item to an existing parent menu without duplicating the menu structure as shown above.

<mainMenu>
    <addScriptItem id="h.mypref">
        <label>My Preference</label>
        <parent>preferences_submenu</parent>
        <insertBefore>h.prefs_viewports</insertBefore>

        <scriptPath>$HOME/scripts/generic_script.py</scriptPath>
    </addScriptItem>
</mainMenu>

This tag inside <mainMenu> lets you relabel, rearrange, or re-parent an existing item.

A <modifyItem> element can contain <label>, <parent>, <insertAfter>, <insertBefore>, and <insertAtIndex> elements.

For example, the following XML code moves the Render ▸ Create Render Node ▸ Other Output Nodes ▸ Dynamics item one level up:

<mainMenu>
    <modifyItem id="h.create_dynamics">
        <label>Moved Dynamics</label>
        <parent>render_create_submenu</parent>
        <insertBefore>render_create_subsubmenu</insertBefore>
    </modifyItem>
</mainMenu>

You can also use the <modifyItem> tag within the <menuBar> definition structure to adjust any items previously defined.

This tag inside <mainMenu> lets you remove an existing item.

For example, the following XML code moves the Desktop sub-menu to the top level and removes the unnecessary separator.

<mainMenu>
  <menuBar>
    <subMenu id="desktop_submenu">
      <insertBefore>help_menu</insertBefore>
    </subMenu>
  </menuBar>

  <removeItem id="windows_menu_sep_0"/>
</mainMenu>