Mel

Querying UI Widgets

Introduction

This tutorial presents code that demonstrates how the state or value of user interface (UI) widgets can be queried. These notes assume the reader is using Cutter and that their Mel scripts will be executed via a port. If the reader is not familiar with Cutter's facilities they should review the following tutorials.
Cutter: Integration with Maya"
Mel: Getting Started with Cutter
Alternatively, the reader can use any text editor to prepare their scripts. For example, the first script might be saved from Cutter as,

    M:/mel/sliderUI.mel

The script could then be run by entering the following command in Maya's script editor window.

    source "M:/mel/sliderUI.mel";

Of course Mel scripts can also be pasted directly into the script editor and executed by pressing the "enter" key on the numeric keypad.

Creating a Window & Adding UI Widgets

The code to create a window and add two UI widgets is shown in listing 1. The -retain flag is used with the window command to ensure the window is not deleted when the user clicks its "close" box but, instead, is merely hidden. A reference to the window is stored in the global variable $sliderWin. It's value is tested within the main proc to ensure the window and its UI widgets are only created once.

Listing 1 (sliderUI.mel)

global string $sliderWin;
global string $slider1;
  
//--------------------------------------------------
// Echoes the value of a slider in the script window
//--------------------------------------------------
global proc getSliderValue() {
    global string $slider1;
      
    float $v = `floatSliderGrp -q -v $slider1`;
    print("The current value of the slider is " + $v + "\n");
    }
  
//--------------------------------------------------
// Adds a slider and a button to the window
//--------------------------------------------------
global proc addUIWidgets() {
    global string $slider1;
    
    columnLayout;
    $slider1 = `floatSliderGrp -columnWidth 1 50
                        -label "test"
                        -field true
                        -value 13
                        -min 1 -max 20`;
    
    button  -label "Get Slider Value" -command "getSliderValue";
    }
  
//--------------------------------------------------
// Main proc
//--------------------------------------------------
global proc sliderUI() {
    global string $sliderWin; 
    
    int $doesExist = `window -exists $sliderWin`;
    if($doesExist == 0) {
        $sliderWin = `window -w 400 -h 200
                            -retain
                            -topLeftCorner 500 1000
                            -title "UI Test"`;
        addUIWidgets();
        }
    showWindow $sliderWin;
    }
  
sliderUI();

Copy and paste the code into a new document in Cutter. Save it as sliderUI.mel. It may be necessary to wait a moment while Cutter reads its database of Mel commands. A progress bar will indicate when the commnands have been read.

Querying a Slider

The code in listing 2 implements a proc that is called when the user clicks the "Get Slider Value" button.

Listing 2

// Echoes the value of a slider in the script window
global proc getSliderValue() {
    global string $slider1;
  
    float $v = `floatSliderGrp -q -v $slider1`;
    print("The current value of the slider is " + $v + "\n");
    }

Use the keyboard shortcut Alt + e, Control + e or Apple + e to execute the Mel script. Maya will open a simple window containing a float value slider. The results of querying the slider ie.

    float $v = `floatSliderGrp -q -v $slider1`;

is echoed in the history pane of the script window. Note the use of the variable $slider1. It has been declared global so that both procs can access its data ie. the name of the slider. Strickly speaking, the variable need not be global, however, declaring it as such enables the proc getSliderValue() to be implemented by a separate Mel script.

Figure 1

Querying a Checkbox from a callback

Listing 3 shows how a callback procedure is registered with a checkbox. When the checkbox is clicked, a callback named updateHappened() is invoked. The procedure queries the state of the checkbox in much the same way as getSliderValue() in listing 2.

Using a callback procedure in this way enables the checkbox to "broadcast" a change has occured to its "state". However, it still remains the job of the callback to query the value of the checkbox ie. 1 is "on", 0 is "off".

Listing 3 (checkBoxUI.mel)

global string $checkboxWin;
global string $checkbox1;
  
//--------------------------------------------------
// This proc is called when the state of the checkbox
// is changed
//--------------------------------------------------
global proc updateHappened() {
    global string $checkbox1;
      
    int $v = `checkBox -q -v $checkbox1`;
    print("The current state of the checkbox is " + $v + "\n");
    }
  
