1. E177, Graphics Objects in Matlab February 26, 2008 http://jagger. me
E177, Graphics Objects in Matlab February 26, Copyright , Andy Packard. This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license, visit or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

2. Schedule Week 6: (Feb 26, 28) Intro to GUI programming
Week 7: (March 4, 6) Callback examples, event queue processing, project discussion
Week 8: (March 11, 13) HandleGraphicsToolkit class building, project discussion (40 minutes)
Week 9: (March 18, 20) examples intro to C
Spring Break (March 25, 27)
Week 10: (April 1, 3) C language
Week 11: (April 8, 10) C-mex interface to Matlab, Midterm
Week 12: (April 15, 17) C-mex interface to Matlab, ?
Week 13: (April 22, 24) ?, ?
Week 14: (April 29, May 1) ?, ?
Week 15: (May 6, 8) ?, ?
FINAL: Tuesday May 20, 5-8PM ???

3. Graphics Objects in Matlab
Some of the different types of graphics objects in Matlab are
Matlab session, the Root object
Handle equals 0
child of root
figure …
axes
uicontrol
uimenu
uicontextmenu
children of figure …
line
patch
surface
text
children of axes

4. Globally accessible, hidden data
“Within each” graphics object, you can store hidden, globally accessible data
Use the command setappdata.
This is called application data.
Example:
H = plot(1:10,sin(1:10));
A = rand(40,40); A(3,2)
setappdata(H,’BigArray’,A);
clear A
whos % data is not in workspace
Retrieve the data using getappdata.
tmp = getappdata(H,’BigArray’);
tmp(3,2)
Data is “globally accessible” in that only the handle of the graphics object is needed to access its application data.

5. Callback Intro: Button-press events for line objects
If the mouse is pressed while the pointer is over the line
a ButtonDownFcn event occurs, so…
if a ButtonDownFcn callback has been set, it is executed
The callback may be set in two manners
using a char
using a cell
In the case of a char, the string is evaluated in the base workspace
cbstr = [’disp(’’Mouse pressed on line’’);’];
set(H,’ButtonDownFcn’,cbstr);
Now, if the mouse is pressed over the line, the command eval(cbstr) will be executed “in the base workspace”, ie., as though you typed
>> eval(cbstr) % i.e., like typing
>> disp(’Mouse pressed on line’);
unless other callbacks are still executing. There is an event queue where unprocessed events are handled/scheduled in a defined fashion. E177...

6. Callback Intro: Button-press events for line objects
Change it to keep track of the number of presses
cbstr = [’np = np+1;’];
set(H,’ButtonDownFcn’,cbstr);
>> np = 0;
Now, if the mouse is pressed over the line, the command eval(cbstr) will be executed in the base workspace, i.e., as though you typed
>> eval(cbstr) % same as >> np = np + 1;
Do it a few times, and it works.
Easy to understand, but often not flexible enough… More generally, cell arrays will be used to specify callbacks.
Any workspace, with H
In base workspace

7. Summary: All graphical objects in Matlab
are referred to by a handle (also called pointer or address)
have a get/set interface by which their properties are accessed and modified
are created by constructor methods, but are not variables
not being variables, they are not in any workspace
being created with constructors, they are created from a specific workspace, but exist independent of workspace
Remember, constructor returns handle to graphics object
can store hidden, globally accessible data, called application data (in the form of Matlab variables) within them that exists as long as the object itself exists. By “within them” we mean
Variables are not in any workspace
Variables exist as long as the graphic object exists
Variables are accessed/deleted/etc via the graphic object’s handle
Have events associated with them
Example: a pushbutton object has a ButtonPress event; a Figure object has a MouseMotion event, etc.
Programs, called “callbacks” can be associated with events so that when the event occurs, the callback program is executed

8. Graphical objects .vs. Variables
Contrast the attributes of the graphical objects with the attributes of Matlab variables (like double, cell, char, struct and objects of user-defined classes)
Graphics Objects:
Are referred to by an address, called the “handle”
Have a get/set interface to access/modify
Are not associated with a workspace
Can hide data
Can generate events
Matlab variables:
Are referred to by name
Are referenced directly to access/modify (primitives)
Have a get/set interface to access/modify (objects)
Live in a workspace
Cease to exist when the workspace they live in is deleted.
Since we write set/get, we could create this behavior too.

9. Writing reusable graphical based applications
In order to write a reusable, graphical based application using Matlab HandleGraphics, the “application” should mimic the attributes of the basic Matlab HandleGraphics objects
referred to by a handle
get/set interface by which its properties (“state”) are accessed
store hidden, globally accessible data
have events associated with changes in its state
To accomplish this, it is best to integrate the graphics objects with the user defined classes. We will do this, over the next two weeks.
Today, we give a partial overview of the strategy, minus the object oriented (user defined classes) wrapper.
We need one more Matlab concept before starting
Cell array callbacks (as opposed to char callbacks)

