Making a basic window

All great user interfaces start with window. In this example, we'll be creating a simple window and using the text label control to add a simple message.

We'll end up with something like the following:

How to do it...

Start by creating a new file in your scripts directory and naming it basic Window.py.

Add the following code:

import maya.cmds as cmds

def showUI():
    myWin = cmds.window(title="Simple Window", widthHeight=(300, 200))
    cmds.columnLayout()
    cmds.text(label="Hello, Maya!")

    cmds.showWindow(myWin)

showUI()

If you run the script, you should see a small window containing the text Hello, Maya!.

How it works...

To create a window, you'll need to use the window command.

myWin = cmds.window(title="Simple Window", widthHeight=(300, 200))

While all of the arguments are optional, there are a few that you'll generally want to include by default. Here, we're setting the title to "Simple Window" and the size of the window to 300 pixels wide by 200 pixels tall. Also note that we save the result of the command to a variable, myWin. This is necessary in order to use the showWindow command. More on that in a bit.

There is also one more requirement, that is, in order to add an element to a window, you must first specify a layout. Layouts are responsible for arranging items within a given area (either a window or another layout). If you fail to provide Maya with a layout, it won't be able to properly position any controls you add, and your script will error out. In this example, we're using a columnLayout, which will arrange all the controls we add in a single vertical column. We add a layout to the window with the following:

cmds.columnLayout()

Once we've created a window and specified a layout, we can start adding controls. In this case, we're using the text control that merely adds some text to the window. While you won't generally use text controls by themselves (it's far more common to use them next to other controls to provide labels or descriptive text), it serves as a good example of a typical, albeit simple, control.

cmds.text(label="Hello, Maya!")

At this point, we're done with our interface, but creating a window will not actually show anything in Maya. To have it shown up in Maya's interface, we'll also need to explicitly show it using the showWindow command. The reason for this is that you generally don't want to show a window until it has all of the controls and other UI elements you want it to have. However, in order to create a control, you must first have a window to add them to. Maya solves this by having you:

1. Create the window.
2. Add your controls.
3. Show the window once all of the controls have been added.

This is why, it was important to save the result of the window() command to a variable, so that we can tell Maya which window it should show to the user. Putting that together gives us the last line of our showUI function:

cmds.showWindow(myWin)

There's more...

Note that once a layout is created, it becomes the active context in order to add controls. You can certainly have multiple layouts in a single window (and even nest them within each other), but there is always exactly one current layout to which Maya will insert newly created controls.

One problem with this example is that running the script multiple times will result in multiple copies of the window, which is usually not what you want. For most purposes, you'll want to ensure that there is only ever a single instance of your UI open at any one time.

To do this, we'll need to:

• Choose a unique name for our window
• Before creating the window, check to see whether one already exists with that name
• If there's already a window by that name, delete it
• Create the window using the window command, passing in the name

When choosing a name, make sure that it's something that is unlikely to conflict with other scripts the user might be using. Generic names such as "MyWindow" or "MainWindow" are likely to cause conflicts; it is much better to have something unique like "CharacterRigControl". To make it even better, add your initials, or the initials of your company to the start of the name ("ahCharacterRig", for example). Note that the name (which is not shown to the user) is distinct from the title (which is), so it's perfectly fine to have a long or unwieldy name. Just make sure that it's unique.

Once you have a name, we'll want to start off by testing to see if a window by that name exists. We can do that with the window command and the exists flag. If we do find that a window of that name exists, we'll want to get rid of it with the deleteUI command:

    if (cmds.window("ahExampleWindow", exists=True)):
        cmds.deleteUI("ahExampleWindow")

Finally, when we create a new window, we'll make sure to pass in our desired name as the first argument, which will give the window the desired name.

myWin = cmds.window("ahExampleWindow", title="Simple Window", widthHeight=(300, 200))

Alternatively, we could just stop the script if there's already a window with the given name, but the previously mentioned approach is more common. If the user invokes your script, they likely want to start with a fresh slate, so replacing the old window is often the best option.