//--------------------------------------------------
// Adds a slider and a button to the window
//--------------------------------------------------
global proc addUIWidgets() {
    global string $checkbox1;
    
    columnLayout;
    // Note the use the -changeCommand flag to register a 
    // callback proc
    $checkbox1 = `checkBox -changeCommand "updateHappened()" 
                            -value 1 -label "state"`;
    }
  
//--------------------------------------------------
// Main proc
//--------------------------------------------------
global proc checkBoxUI() {
    global string $checkboxWin; 
    global string $slider1;
    
    int $doesExist = `window -exists $checkboxWin`;
    if($doesExist == 0) {
        $checkboxWin = `window -w 400 -h 200
                            -retain
                            -topLeftCorner 500 1000
                            -title "UI Test"`;
        addUIWidgets();
        }
    showWindow $checkboxWin;
    }
  
checkBoxUI();

Sliders and callbacks

Listing 4 shows how two callback procedures can be registered with a slider. One callback, updateHappened(), is invoked only when the user releases the mouse button after dragging the slider. The other callback, dragHappened(), is invoked while the user is dragging the slider. In most situations, only one callback is necessary.

Listing 4 (sliderCallBackUI.mel)

global string $sliderCallBackWin;
global string $slider1;
  
//--------------------------------------------------
// Called AFTER the user has moved the slider
//--------------------------------------------------
global proc updateHappened() {
    global string $slider1;
    
    float $v = `floatSliderGrp -q -v $slider1`;
    print("The released value of the slider is " + $v + "\n");
    }
  
//--------------------------------------------------
// Called WHILE the user is moving the slider
//--------------------------------------------------
global proc dragHappened() {
    global string $slider1;
    
    float $v = `floatSliderGrp -q -v $slider1`;
    print("The dragged value of the slider is " + $v + "\n");
    }
  
//--------------------------------------------------
// Adds a slider and a button to the window
//--------------------------------------------------
global proc addUIWidgets() {
    global string $slider1;
    
    columnLayout;
    $slider1 = `floatSliderGrp -columnWidth 1 50
                        -label "test"
                        -field true
                        -value 13 -min 1 -max 20
                        -changeCommand "updateHappened()"
                        -dragCommand "dragHappened()"`;
    }
  
//--------------------------------------------------
// Main proc
//--------------------------------------------------
global proc sliderCallBackUI() {
    global string $sliderCallBackWin; 
    
    int $doesExist = `window -exists $sliderCallBackWin`;
    if($doesExist == 0) {
        $sliderCallBackWin = `window -w 400 -h 200
                                    -retain
                                    -topLeftCorner 500 1000
                                    -title "UI Test"`;
        addUIWidgets();
        }
    showWindow $sliderCallBackWin;
    }
  
sliderCallBackUI();

Text Fields and callbacks

Listing 5 shows how a callback procedure can be registered with a textFieldGrp. The callback is invoked after the user has changed the text of the textFieldGrp and has subsequently pressed the enter key.

Listing 5 (textFieldUI.mel)

global string $textFieldWin;
global string $textfield1;
  
//--------------------------------------------------
// This proc is called when the textfield changes state
//--------------------------------------------------
global proc updateHappened() {
    global string $textfield1;
      
    string $v = `textFieldGrp -q -text $textfield1`;
    print("The current text of the textfield is \"" + $v + "\"\n");
    }
  
  
//--------------------------------------------------
// Adds a slider and a button to the window
//--------------------------------------------------
global proc addUIWidgets() {
    global string $textfield1;
    
    columnLayout;
    $textfield1 = `textFieldGrp -changeCommand "updateHappened()"
                                -columnWidth 1 50
                                -columnWidth 2 150
                                -text "hello" -label "Info"`;
    }
  
//--------------------------------------------------
// Main proc
//--------------------------------------------------
global proc textFieldUI() {
    global string $textFieldWin; 
    
    int $doesExist = `window -exists $textFieldWin`;
    if($doesExist == 0) {
        $textFieldWin = `window -w 400 -h 200
                                    -retain
                                    -topLeftCorner 500 1000
                                    -title "UI Test"`;
        addUIWidgets();
        }
    showWindow $textFieldWin;
    }
  
textFieldUI();