MEL - Interfaces

Introduction

The entire interface of Maya is built from MEL scripts. So it should be obvious that there are numerous possibilities within MEL to create interfaces. Creating an interface for your MEL script can be important, as it can increase the useability and application of your script considerably. Scripts are often (small) tools to aid in modeling, texturing, lighting, animating, etc. These tools have an user interface (UI) in most cases to increase their ease of use. They can also be embedded somewhere in the existing interface, by modifying the existing interface scripts.

Window

We start by creating a new window to show our interface

window -t "Window Title" MyWindow;

This command creates a standard window with title 'Window Title' and (internal) object name MyWindow. You'll probably notice immediately that no window shows up when executing this command. To display the created window, you need a separate command:

showWindow MyWindow;

If you execute the script to create a window again, you'll get an error, as the window already exists:

// Error: line #: Object's name is not unique:  MyWindow //

You can't create two windows with the same name. To solve this in a proper way, you could use:

if ( `window -exists MyWindow` ) {
    deleteUI MyWindow; // delete window when it exists
}
window -t "My custom interface" MyWindow;
 
showWindow MyWindow;

Layouts

All elements in your interface must be placed within a Layout. There are a number of layouts for the contents of windows. Some examples:

ColumnLayout
RowLayout
RowColumnLayout
ScrollLayout
FrameLayout
FormLayout

Furthermore there are various layouts for: pull-down menu's, shelves, tabs, etc.

Creating a interface is strictly hierarchical. All (interface related) commands following a Layout command will be regarded as related to this layout. A layout command must be preceded by a windows command, as it's only valid within a window.

The most common is the ColumnLayout, which places all elements in one single column. A first example:

if ( `window -exists MyWindow` ) {
    deleteUI MyWindow; // delete window when it exists
}
window -t "My own interface" MyWindow;
 
columnLayout MyMainCol;
button MyButton;
floatField MyFloatField;
 
showWindow MyWindow;

This example also shows a few Control elements: a button and a field to enter numerical values (floatfield).

You can find more information on layouts and combining layouts in MEL UI Layouts.

Controls

The Controls are the elements in your interface where the real work takes place: buttons, input fields, sliders and text areas. An overview of the most common controls:

Control	Description	Example
floatField	input field for decimal numbers
floatFieldGrp	input field for decimal numbers plus a text label
floatSlider	slider for decimal numbers
floatSliderGrp	slider for decimal numbers plus input field (optional) plus text label
intField, intFieldGrp, intSlider, intSliderGrp	same, but for integer numbers
colorSliderGrp	a slider to select a color
button	a button to execute a command
checkBox	checkbox to make 'on/off' selections
checkBoxGrp	same as checkbox, but now the label is put before the checkbox
radioButton	button to choose a single option from a set of options (uses radioCollection)
radioButtonGrp	a set of radio buttons on a single line
text	text labels
textField	input field for text
textFieldGrp	input field for text with a label
textScrollList	a list of selectable options
scrollField	a multi-line field for text. Editing can be disabled.
optionMenu	a pull-down menu to select from a set of options.

You can find a complete overview of the available controls in the MEL Command Reference.

Most controls have various options (flags). Some controls can show multiple input fields at once (e.g: to input X, Y and Z values), have a text label or allow widths to be set for a field or other element of the control. All these options are documented in the MEL Command Reference.

Reading Controls

The goals is to use values that a user enters into the interface. Each Control command has a flag to switch to query mode (-q), to allow you to read the current value(s) of the control.

floatField -q -v MyFloatField;

This value can be assigned to a variable:

$hoogte = `floatField -q -v MyFloatField`;

Some Controls, like the floatFieldGrp, can be set up to allow multiple values to be entered. When reading these controls, you need to specify which value you want to read, even if you configured it to allow only one value:

floatFieldGrp -q -v1 MyFloatField;

You can use the Command Reference for the exact specifications and options of each control.

This also shows the importance of naming your Interface elements. If you don't know the name of the control, it's impossible to read its value. There are two strategies regarding naming:

Reading a RadioButtonGrp

A radioButtonGrp can be used to provide a choice between (up to) 4 possibilities. Reading a radioButtonGrp to determine which option was selected, a slightly different approach is used:

radioButtonGrp -q -sl MyradioButtonGrp;

You query the control to see which option was selected. Maya returns a 1-based integer. This means that the result (an integer) will be 1 if the first option was selected, 2 for the second and so on.

A more extensive example is provided at the bottom of this page.

Reading a RadioCollection

A radioCollection is used to create a custom group of radioButtons of which only one can be selected at a time. Each radioButton can have integer data assigned to it. To read that data, two actions are needed:

