The intent of a GUI is to provide the user with a means of interacting with an application. A user’s actions are not predictable, and therefore the interface must be programmed to react appropriately to an undetermined number and order of sequential events. When a user clicks the mouse button or moves the pointer in an interface that has a lot of features and capabilities, many different callbacks can be triggered. In addition to user-induced events, there are also MATLAB commands that trigger events. Having knowledge about the order and the circumstances in which the callbacks are scheduled is very important when deciding on how to program a GUI.
Event Scheduling and Execution
The events that will be discussed in this section are the user-invoked events such as the mouse click, up and down, and mouse pointer motion. Since a single action such as a click could trigger several callbacks (the Window-ButtonDownFcn, WindowButtonUpFcn, CallBack, and Button-DownFcn of any graphics object that exists below the region that was clicked on), these events need to be scheduled. In addition to evaluating and processing the actual callback string, MATLAB also needs to update all the properties that store information about the action. All of the actions that MATLAB needs to perform are placed in what will be called an "event queue" so that they can be acted on in a logical and consistent order. Once the callback event queue has been formed, additional user actions that attempt to schedule a set of new callbacks are ignored unless the Interruptible property has been manipulated. For simplicity, right now we will assume that the callbacks are not interruptible.
During execution of an individual callback string, for efficiency, MATLAB stores all events that affect the appearance of any or all graphics on the screen, so that they can be executed at once. These events are stored in what will be called a "graphics event queue." The events in the graphics event queue are evaluated and are only updated under the following circumstances:
• all callbacks in the "callback queue" are finished executing and control is passed back to the command line
• a drawnow command is encountered
• a figure command is executed
• a getframe command is executed
• execution is temporarily halted because a pause waitforbuttonpress, or input command is issued.
In the event that a drawnow discard command is evaluated, the graphics event queue will be flushed (cleared) so that none of the graphics commands that were in the queue will be drawn on the screen. This does not mean that if one of the commands in the event queue is to set an existing graphics object’s property that changes that object’s appearance, the set command is not issued. Rather, the appearance will just not be displayed on the screen until a command that forces the figure to be redrawn is issued, such as refresh or another plotting command.
Execution Order of Events
The order in which graphics object information is updated and callbacks are evaluated can be seen in the flow charts found in the next several sections. The best way to learn is to write a little script and experiment with the different possibilities by clicking and dragging in different parts of the two figures. The following code is provided to you just for that.
Mouse Button Pressed Down
When the user presses the mouse button down within the area defined by a figure’s boundaries, MATLAB processes the following sequence of actions.
As is noted in the diagram, in the event that the user clicks the mouse down over an uicontrol button, the appearance of the uicontrol may change; however, the CallBack is not evaluated until the mouse button is released over that uicontrol. This gives the user the opportunity to back out of an accidental choice by moving the mouse away from the uicontrol and releasing the button over another region of the figure.
Mouse Button Released
When the user releases the mouse button within the area defined by a figure’s boundaries, MATLAB processes the following sequence of actions:
The WindowButtonMotionFcn can be executed at the time a mouse button is released under the circumstance indicated by the flow diagram. It occurs only if the WindowButtonMotionFcn is defined. If the user clicks down in one figure and then moves over to another figure before releasing the mouse button, the WindowButtonUpFcn property of the figure in which the mouse was clicked down will be evaluated. The other figure that the pointer was moved into will not have its WindowButtonUpFcn evaluated, but its WindowButtonMotionFcn will be evaluated. In other words, in order for the WindowButtonUpFcn to be evaluated, the mouse button has to be pressed down in that figure.
Mouse Pointer Moved
When the user moves the mouse pointer within the area defined by a figure’s boundaries, MATLAB processes the sequence of actions shown in the following figure. This is true only if the WindowButtonMotionFcn is defined for that figure. If it is not defined, MATLAB does not waste time updating the figure’s CurrentPoint and the root’s PointerLocation and PointerWindow properties until they are requested.
If the mouse button is pressed and held down while the pointer is moved into a figure whose WindowButtonMotionFcn properties are also defined, only the WindowButtonMotionFcn of the figure that the mouse was pressed down in will be evaluated. If the mouse is not held down and the user moves the mouse into a different figure, normal operation will ensue. In other words, MATLAB will evaluate the WindowButtonMotionFcn for the figure in which the pointer is located.
Each slight movement of the mouse is an action event that can schedule a WindowButtonMotionFcn callback. Since the number of these events that are processed in a given amount of time depends on your machine’s speed and the rate at which the mouse pointer is being moved across the screen, MATLAB evaluates only the most recent WindowButtonMotionFcn callback; the rest are discarded, otherwise a machine could become seriously bogged down in evaluating callbacks.
Interruptible vs. Uninterruptible
One of the properties found in every single graphics object is the Interruptible property. By default, this property is set to "on", which means that if an object’s callback is being evaluated (no matter where it is defined: CallBack, ButtonDownFcn, WindowButtonDownFcn, etc.), it can be interrupted by any other object’s callback. It is useful to set this property to "off" when you want to ignore all user-invoked actions (mouse clicks or pointer movement) that may occur while a MATLAB program is being executed.
There are many situations in which you want the user to be able to interrupt a callback. For example, if you would like to program the CallBack of an uicontrol, let’s say button A, to bring up another GUI that the user must respond to before button A’s CallBack can be completed, you will want to keep A’s Interruptible property set to "on".
In the example GUI provided in Section 10.7.4, we saw that while an animation was running, the user could manipulate the uicontrols and see an immediate effect on the animation. This was because the push button that started the simulation (i.e., the one labeled "Rotate") has its Interruptible property set to "on".
In order to interrupt an object’s callback, there are two requirements
1. The object’s Interruptible property must be set to "on" (the default).
2. The callback must contain a drawnow, getframe, figure, input, pause, or waitforbuttonpress (actually, any of the wait for… ) command.
There are situations where it does not matter what you have set the Interruptible property to and the executing callback will be interrupted any way; these are:
1. when the interrupting callback is a DeleteFcn or CreateFcn callback or
2. when a figure is executing a CloseRequest or ResizeFcn callback
Common Mouse Action Examples
There are a couple of examples that we can offer to teach and reinforce some of the ideas learned in this section. First, we will demonstrate a capability that allows the user to use the mouse button to move and resize objects, such as text and axes objects, so that the changes do not need to be made at the command line before printing out a hard copy of a figure. The second is being able to create a dynamic box when the user clicks and drags the mouse. Both of these examples were presented in a similar fashion in the earlier editions of this topic, and although modern MATLAB provides some functions, e.g., selectmoveresize and dragrect, and the figure property WindowStyle, we still feel that these examples are educational and will help in understanding the event queue and the nature of mouse-related operations.