10. Cell array callbacks Create (for example) a pushbutton
PB = uicontrol(’style’,’pushb’);
and a function, ARG5.m
and a 1x4 cell array
cb = ’e7’ [100;10;1]};
Set the callback of the pushbutton to be the cell array.
set(PB,’Callback’,cb);
What happens when the button is pressed?
function ARG5(A1,A2,A3,A4,A5)
... % some code here

11. Cell array callbacks Setup is PB = uicontrol(’style’,’pushb’);
cb = ’e177’ [100;10;1]};
set(PB,’Callback’,cb);
Upon buttonpress, Matlab creates 2 objects, EventSrc and EventData, and executes the desired funtion, without outputs
tmp = get(gcbo,’Callback’);
tmp{1}(EventSrc,EventData,tmp{2:end})
equivalently
ARG5(EventSrc,EventData,-14.1,’e177’,[100;10;1])
ARG5(A1, ,A ,A3 ,A4 ,A )
ARG5.m
function ARG5(A1,A2,A3,A4,A5)
...
gcbo, builtin function, returns handle of object that generated the callback (get callback object, gcbo)

12. Cell array callbacks Setup is PB = uicontrol(’style’,’pushb’);
cb = ’e7’ [100;10;1]};
set(PB,’Callback’,cb);
Upon buttonpress, Matlab creates 2 variables, EventSrc and EventData, & executes the callback function, w/out outputs
tmp = get(gcbo,’Callback’);
tmp{1}(EventSrc,EventData,tmp{2:end})
equivalently
ARG5(EventSrc,EventData,-14.1,’e7’,[100;10;1])
ARG5(A1, ,A ,A3 ,A4 ,A )
ARG5.m
function ARG5(A1,A2,A3,A4,A5)
...
gcbo, builtin function, returns handle of object that generated the callback (get callback object, gcbo)

13. PushButton/Counter ++ ++ 1 ++ 7
Let’s create an “object” consisting of a
counter (initialized at 0)
pushbutton (to increment counter)
text display of counter value
Initial appearance
After one buttonpress
After 7 buttonpresses
User (programmer employing this object in their program) should also be able to program additional actions to occur after a button press.
pushbutton
frame
text
uicontrol ++ ++ 1 ++ 7

14. Overview of Tool Code function ToolH = fname(arg)
% Create objects which constitute the tool
% These are the “subobjects”
% Choose one subobject as the “tool handle” (ToolH)
% Create ToolState variables which hold tool “state”
% Hide ToolState variables in appdata of ToolH
% Set subobject properties, event callbacks to subfcns
% Input arg: ToolH (then subfcns can access ToolState)
function subf1(Esrc,Edata,ToolH)
% Ignore Esrc, Edata
% Retrieve ToolState (from appdata of ToolH)
% Do calcs, set properties of subobjects
% Update and replace ToolState (appdata of ToolH)
function subf2(Esrc,Edata,ToolH)
function subf3(Esrc,Edata,ToolH)

15. PushButton/Counter State
Graphics “object” is the counter/display
What information do we need to keep track of everything?
value of counter
handle of text display
function_handle that user wants to additionally execute when the value is incremented
Hence, ToolState consists of 3 variables
CntVal, integer counter value
DispHan, the handle of the text display uicontrol
IncCB, function_handle (plus additional arguments) of user-defined increment callback ++ 1

16. function ToolHan = e117gui1(X,Y,IncCB)
FrameH = uicontrol('style','frame',...
'position',[X Y ]);
PlusH = uicontrol('style','pushbutton',...
'position',[X+5 Y ],'str','++');
DispH = uicontrol('style','text',...
'position',[X+50 Y ]);
ToolHan = DispH;
setappdata(ToolHan,'CntVal',0);
setappdata(ToolHan,'DispHan',DispH);
setappdata(ToolHan,'IncCB', IncCB);
ToolHan});
set(DispH,'str',int2str(0));
function LOCALinc(ESrc, EData, TH)
Cnt = getappdata(TH,'CntVal');
DispH = getappdata(TH,'DispHan');
IncCB = getappdata(TH,'IncCB');
Cnt = Cnt + 1;
set(DispH,'str',int2str(Cnt));
setappdata(TH,'CntVal',Cnt);
if ~isempty(IncCB)
IncCB{1}(ESrc,EData,TH,IncCB{2:end})
end
Create the objects that constitute the tool
Designate toolhandle
Hide state in ToolHan
Set callback events & subobject properties
Retrieve ToolState
Do calculations, set subobject properties
Update ToolState
Run user callback if it exists, passing supplied arguments

