Building User Interfaces¶

Function Name as String¶

The simplest method of setting up a callback is to pass the name of the callback function as a string. Maya will try to execute this as python code. Here’s a simple example:

from pymel.core import *

def buttonPressed():
    print "pressed!"

win = window(title="My Window")
layout = columnLayout()
btn = button( command='buttonPressed()' )

showWindow()

This example works fine if you run it from the script editor, but if you save it into a module, say myModule, and then import that module as normal ( e.g. import myModule ), it will cease to work (assuming you haven’t already run it from the script edtior). This is because the namespace of the buttonPressed function has changed. It can no longer be found as buttonPressed, because from Maya’s perspective, its new location is myModule.buttonPressed.

There are several solutions to this.

1. you can import the contents of myModule directly into the main namespace ( e.g. from myModule import * ). This will allow buttonPressed to be accessed without the namespace. This is not generally recommended as its clutters up your main namespace which could ultimately lead to name clashes.

2. you can change your script and prefix the function with the module it will be imported from:

   button( command="myModule.buttonPressed()" )
   

The problem with both of these solutions is that you must ensure that the module is always imported the same way, and, if you plan to share your module with someone, it’s pretty impossible to do this.

A more robust solution is to include an import command in the string to execute:

button( command="import myModule; myModule.buttonPressed()" )

That gives us a fairly reliable solution, but it still has one major drawback: any parameters that we wish to pass to our function must also be converted to strings. This becomes impractical when the parameters are complex objects, such as dictionaries, lists, or other custom objects.

So, while string callbacks may seem simple at first, they have limitations, and are generally not recommended.

Function Object¶

When using this technique, you pass an actual function object instead of a string.

from pymel.core import *

def buttonPressed():
    print "pressed!"

win = window(title="My Window")
layout = columnLayout()
btn = button(command=buttonPressed)

showWindow()

The difference from the previous example is subtle: command="buttonPressed()" is now command=buttonPressed. The most important thing to realize here is that buttonPressed is not a string, it is a python function object. As such, if we had included () ( e.g. command=buttonPressed() ) we would have executed the buttonPressed function immediately, but we don’t want that to happen yet. By leaving the parentheses off, we hand the function over to the UI element to execute later. For most commands that support callbacks, Maya recognizes when you are passing a string and when you are passing a function, and it treats each differently when the callback is triggered.

This method is very robust, but there are a few caveats to be aware of. To see what I mean, try executing the code above and pressing the button...

...when we press it, we get this error:

# TypeError: buttonPressed() takes no arguments (1 given) #

Why?! The button UI widget, like many others, automatically passes arguments to your function, whether you want them or not. Sometimes these arguments contain the state of the UI element, such as whether a checkbox is on or off, but in our case they are pretty useless.

radioButton -changeCommand "myRadButtCB #1";

So, to make our callback work, we need to modify the function to accept the argument that the button command callback is passing us:

def buttonPressed(arg):
    print "pressed!"

The tricky part is that different UI elements pass differing numbers of arguments to their callbacks, and some pass none at all. This is why it is best for your command to use the *args syntax, like so:

def buttonPressed(*args):
    print "pressed! here are my arguments %s" % ( args, )

The asterisk in front of args allows the function to accept any quantity of passed arguments. All of the positional arguments to the function are stored in the variable args (without the *) as a read-only list, known as a tuple. Making it a habit to use this syntax for your callbacks can save you a lot of headache.

Putting it all together:

from pymel.core import *

def buttonPressed(*args):
    print "pressed!"

win = window(title="My Window")
layout = columnLayout()
btn = button( command=buttonPressed )

showWindow()

Lambda Functions¶

The next technique builds on the last by simplifying the following situations:

• You want to pass arguments to your callback function other than those automatically sent by the UI element
• You’re using a function that someone else wrote and can’t add the *args to it

For example, I want to pass our buttonPressed function a name argument. Here’s how we do this using a lambda function:

from pymel.core import *

def buttonPressed(name):
    print "pressed %s!" % name

win = window(title="My Window")
layout = columnLayout()
btn = button( command = lambda *args: buttonPressed('chad') )

showWindow()

So, what exactly is a lambda? It’s a shorthand way of creating a simple function on one line. It’s usually used when you need a function but you don’t need to refer to it later by name, which makes it well suited for callbacks. Combining lambda functions with the lessons we learned above adds more versatility to command callbacks. You can choose exactly which args you want to pass along.

Let’s clarify what a lambda is. In the above example, this portion of the code...

lambda *args: buttonPressed('chad')

...could have been written as:

def tempFunc(*args):
    return buttonPressed('chad')

We would have then passed tempFunc as the callback:

btn = button( command = tempFunc )

Instead, we use the lambda to create the function on one line and pass it directly to the command flag.

btn = button( command = lambda *args: buttonPressed('chad') )

The lambda function serves as a mediator between the UI element and our real callback, buttonPressed, giving us control over what arguments will be passed to buttonPressed. In our example, we ignore all the arguments passed by the button and instead opt to pass the string 'chad', however, if the circumstances require it, you could use the arguments in args as well:

btn = button( command = lambda *args: buttonPressed('chad', args[0]) )

In the example above we’re using the first of the arguments passed by the button (remember, args is a tuple, which is like a list) and passing it on to our callback in addition to the name string. Keep in mind that for this to work our buttonPressed callback would need to be modified to accept two arguments.

Whew! That was a lot to learn, but unfortunately, this method has a drawback, too. It does not work properly when used in a ‘for’ loop.

In the following example, we’re going to make several buttons. Our intention is that each one will print a different name, but as you will soon see, we won’t succeed.

from pymel.core import *

def buttonPressed(name):
    print "pressed %s!" % name

win = window(title="My Window")
layout = columnLayout()
names = ['chad', 'robert', 'james']
for name in names:
    button( label=name, command = lambda *args: buttonPressed(name) )

showWindow()

When pressed, all the buttons will print ‘james’. Why is this? Think of a lambda as a “live” object. It lives there waiting to execute the code it has been given, but the variables in that code are live too, so the value of the variable named character changes with each iteration through the loop, thereby changing the code that lambda is waiting to execute. What is its value at the end of the loop? It’s ‘james’. So all the lambda’s execute the equivalent of:

buttonPressed('james')

To solve this we need to “pin” down the value of our variable to keep it from changing. To do this, pymel provides a Callback object...

Callback Objects¶

In my experience this method handles all cases reliably and predictably, and solves the ‘lambda’ issue described above. A Callback object is an object that behaves like a function, meaning it can be ‘called’ like a regular function. The Callback object ‘wraps’ another function, and also stores the parameters to pass to that function. And, lucky for you, the Callback class is included with pymel.

Here’s an example:

from pymel.core import *

def buttonPressed(name):
    print "pressed %s!" % name

win = window(title="My Window")
layout = columnLayout()
names = ['chad', 'robert', 'james']
for name in names:
    button( label=name, command = Callback( buttonPressed, name ) )

showWindow()

Our example now works as intended. The Callback class provides the magic that makes it work.

Pay close attention to how the Callback is created: the first argument, buttonPressed, is the function to wrap, and the rest are arguments to that function. The Callback stores the function and its arguments separately and then combines them when it is called by the UI element.

So, on assignment, something that looks like this...

Callback( buttonPressed, name )

...on execution becomes:

buttonPressed(name)

In this case, the variable name is the only additional argument, but the Callback class can accept any number of arguments or even keyword arguments, which it will dutifully pass along to your function when the callback is triggered.

The Callback class ignores any arguments passed in from the UI element, so you don’t have to design your function to take these into account. However, if you do want these, use the alternate callback object CallbackWithArgs which will pass the UI arguments after yours.