MatLab Training Course Notes
Session 6

Creating Graphical User Interface (GUI) driven programs

Instructor:
Bill Miller
Dynamic Neuroimaging Laboratory
415.502.3726
http://dnl.ucsf.edu

Topics for Session 6

Concepts: Interface, Responding to graphics events
Structure of a GUI-program: a reliable approach
GUIfft: An illustrative example
Live response to mouse motion: two examples

1. Concepts: Interface, Responding to graphics events

MatLab GUI consists of figure window containing graphics objects, some or all of which respond to mouse events. The responsive graphics objects can be any of the objects used for plotting, including:
- axes, line, plot, image, and figure itself; and
- controls such as buttons, menus, listboxes, textboxes, using uicontrol, and uimenu objects.
As we learned in Session 3 on handle graphics, each type of graphic object has a specific set of associated properties whos values determine how the object is displayed and behaves.
Note: It can be hard to remember all of the properties and their potential values, so it is convenient to refer to the html-based helpdesk information (or the manuals), for each of the objects listed above.
Several particular object properties are used repeatedly in MatLab GUI programs:
- "units" and "position" properties for specifying where an object is placed
- "menubar", "numbertitle" properties for figures, together with uimenu for customizing the figure's title and menu.
- "userdata" property (any object) for storing internally useful information like object handles
- "tag" and "type" properties, together with the findobj function, for identifying graphic objects during run-time.
- "callback","ButtonDownFcn" (all non-figure objects) and "WindowButton[Down/Motion/Up]Fcn" for creating callback responses to graphics (mouse and return) events.
Modal interfaces ("dialog boxes") are those in which the figure window's "modal" property has been set to "on". When a modal interface is created. Execution is halted (outside that controlled by the interface) can take place until the figure window is closed. Compare the following two commands (close the windows by clicking on the top right close boxes):
```
    figure   %creates normal figure window - can still type on command line
    dialog   %creates a modal figure - can't type on command line
```
MatLab provides built-in file selection dialog box functions uigetfile and uisetfile for convenient file selection by the user. The first of these is employed in the example below.
There are two typical styles of GUI programming: Active event polling and using callbacks
- In active event-polling, the program arrives at an "infinite loop" which "listens" for mouse events and branches according to event-type. Typically used built-in functions are waitfor, uiwait and uiresume. The disadvantages of this approach is that the program is always executing, and the single loop has to deal with every possible event you've coded.
- Using callbacks is a more elegant solution. A MatLab executable command string is associated with each graphics object that should respond to a mouse event. The program only runs when it is either initially called from the command line (to create the interface), or when responding to callbacks for graphics events. This is the approach we'll use here.
  For example, the following code creates a pushbutton on a figure with the name "Click Me" and the Callback string "disp hello". Clicking the button causes the string to be executed by MatLab just as if the command had been typed at the command line. (To try it, copy this code, paste it at the MatLab prompt, and press return).
```
   uicontrol('style','pushbutton','string','Click Me','callback','disp hello')
```
  In another example, the closereq can be used in a callback to close the figure window:
```
   uicontrol('style','pushbutton','string','Quit','callback','closereq')
```
  Note that this technique of executing strings as MatLab commands is also commonly done in non-GUI programs using the eval command. We haven't encountered eval in previous sessions, so see its help information to learn more.

2. Structure of a GUI-program: a reliable approach

Overall design approach:

Use the main (first) function in the m-file as an "action"-driven callback processor for graphic events.
Create separate subfunctions for each desired action or functionality:
- function which creates the GUI figure window
- function(s) which deal with each type of interface response
- functions which perform calculations, do plotting, etc.
For each object on the user interface that should respond to a mouse or keyboard event (i.e., click, return, etc.), when the object is created, its "callback" property is assigned a string value which typically will be the name of the m-file's main function followed by the appropriate action. Thus, the object will call back into the m-file with the input argument "action".

This method of creating GUI programs has several advantages:

Compactness: There is only one m-file, which gets called initially from the command line to create the interface and thereafter by the mouse-event callbacks of the graphics objects on the GUI.
Readability: it is relatively easy to read and add functionality to the program, since different functionalities are separated into different sub-functions.
CPU-economy: no continuous polling for events; the m-file is only executed when a callback event occurs, and exits when the appropriate response is completed.

3. GUIfft: An illustrative example

The following example, GUIfft.m illustrates the above style of making a GUI program. GUIfft has 3 functionalities:

Open and load and display a signal from a text file. (only the last column of multi-column data is used).
Compute the FFT (fast Fourier transform) of the signal and display it on the axis (replacing the original raw data).
Display a horizontal threshold line over the raw data or FFT at a level specified by the user.

GUIfft's interface consists of a figure window containing:

a custom menubar with a "File" menu, containing an "Open..." menu item
an empty axis object
a pushbutton named "Do FFT" which, when clicked, causes the FFT to be calculated and displayed.
a movable horizontal line which appears on the axis at the y-level of the mouse pointer any time the mouse (left button) is clicked inside the axis.

To implement the above functionality and user interface, GUIfft.m contains a top-level function (GUIfft) and four subfunctions:

Name	Called by	Purpose
`GUIfft(action)`	User (command line) or graphics callbacks	Decide which sub-function to call depending input argument
`CreateGUI`	GUIfft when action='create'	Creates GUI interface
`LoadFile`	GUIfft when action='loadfile'	Load and plot raw data
`doFFT`	GUIfft when action='dofft'	Compute and plot FFT of raw data
`Threshold`	GUIfft when action='threshold'	Create and place a threshold line on the axis

GUIfft.m includes extensive commenting to help you understand each line of each function.

4. Live response to mouse motion: two examples

In the above example program GUIfft, the "ButtonDownFcn" property of the axis used to generate a callback for creating a new threshold line when the mouse is clicked somewhere inside the axis. Holding the mouse button down while moving the mouse has no effect in this case. However, it is possible to obtain just such "live" movable behavior, by employing the following:

Figure callback properties "WindowButtonDownFcn", "WindowButtonMotionFcn" and "WindowButtonUpFcn"
"currentpoint" property for locating the last recorded mouse position

The following programs employ the above properties to create and manipulate movable lines on an axis (which can be used for thresholding or finding peaks, etc.):

testline.m creates a horizontal or vertical movable line on the specified axis (more than one can be created on the same axis!)
locklines.m can lock two lines (previously created with testline.m) together so that moving one also moves the other!

The live action technique involves dynamically resetting the callback strings of the above properties, and is a bit beyond explaining here. Take a look at the help information provided with these functions, and the code itself to see how the behavior is acheived.