MEL How-To #30

How do I create and edit Shelf buttons?

First, you need to find the name of the official ‘shelfLayout’ which comprises Maya's own Shelf. This is easy -- Maya stores the UI identity of the Main Shelf in the global string variable $gShelfTopLevel:

global string $gShelfTopLevel;
print $gShelfTopLevel;
// Result: MayaWindow|mayaMainWindowForm|formLayout2|formLayout22|ShelfLayout //

This is a little deceptive, as this is not a shelfLayout, but rather a tabLayout; it's the tabLayout that provides you with the ability to create multiple, tabulated categories of Shelves.

The "child array" of the tabLayout will give you an array of shelfLayouts that contain your tools:

// Get the array of Shelves (the row of tabs you see in Maya)
tabLayout -q -childArray $gShelfTopLevel;
// Result: Animation Colouring Polygon Primitives Render Tools //

// Now get the actual contents of the "Polygon" Shelf
shelfLayout -q -childArray "Polygon";
// Result: toolButton2 toolButton3 shelfButton54 shelfButton55 //

Note that if you wish to edit an item from a Shelf you must determine whether the item is a "shelfButton" or a "toolButton", as you require a different command to query the parameters of each.

objectTypeUI "toolButton2";
// Result: toolButton //

// This is a toolButton - must use ‘toolButton’ to query
// which Tool is activated by this button.
toolButton -q -tool "toolButton2";
// Result: polyCreateFacetCtx1 //

objectTypeUI "shelfButton54";
// Result: shelfButton //

// This is a shelfButton - must use ‘shelfButton’ to query
// the command string for this button.
shelfButton -q -command "shelfButton54";
// Result: performPolyCollapse 0 //

To add your own button to a shelf, use the ‘shelfButton’ command, specifying the desired shelfLayout as the parent for the button.

For an example of a complete Shelf Button definition, load up your Shelves Preference file into a text editor. The Preference file will be a MEL script named with the prefix "shelf_" plus the name of the Shelf, and a ".mel" extension. For example:

%MAYA_APP_DIR%\2.5\prefs\shelves\shelf_Polygon.mel

The definition stored for "shelfButton54" above is:

shelfButton
   -enable 1
   -width 34
   -height 34
   -manage 1
   -visible 1
   -annotation "Collapse: Collapse the selected edges or faces"
   -label "Collapse"
   -image1 "polyCollapseEdge.xpm"
   -style "iconOnly"
   -command "performPolyCollapse 0"
;

For a simple example, if you wanted to add a button to the "Tools" Shelf that cleared the selection list:

global string $gShelfTopLevel;

string $shelves[] = `tabLayout -q -childArray $gShelfTopLevel`;
// Result: Animation Colouring Polygon Primitives Render Tools //

// Note: $shelves[5] == "Tools"

// Now add the button
string $myButton = `shelfButton
     -parent $shelves[5]           // Set parent Shelf as "Tools"
     -enable 1
     -width 34
     -height 34
     -manage 1
     -visible 1
     -annotation "Clear the selection list"
     -label "Select None"
     -image1 "select.xpm"
     -style "iconOnly"
     -command "select -clear"`;

Note that the command string can be as long as you need it, provided it is syntactically valid within the quotes.

Use a string variable -- in this case $myButton -- to access the properties of your new button after it is created.

deleteUI $myButton;

If you need to delete one of your buttons afterward, without knowing the specific UI identity, you can query the child array of a shelfLayout looking for your specific command or label, or for a sub-string in either (such as a comment).

string $shelfButtons[] = `shelfLayout -q -childArray $shelves[5]`;

for ( $button in $shelfButtons )
{
   string $label;

   // Assert that this is a shelfButton
   if ( `objectTypeUI -isType "shelfButton" $button` )
   {
      $label = `shelfButton -q -label $button`;

      // If this button has the label we're looking for,
      // delete the button.
      if ( "Select None" == $label )
         deleteUI $button;
   }
}

After adding (or deleting) Shelf buttons, the new configuration will be saved with Maya's Shelf Preferences. The options for saving Shelf Preferences can be set using:

To explicitly save the Shelf Preferences, use the following:

global string $gShelfTopLevel;
saveAllShelves $gShelfTopLevel;

Related How-To's

Tuesday, March 20, 2001