Writing Workspace controls

You can use workspace controls to create custom UI that can be dragged, docked and saved within Maya's workspaces system. Workspace controls are created using the workspaceControl command. Calling the command with a script passed to the uiScript flag that creates the internal UI, allows the workspaces system to save it to a given workspace, and properly restore the control the next time it is opened. Note that anything called in that script must be available for execution during any subsequent Maya startup, which is the time that any saved workspace is restored.

MEL scripts have to be sourced while Python modules have to be imported. The only exceptions are as follows:

Calls to access another workspace control or its contained UI. In this case, you must provide the requiredControl flag with the name of the other workspace control. Be aware of cyclical dependencies, such as controls that require each other.
Calls to functionality from a plug-in. In this case, you user must provide the requiredPlugin flag with the name of the plug-in.

Workspace controls replace the dockControl command which was previously used to create UI that could be docked around the four sides of the central viewport. The dockControl functionality is no longer supported. You can migrate to workspaceControl functionality by creating a script that generates the internal UI when executed, and attach it to a workspaceControl command call using the uiScript flag. You should no longer create a window with internal UI and then attach it to a dockControl command call via the content flag.

Create workspace controls using MEL

The following example shows the easiest way of creating workspace controls using MEL. Note that the example assumes this script exists in customWorkspaceControlFile.mel.

	global proc createCustomWorkspaceControlUI()
	{
	                columnLayout;
	                button;
	                button;
	                button;
	}

Execute this command to create the control for the first time:

workspaceControl -retain false -floating true 
-uiScript "if(!`exists createCustomWorkspaceControlUI`) source customWorkspaceControlFile; createCustomWorkspaceControlUI();" 
myCustomWorkspaceControl;

Create workspace controls using Python with Pyside bindings

You can create workspace controls in Python by using Maya command scripting. PySide only applies if the UI content of the workspace control is PySide-based.

Create a workspace control in PySide UI by doing the following:

Derive the top-level widget from the MayaQWidgetDockableMixin class.
Open the widget using a call to show() with dockable set to True.
Set uiScript to a script that recreates the widget. The script needs to parent the recreated widget into the restored workspace control (locate using MQtUtil.findControl) using MQtUtil.addWidgetToMayaLayout.

For more information about creating a workspace control using Python see the dockableWorkspaceWidget.py devkit example. To run the example, open it in the Script Editor and execute it. See also PyQt and PySide Widget Best Practices.

Create workspace controls using C++

When using C++, you must first create the workspace control using the workspaceControl MEL command. It can be executed using the MGlobal::executeCommand() method. You can then parent your C++-created Qt UI into the workspace control using the MQtUtil::addWidgetToMayaLayout() method.

The workspaceControlCmd.cpp example demonstrates how to create a command that generates the workspace control and the containing UI. It also shows how to pass it into the workspaceControl's uiScript flag to restore the UI on reopen. Since the command is part of a plug-in, the workspace control must be made aware of that plug-in using the requiredPlugin flag so that it can execute the command to restore the UI.

To build the workspaceControlCmd example, see the Building the plug-in section of the Using Qt in Plug-ins topic. After the plug-in is built, load it into Maya and execute the following MEL script:

workspaceControlWindow; .