maya-toolbar 0.2.0

Ever wanted more space on your shelf?

maya-toolbar is a user interface designed to quickly access and execute user-defined commands.

Features

• Resizable UI
• Dockable UI
• Persistent UI
• Customizable

Table of Contents

• System Requirements
• Installation
  • Manual
  • pip
• Usage
• Add New Tabs
• YAML References
  • Tab
  • Category
  • Command
  • Menu
  • Menu item
    • command
    • separator
    • menu
• Execute function
• Environment Variables
  • TOOLBAR_PATH_DISCOVER
  • TOOLBAR_ACTIVE_TAB
  • TOOLBAR_AUTOLOAD
• Special Thanks

System Requirements

• Autodesk Maya (2020+)

  In theory, it may run in older maya versions, but those are never being tested. If you try to use it on one of these versions and everything seems to works properly, please do not hesitate to let me know! :)

  Note that the tool does not currently support maya 2025+ due to the upgrade of the pyside library to the version 6. I plan to add a support using the Qt.py in a future release.

• YAML

  This will allow to write proper and readable configuration files that the UI will read to generate the user interface. The library is not included with the Maya installation, so we need to install it separately. Please see the installation section below for details.

Installation

The installation can be done using two different methods.

Manual

1. Located the maya script directory (or any other directory that will be available in the PYTHONPATH).

   • Linux
     • ~/maya/scripts
     • ~/maya/{VERSION}/scripts
   • Windows
     • ~/Documents/maya/scripts
     • ~/Documents/maya/{VERSION}/scripts
   • Mac OS
     • Library/Preferences/Autodesk/maya/scripts
     • Library/Preferences/Autodesk/maya/{VERSION}/scripts

2. Install pyyaml package.

   If your workstation is in a studio, there is a good chance that the library is already installed. If you are not sure, you can try running the following code:

   import yaml
   

   If an ImportError is raised, the library needs to be installed, otherwise, you're good to go :)

   The easiest way to install it is to use pip. The --target option allows us to change the directory in which the package will be installed. In our case, we want to use the scripts directory found above (or another directory that is a part of the PYTHONPATH).

   pip install pyyaml --target ~/maya/scripts
   

3. Download the file maya_toolbar.py and save it inside the scripts directory.

4. See usage below.

pip

maya-toolbar is also uploaded on PyPI and can directly be installed using pip. This means that all the dependencies will be automatically be installed without doing anything else!

pip install maya-toolbar

Like in the manual section, its possible to use the --target option to install the package in other directory, for example, the maya scripts folder.

Usage

To open the toolbar, get a new python tab inside the script editor, and execute the following lines:

import maya_toolbar
maya_toolbar.show()

The user interface will added to the current workspace. This means that it will automatically reopen where it was left for the next Maya session!

Enjoy! :)

Add New Tabs

Each tab is represented by a single YAML file which contains all the configuration to generate the UI.

By default the tabs will be searched in the following directories (where ~ represent the $HOME directory):

• Linux
  • ~/toolbar
  • ~/maya/toolbar
  • ~/maya/{VERSION}/prefs/toolbar
• Windows
  • ~/toolbar
  • ~/Documents/maya/toolbar
  • ~/Documents/maya/{VERSION}/prefs/toolbar
• Mac OS
  • ~/toolbar
  • Library/Preferences/Autodesk/maya/toolbar
  • Library/Preferences/Autodesk/maya/{VERSION}/prefs/toolbar

In addition to these directories, every maya module that contains a directory called toolbar will also be included.

Arbitrary directories can also be added using the TOOLBAR_PATH_DISCOVER environment variable or directly from the python interpreter using the PATH_DISCOVER attribute:

export TOOLBAR_PATH_DISCOVER = $TOOLBAR_PATH_DISCOVER:path/to/directory

import maya_toolbar
maya_toolbar.PATH_DISCOVER.append("path/to/directory")
maya_toolbar.show()

YAML References

All the configure of the toolbar are done through YAML files. There will be no explanation of syntax here but its possible to learn it from the official documentation.

See bellow all the different options available for each component of the toolbar.

Tab

• name (str) - The name of the tab. If not specified, the name of the file will be used (without the extensions).
• load (bool) - Specify if the configuration should be loaded as a tab or not. Defaults to AUTOLOAD.
• categories (list) - The configuration of the categories.

name: demo
load: true
categories: []

Category

• name (str) - The name of the category.
• open (bool) - Should the category be extended or collapsed by default? Defaults to false.
• commands (list) - The configuration of the commands.

name: Category A
open: false
commands: []

Command

• name (str) - The name of the command (Displayed as a tooltip).
• icon (str) - The icon with which the command will be displayed.
• label (str) - A short text that will be displayed below the command.
• callback (str) - The function that should be executed (see the syntax here).
• menu (dict) - The configuration of the menu.

name: Command A
icon: :mayaCommand.png
label: a
callback: maya.cmds:NewScene
menu: {}

Menu

• click (str) - The click that will show the menu (left or right). Defaults to right.
• items (list) - The item to add as children.

name: Menu A
click: right
items: []

Menu item

• type (str) - The type of the item to add. For each of them, different options are available:

Additional options are available according to the specified type:

command

• name (str) - The name of the command.
• icon (str) - The icon with which the command will be displayed.
• callback (str) - The function that should be executed (see the syntax here).

type: command
name: Menu command A
icon: :mayaCommand.png
callback: maya.cmds:NewScene

separator

No options are available.

type: separator

menu

• name (str) - The name of the menu.
• icon (str) - The icon with which the menu will be displayed.
• items (list) - The item to add as children.

type: menu
name: Menu A
icon: :mayaCommand.png
items: []

Execute function

To call a function, a special syntax similar to setuptools is used. The package name is separated from the function name using a :, where the package can be anything accessible from python (inside the PYTHONPATH)).

So for example, if we have a module called commands.py available inside our PYTHONPATH and that contains the following code:

def hello_world():
    print("Hello Word!")

Inside the YAML configuration file, we can point to our hello_world function using:

callback: commands:hello_world

Environment Variables

Functionalities of the toolbar can be modified using environment variables.

TOOLBAR_PATH_DISCOVER

Similar to what python does with the PYTHONPATH) variable, this allows the specified custom path to include in the search for the tab configuration file.

echo $TOOLBAR_PATH_DISCOVER

The equivalent attribute in the python module is PATH_DISCOVER:

import maya_toolbar
maya_toolbar.PATH_DISCOVER

TOOLBAR_ACTIVE_TAB

The name of the tab that should have the focus when the user interface is opened or reloaded.

echo $TOOLBAR_ACTIVE_TAB

The equivalent attribute in the python module is ACTIVE_TAB:

import maya_toolbar
maya_toolbar.ACTIVE_TAB

TOOLBAR_AUTOLOAD

Set the default loading behaviour for discovered configuration files.

1 means that all configuration files will be automatically loaded, unless load: false is explicitly specified.

0 is the exact opposite. Each configuration file will not be considered for loading unless the load: true option is specified.

echo $TOOLBAR_AUTOLOAD

The equivalent attribute in the python module is AUTOLOAD:

import maya_toolbar
maya_toolbar.AUTOLOAD

Special Thanks

• @BenoitGielly for the original idea and implementation!