dockControl part 2: adv. usage

Today, I ‘m going to expand on the blog post that Owen wrote about the new dockControl command in Maya 2011 and look at some more advanced examples of its usage.

Mainly delete the UI when it becomes hidden, a look at the different methods, adding multiple windows and adding them to layouts.  

Delete the docked window when it is invisible

The first problem that will be obvious to users, is that once we create a docked generic window with the dockControl, you lose the ability to bring up that window even after the docked one is closed.

Example:  
You can easily create a docked window with the dockControl. For example, this brings up the script editor docked on the left:

dockControl -area left -content scriptEditorPanel1Window owensScriptEditorDC;

The problem with this approach is that if I close the docked script editor, I won't be able to open the script editor with the main menu (I'll get // Error: line 1: No window found. /).  

Using that little cross to close the window doesn’t actually delete the UI, it hides the window.  And as we all know, Maya doesn't like multiple Outliner or Script editors… so it’s important to delete the UI so you can open the UI again later.

To do that, you use the –vcc (visibleChangeCommand)  and the –io (isObscured) flag to query when the window is obscured and then delete it with the deleteUI command:

$customOutliner = `dockControl -area "left" -content scriptEditorPanel1Window -vcc "if (`dockControl -q -io $customOutliner`) {evalDeferred \"deleteUI $customOutliner\";}"`;

Here the syntax is fairly similar except I am giving a name to the control, so I can delete easily afterwards.  Secondly and most importantly,  I am testing with a query when the window becomes obscured and once it is, delete it with the –vcc and the –io flag.  

Doing it this way is more scripting but it will make the Outliner useable in and out the dockControl.

Two ways to use the dockControl

You might all ready know there are two methods to using the dockControl.  The simple way is to create a window in the usual way, and then use dockControl instead of showWindow. .  

Here is an example of the first method:

$mywindow = `window -widthHeight 200 150 -backgroundColor 1.0 1.0 1.0 -t ""`;
$tabLayout_1 = `tabLayout -innerMarginWidth 5 -innerMarginHeight 5 -backgroundColor 1.0 1.0 1.0`;
string $panel = `outlinerPanel`;
string $outliner = `outlinerPanel -q -outlinerEditor $panel`;
dockControl -area left -content $mywindow ;

Here I have simply changed the showWindow command for the dockControl , and added the appropriate flag.

Second method:

The second way is to create the docked window first, and then parent a window underneath it.  This also means I have to create a tabLayout that is parented to the Maya Main window previously.

global string $gMainWindow;
$tabLayout_1 = `tabLayout -parent $gMainWindow `;
$dockedWindow = `dockControl -l "Custom Window" -allowedArea "all" -area "left" -content $tabLayout_1`;
OutlinerWindow;
control -e -p $tabLayout_1 outlinerPanel1Window;

Here, I create my docked window first, and “parent” a window underneath it.  This also means I have to create a tabLayout that is parented to the Maya Main window previously.

Clearly these two different approaches will give different results, although the first method is an easier concept, since it only involves changing the last line of the script, the second method is much more powerful.  I am actually editing the outliner window (with the –e flag) so the UI will persists when I do a File -> New Scene instead of giving me an ugly white empty area.

Creating multiple tabs with Maya windows

Using the second method, it becomes quite easy to add multiple Maya windows.

In this example, I create a tabLayout and add multiple windows to it.  I create a window with an Outliner and a Hypergraph, and I use the –label flag to name the window “Custom Window”.

global string $gMainWindow;
$tabLayout_1 = `tabLayout -parent $gMainWindow `;
$dockedWindow = `dockControl -label "Custom Window" -allowedArea "all" -area "left" -content $tabLayout_1`;
OutlinerWindow; control -e -p $tabLayout_1 outlinerPanel1Window;
HypergraphHierarchyWindow; control -e -p $tabLayout_1 hyperGraphPanel1Window;

Next saving this new UI in a layout to reuse it

Anyone that has played with the docked window will know that these are not “visible” in the layout editor.  Basically, Maya thinks of a layout as to what fits in the panel area, and since we are docking windows outside of it, this won’t work.

Off course, there is a way around this… with a neat little trick …

We know the layouts are saved in the userPrefs.mel.   For this example, create a layout with a specific name (here I called it SPECIAL) and then do a search in the userPrefs.mel to find the code associated with it.   You will get something like this:

panelConfiguration -label (localizedPanelLabel("SPECIAL"))
    -defaultImage ""
    -image ""
    -sc false
    -configString "global string $gMainPane; paneLayout -e -cn \"single\" -ps (.....)
    -ap true
        (localizedPanelLabel("Persp View"))
        "modelPanel" (....)

We can add a global procedure called by the configString to create our dock window.  So it will look like this :

panelConfiguration -label (localizedPanelLabel("SPECIAL"))
    -defaultImage ""
    -image ""
    -sc false
    -configString "CustomWindow; global string $gMainPane; paneLayout -e -cn \"single\" -ps (.....)
    -ap true
        (localizedPanelLabel("Persp View"))
        "modelPanel" (.....)


And off course, all we have to do now is to create the global proc and add it to the userPrefs.mel.  Simply add this at end of the scripts…

global proc CustomWindow ()
{    global string $gMainWindow;
$tabLayout_1 = `tabLayout -parent $gMainWindow `;
$dockedWindow = `dockControl -label "Custom Window" -allowedArea "all" -area "left" -content $tabLayout_1`;
OutlinerWindow; control -e -p $tabLayout_1 outlinerPanel1Window;
HypergraphHierarchyWindow; control -e -p $tabLayout_1 hyperGraphPanel1Window;
}

Comments

[Monkeys Human]

thanks so much for this tutorial, it was very helpful. Although I am still having problems with deleting the dock after I "x" it out.

So I am using this new command to be able to dock an existing UI we have created (it was created in 2008, we just upgraded to 2011 and it works fine, now I'm just trying to add this fancy new feature)

when I use the -vcc flag to close the window when I "x" it out it also deletes it when I un-dock the window (it actually crashes Maya). Is there a way of being able to delete the window when it is docked and un-docked?

also, I have tried putting in a check at the beginning of the opening of the UI which is like this:
if( `dockControl -q -io myDock` )
{
deleteUI -control myDock;
return;
}

When I run that check at the begining I get this error:
Object 'myDock' not found.

Any ideas on a way around this?

[Damon]

Hey, how can you resize a docked panel? I need to make it wider, but changing width via maya.cmds.window before or after docking doesnt seem to work....

[RH]

Outstanding! Thank you so much for taking the time to share. I use docks a surprising amount now since their introduction (finally!, the ability to design our personal workflow orientated interfaces).

This tutorial really is insightful, and better still- perfectly legible. Now I'm just itching to try tabbed window docks. (come on other machine .. finish rendering already!)