17. ++ function ToolHan = e117gui1(X,Y,IncCB)
Create the objects that constitute the tool
function ToolHan = e117gui1(X,Y,IncCB)
FrameH = uicontrol('style','frame',...
'position',[X Y ]);
PlusH = uicontrol('style','pushbutton',...
'position',[X+5 Y ],'str','++');
DispH = uicontrol('style','text',...
'position',[X+50 Y ]); ++

18. setappdata(ToolHan,'CntVal',0); setappdata(ToolHan,'DispHan',DispH);
function ToolHan = e117gui1(X,Y,IncCB)
FrameH = uicontrol('style','frame',...
'position',[X Y ]);
PlusH = uicontrol('style','pushbutton',...
'position',[X+5 Y ],'str','++');
DispH = uicontrol('style','text',...
'position',[X+50 Y ]);
Create the objects that constitute the tool
Designate toolhandle
ToolHan = DispH;
setappdata(ToolHan,'CntVal',0);
setappdata(ToolHan,'DispHan',DispH);
setappdata(ToolHan,'IncCB', IncCB);
Hide state in ToolHan

19. set(PlusH,'callback',{@LOCALinc ToolHan});
function ToolHan = e117gui1(X,Y,IncCB)
FrameH = uicontrol('style','frame',...
'position',[X Y ]);
PlusH = uicontrol('style','pushbutton',...
'position',[X+5 Y ],'str','++');
DispH = uicontrol('style','text',...
'position',[X+50 Y ]);
ToolHan = DispH;
setappdata(ToolHan,'CntVal',0);
setappdata(ToolHan,'DispHan',DispH);
setappdata(ToolHan,'IncCB', IncCB);
Create the objects that constitute the tool
Designate toolhandle
Hide state in ToolHan
Set callback event(s)
ToolHan});
set(DispH,'str',int2str(0));
function LOCALinc(ESrc, EData, TH)
...
Last line of function, so Exit, function complete. Function instance workspace is deleted, but all graphics objects (in their current “states”) continue to exist .
Set subobject properties
subfunction (same file)

20. function LOCALinc(ESrc, EData, TH) Cnt = getappdata(TH,'CntVal');
function ToolHan = e117gui1(X,Y,IncCB)
PlusH = uicontrol('style','pushbutton',...
DispH = uicontrol('style','text',...
ToolHan = DispH;
setappdata(ToolHan,'CntVal',0); ...
ToolHan});
function LOCALinc(ESrc, EData, TH)
Cnt = getappdata(TH,'CntVal');
DispH = getappdata(TH,'DispHan');
IncCB = getappdata(TH,'IncCB');
Cnt = Cnt + 1;
set(DispH,'str',int2str(Cnt));
setappdata(TH,'CntVal',Cnt);
Retrieve ToolState
Do calculations
set subobject properties
Update ToolState

21. IncCB{1}(ESrc,EData,TH,IncCB{2:end}) end
function ToolHan = e117gui1(X,Y,IncCB)
PlusH = uicontrol('style','pushbutton',...
DispH = uicontrol('style','text',...
ToolHan = DispH;
setappdata(ToolHan,'CntVal',0); ...
ToolHan});
function LOCALinc(ESrc, EData, TH)
Cnt = getappdata(TH,'CntVal');
DispH = getappdata(TH,'DispHan');
IncCB = getappdata(TH,'IncCB');
Cnt = Cnt + 1;
set(DispH,'str',int2str(Cnt));
setappdata(TH,'CntVal',Cnt);
Retrieve ToolState
Do calculations, set subobject properties
Update ToolState
Run user callback if it exists, passing supplied arguments
Extra supplied arguments
if ~isempty(IncCB)
IncCB{1}(ESrc,EData,TH,IncCB{2:end})
end
Our “convention”

22. PushButton Demo guidemoA.m replot.m % guidemoA script file
x = linspace(0,2*pi,200);
Line1 = plot(x,sin(0*x));
set(Line1,'LineWidth',3);
H1 = Line1});
function replot(Esrc,Edata,CntTool,LH)
XD = get(LH,'Xdata');
Cnt = getappdata(CntTool,'CntVal');
set(LH,'Ydata',sin(Cnt*XD));
Plot a simple graph, and store the line handle
Create the tool, set user-callback to replot, callback wiil pass line-handle as 4th argument
guidemoA.m
Get X data from line object (4th argument)
Get toolstate (CntVal) from toolhandle (3rd argument)
Using CntVal, set Ydata of line object.
replot.m

23. PushButton Demo 2 guidemoB.m wacky.m % guidemoB script file
x = linspace(0,2*pi,200);
Line1 = plot(x,sin(0*x));
set(Line1,'LineWidth',3);
H1 = Line1});
H2 = Line1});
function wacky(Esrc,Edata,CntTool,LH)
set(LH,'Color',rand(1,3));
Plot a simple graph, and obtain the line handle
Create two tools, set user-callbacks, callbacks wiil pass line-handle as 4th argument
guidemoB.m
Randomly change Color of line object every buttonpress
wacky.m