Find out which of the radioButtons is currently selected within the radioCollection:
```
$button = `radioCollection -q -sl MyRadioCollection`;
```
Read the data that is attached to the specific radioButton:
```
$data = `radioButton -q -data $button`;
```

Using names for controls

Each control must have its own, unique name. This can be achieved by structuring your naming. Preferably you use your own 'unique' prefix. The prefix is to reduce the likeliness that you name conflicts with a name used in another script loaded in Maya. A commonly used method is to use your initials or an abbreviation of the company you work for.

// using tw_ as a prefix
intFieldGrp -l "Number" tw_Number;

Another approach is to store the name of a control in a variable upon creation of the control (of course the name for your variable may need to be unique...):

$number_of_objects = `intFieldGrp -l "Number"`;
// Result: MyWindow|MyMainCol|intFieldGrp1 //

Button actions

When you press a button in an interface, you expect something to happen. You're free to program any action for a button using the -command flag for the command to be executed when the button is pressed.

It's likely that you'd want a little more complex command to be executed than the -command flag allows you to specify (in a convenient way). Therefore it's recommended to use MEL procedures for each button action.

A typical snippet:

window -t "Button Test" MyWindow;
 
columnLayout MyMainCol;
intFieldGrp -l "Number" numberOfCubes;
button -l "Create" -command "createCubeButtonAction()";
 
showWindow MyWindow;
 
global proc createCubeButtonAction() {
  // read the control for the number of cubes to be created
  int $num = `intFieldGrp -q -v1 numberOfCubes`;
  for ($i=0;$i<$num;$i++ ) {
      polyCube;
      move (2*$i) 0 0;
  }
}

Control Commands

Most controls allow you to specify an action that should be taken when something happens within the control. For example: the contents of a field changes, a radio button is switched on or off, etc.

This is a very powerful option. You can act on changes seamlessly or change your interface upon selections that are being made. Using names for each control is crucial in this case. It's best to illustrate this with an example:

onCommand Example

if ( `window -exists MyWindow` ) {
  deleteUI MyWindow; // delete window when it exists
}
window -t "My own interface" MyWindow;
 
columnLayout MyMainCol;
 
//this command is split across multiple lines to improve readability
radioButtonGrp -cw3 80 50 50 -label "Mode" 
 -numberOfRadioButtons 2 
 -labelArray2 "1D" "2D" 
 -select 1 
 -onCommand1 "floatFieldGrp -edit -enable 0 MyZDistance" 
 -onCommand2 "floatFieldGrp -edit -enable 1 MyZDistance";
 
floatFieldGrp -l "Distance X" -cw2 80 100 MyXDistance;
floatFieldGrp -l "Distance Z" -enable 0 -cw2 80 100 MyZDistance;
button -l "Create" -c "";
 
showWindow MyWindow;

Examples

if ( `window -exists MyWindow` ) {
  deleteUI MyWindow; // delete window when it exists
}
window -t "My own interface" MyWindow;
 
columnLayout MyMainCol;
text -l "Create cubes";
intFieldGrp -l "Number" -cw2 80 100 MyNumber;
floatFieldGrp -l "Distance" -cw2 80 100 MyDistance;
button -l "Create" -c "MyMakeCubes()";
 
showWindow MyWindow;
 
global proc MyMakeCubes() {
  int $num = `intFieldGrp -q -v1 MyNumber`;
  float $dist = `floatFieldGrp -q -v1 MyDistance`;
  for ($i=0;$i<$num;$i++ ) {
    polyCube;
    move (($dist + 1)*$i) 0 0;
  }
}

RadioButtonGrp example:

if ( `window -exists MyWindow` ) {
  deleteUI MyWindow; // delete window when it exists
}
window -t "My own interface" MyWindow;
 
columnLayout MyMainCol;
text -l "Create cubes";
radioButtonGrp -l "Primary color" -numberOfRadioButtons 3 -select 2 -l1 "Red" -l2 "Green" -l3 "Blue" MyChoice;
button -l "Go" -c "MyPrintChoice()";
 
showWindow MyWindow;
 
global proc MyPrintChoice() {
  int $selected = `radioButtonGrp -q -select MyChoice`;
  if ( $selected == 1 ) {
    confirmDialog -title "Choice" -message "You've selected the first option";
  } else if ( $selected == 2 ) {
    confirmDialog -title "Choice" -message "You've selected the second option";
  } else if ( $selected == 3 ) {
    confirmDialog -title "Choice" -message "You've selected the third option";
  }
}

Related pages

MEL UI Layouts

Overview of Maya topics

Maya main index

MEL - Interfaces

Contents

Introduction

Window

Layouts

Controls

Reading Controls

Reading a RadioButtonGrp

Reading a RadioCollection

Using names for controls

Button actions

Control Commands

onCommand Example

Examples

Related pages

Personal tools

Views

Actions

Search

Navigation

Tools