(Ebook) Engineering - Building Gui With Matlab

M
ATLAB

The Language of Technical Computing

Computation
Visualization
Programming

Bui l di ng GUI s wi th M

ATLAB

Version 5

How to Conta ct The Ma thW orks:

508-647-7000 Phone
508-647-7001 Fax
The MathWorks, I nc. Mai l
24 Pri me Park Way
Nati ck, MA 01760-1500

ht t p: //www. mat hwor ks . com

Web

f t p. mat hwor ks . com

Anonymous FTP server

comp. s of t - s y s . mat l ab

Newsgroup

s uppor t @mat hwor ks . com

Techni cal support

s ugges t @mat hwor ks . com

Product enhancement suggesti ons

bugs @mat hwor ks . com

Bug reports

doc@mat hwor ks . com

Documentati on error reports

s ubs cr i be@mat hwor ks . com

Subscri bi ng user regi strati on

s er v i ce@mat hwor ks . com

Order status, l i cense renewal s, passcodes

i nf o@mat hwor ks . com

Sal es, pri ci ng, and general i nformati on

Building GUI s with MATLAB

(December 1996)

COPYRI GHT 1984 - 1996 by The MathWorks, I nc. Al l Ri ghts Reserved.

The software descri bed i n thi s document i s furni shed under a l i cense agreement. The software may be used
or copi ed onl y under the terms of the l i cense agreement. No part of thi s manual may be photocopi ed or repro-

duced i n any form wi thout pri or wri tten consent from The MathWorks, I nc

.

U.S. GOVERNMENT: I f Li censee i s acqui ri ng the software on behal f of any uni t or agency of the U. S.
Government, the fol l owi ng shal l appl y:
(a) for uni ts of the Department of Defense:
RESTRI CTED RI GHTS LEGEND: Use, dupl i cati on, or di scl osure by the Government i s subject to restri c-
ti ons as set forth i n subparagraph (c)(1)(i i ) of the Ri ghts i n Techni cal Data and Computer Software Cl ause
at DFARS 252.227-7013.
(b) for any other uni t or agency:
NOTI CE - Notwi thstandi ng any other l ease or l i cense agreement that may pertai n to, or accompany the
del i very of, the computer software and accompanyi ng documentati on, the ri ghts of the Government
regardi ng i ts use, reproducti on and di scl osure are as set forth i n Cl ause 52.227-19(c)(2) of the FAR.
Contractor/manufacturer i s The MathWorks I nc., 24 Pri me Park Way, Nati ck, MA 01760-1500.

M

ATLAB

, S

I MULI NK, and Handl e Graphi cs

are regi stered trademarks and Real -Ti me Workshop i s a trade-
mark of The MathWorks, I nc.
Other product or brand names are trademarks or regi stered trademarks of thei r respecti ve hol ders.

Pri nti ng Hi story: December 1996 Fi rst pri nti ng for MATLAB 5
PH O N E
FA X
u
M
A
I
L
IN TER N ET
@
E-M A IL

i

Contents

1

Introduction

Introduction

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-2

How to Use Thi s Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-2

The Bi g Pi cture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-3
A Quick Start with Guide

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-4

Modi fyi ng Properti es wi th the Property Edi tor . . . . . . . . . . . . . .

1-4

Addi ng Buttons wi th the Control Panel . . . . . . . . . . . . . . . . . . . .

1-6

Setti ng Cal l backs wi th the Cal l back Edi tor . . . . . . . . . . . . . . . . .

1-7

Acti vati ng the Fi gure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-8

The Bottom Li ne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-9

2

GUI Design

Introduction

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-2
Design Principles

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-3

Si mpl i ci ty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-4

Consi stency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-7

Fami l i ari ty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-7

The Dynami c I nterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-9

Keep I t Si mpl e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-11
Design Process

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-12

A Compl ete Exampl e: Preci pi tati on Fi l es . . . . . . . . . . . . . . . . .

2-15

ii

Contents

3

GUI Implementation

Introduction

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-2
Handle Graphics and the Property Editor

. . . . . . . . . . . . . . .

3-3

The Property Edi tor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-3
GUI Layout with Guide

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-9

The Control Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-10

The Property Edi tor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-12

The Cal l back Edi tor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-12

The Al i gnment Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-14

The Menu Edi tor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-15

A Compl ete Exampl e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-16
Writing Callbacks

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-25

Layout vs. Cal l backs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-25

Cal l back Ti ps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-25
A Complete Example: Temperature Conversion

. . . . . . . . .

3-35

4

Reference

1

I ntroducti on

1-2 Introduction
1-2

How to Use Thi s Book

1-3

The Bi g Pi cture

1-4 A Quick Start with Guide
1-4

Modi fyi ng Properti es wi th the Property Edi tor

1-6

Addi ng Buttons wi th the Control Panel

1-8

Setti ng Cal l backs wi th the Cal l back Edi tor

1-9

Acti vati ng the Fi gure

1-9

The Bottom Li ne

1

Introduction

1-2

Introduction

Good tool s make for pl easant work.
Thi s book i s about how to make MATLAB-based Graphi cal User I nter-
face (GUI ) tool s. I t fal l s natural l y i nto two parts:

GUI desi gn, or

how to make something thats useful

GUI i mpl ementati on, or

how to make something that works

The pri nci pl es of good GUI desi gn are, for the most part, ti mel ess and
uni versal . They appl y i n MATLAB as much as they appl y anywhere el se,
though we consi der them here wi th respect to speci fi c exampl es. The
gui del i nes for GUI i mpl ementati on, on the other hand, tend to be much
more speci fi cmany of the i mpl ementati on detai l s we di scuss here
werent possi bl e i n MATLAB unti l recentl y. Accordi ngl y, i n thi s manual
there i s a trend from the general to the speci fi c. Part of the second hal f of
the manual i s devoted to the use of MATLABs GUI -bui l di ng tool , Gui de
(Graphi cal User I nterface Devel opment Envi ronment). A qui ck start
exampl e of how to use Gui de al so cl oses out thi s i ntroductory chapter.

How to Use This Book

The goal of thi s book i s to address both the desi gn of the GUI , and i ts
rapi d and robust i mpl ementati on i n the MATLAB envi ronment usi ng
Gui de. I f you onl y want to know how to use Gui de, read through the rest
of thi s i ntroducti on and then go to Chapter 3, GUI I mpl ementati on. I f
you al so want to l earn about desi gni ng GUI s, read Chapter 2 as wel l .
Examples Online The M-l es behi nd many of the exampl es i n thi s
manual can be found i n f t p: //f t p. mat hwor ks . com/pub/mat hwor ks /
t ool box /bui l di ng- gui s /.
Introduction
1-3
The Big Picture
Thi s manual i ncl udes many speci fi c recommendati ons about detai l s of
i mpl ementati on, desi gn, and so on, but keep i n mi nd the bi g pi cture: the
user i nterface you create, whether bi g or smal l , si mpl e or extravagant, i s
a single entity wi th a certai n personality to hel p a specific user perform a
specific task. Who i s that user? What i s that task? What i s that person-
al i ty?
To see i f your i nterface i s doi ng a good job, here are two good generi c
questi ons:
1 Do the users al ways know where they are?
2 Do they al ways know where to go next?
Keep returni ng to these questi ons, keep thi nki ng about the bi g pi cture,
and the detai l s fal l i nto pl ace much easi er.
The user interface you create is a
single entity with a
certain personality to help a
specific user perform a
specific task.
The Big Picture
1 Introduction
1-4
A Quick Start with Guide
MATLAB i s bui l t around a programmi ng l anguage, and as such i ts
real l y desi gned wi th tool -bui l di ng i n mi nd. Gui de extends MATLABs
support for rapi d codi ng i nto the real m of bui l di ng GUI s.
Gui de i s a set of MATLAB tool s desi gned to make bui l di ng GUI s easi er
and faster. Just as wri ti ng math i n MATLAB i s much l i ke wri ti ng i t on
paper, bui l di ng a GUI wi th Gui de i s much l i ke drawi ng one on paper. As
a resul t, you can l ay out a compl ex graphi cal tool i n mi nutes. Once your
buttons and pl ots are i n pl ace, the Gui de Cal l back Edi tor l ets you set up
the MATLAB code that gets executed when a parti cul ar button i s
pressed.
Modifying Properties with the Property Editor
The fi ve tool s that together make up Gui de are:
The Property Edi tor
The Gui de Control Panel
The Cal l back Edi tor
The Al i gnment Tool
The Menu Edi tor
We consi der the top three i n thi s Qui ck Start i ntroducti on. Lets start
wi th the Property Edi tor. I n MATLAB Handl e Graphi cs, every graphi cal
object has a handl e and a number of properti es. For i nstance, a fi gure
wi ndow has a Col or property and a Vi s i bl e property, and so on. To vi ew
and change these properti es from the command l i ne, you need to use the
s et and get commands together wi th the handl e for the fi gure. The Prop-
erty Edi tor i s desi gned to l et you modi fy these properti es i nteracti vel y.
For i nstance, pl ot the curve t sin(t) :
>> t = 0: 0. 1: 20;
>> pl ot ( t , t . *s i n( t ) )
>> get ( gcf , ' Col or ' )
ans =
0. 8000 0. 8000 0. 8000
Here were usi ng the get command to query the fi gures Col or property
(recal l that gcf i s a functi on that returns the handl e of the current
A Q uick Start w ith G uide
1-5
fi gure). Al l col ors i n MATLAB are stored as RGB (red, green, and bl ue)
tri pl ets, where [ 1 1 1] i s whi te, and [ 0 0 0] i s bl ack. We can use the
Property Edi tor to fi nd and modi fy the same i nformati on. I nvoke the
Property Edi tor wi th the command pr opedi t .
>> pr opedi t ( gcf )
The Property Edi tor can be used to change the properti es of the fi gure.
Cl i ck i n the Show Property List checkbox and scrol l down unti l you see
the word Col or i n the fi rst col umn of the Property Li st. Cl i ck on that l i ne
i n the l i stbox, and the current col or of the fi gure qui ckl y appears i n the
edi t fi el d just to the ri ght. Now you can change to somethi ng darker, say
[ 0. 6 0. 6 0. 6] . You can use the Property Edi tor to query or change any
property.
As a si mpl e GUI for getti ng started, l ets add two buttons to thi s fi gure:
one to turn the axi s gri d off and one to turn i t back on.
grid on grid off
Figure 1
gr i d on
Callback
gr i d of f
Callback
grid on grid off
Figure 1
click
1 Introduction
1-6
Adding Buttons with the Control Panel
Typi ng gui de i n the MATLAB Command Wi ndow bri ngs up the Gui de
Control Panel and control s (or puts i nto edi t mode) the si ne wave
fi gure. Heres what you shoul d see.
The dashed whi te l i nes i n the control l ed fi gure shown on the l eft above
i ndi cate i ts control l ed state. The Gui de Control Panel i s di vi ded i nto
three mai n parts:
l i st of Gui de Tool s (at the top)
Gui de-Control l ed Fi gure Li st (i n the mi ddl e)
New Object Pal ette (at the bottom)
The Gui de Tool s i ncl ude the al ready-menti oned Property Edi tor, the
Cal l back Edi tor, the Al i gnment Tool , and the Menu Edi tor. I n thi s
exampl e, the Property Edi tor button i s sel ected (pushed i n) because
that tool i s currentl y open on the desktop.
I n the mi ddl e of the Control Panel , the Gui de-Control l ed Fi gure Li st
shows what fi gures are open and whether or not they are bei ng con-
trol l ed by Gui de. When a fi gure i s i n a Gui de-control l ed state, you can
move buttons, axes, and other objects i nsi de that fi gure si mpl y by
cl i cki ng on them and draggi ng thema wel come rel i ef from cal cul ati ng
indicate the figure is
controlled by Guide.
The Figure List
in the Control
Panel also shows
which figures
are controlled.
Dashed white lines in the figure
1-7
numeri cal posi ti ons i n MATLAB code. Once everythi ng i s as you l i ke i t,
then you can acti vate the fi gure to return i t to normal behavi or (i .e. no
cl i cki ng and draggi ng).
At the bottom of the Control Panel i s the New Object Pal ette. To add an
object l i ke a push button, you cl i ck on the appropri ate regi on and then
cl i ck and drag i n the Gui de-control l ed fi gure. Cl i ck once on the button
fi el d i n the Gui de Control Panel and you can add a button to the fi gure
by cl i cki ng i n the control l ed fi gure and draggi ng unti l the button i s the
si ze you want.
The new button i s sti l l sel ected, so use the Property Edi tor to set i ts
St r i ng property to ' gr i d on' (i ts i mportant to i ncl ude the si ngl e
quotes). Now you have a fi gure that l ooks l i ke the ri ghtmost fi gure bel ow.
Setting Callbacks with the Callback Editor
Weve posi ti oned a button where we want i t, but we havent defi ned what
happens when i t gets cl i cked. Thi s i s a job for the Cal l back Edi tor. Wi th
the button sti l l sel ected, open up the Cal l back Edi tor by cl i cki ng the
second tool i n the Control Panel , sel ect Cal l back from the pop-up menu,
then the axes are resized then the button is added
First the figure is controlled,
by clicking and dragging, using the Control Panel
and modified with the
Property Editor.
1 Introduction
1-8
and enter the cal l back: gr i d on (No need for quotes when usi ng the Cal l -
back Edi tor).
Once the fi gure i s acti vated, whenever the button i s pushed, MATLAB
runs thi s code, and the gri d gets turned on. The code you choose to put i n
here can be as si mpl e or compl ex as you l i ke. I n thi s case, the code i s qui te
si mpl e. Before we fi ni sh up, we want to add another button si mi l ar to the
fi rst one. Copy and paste the button shown above usi ng the Edit menu
i n the control l ed fi gure, change both the stri ng and the cal l back to say
gr i d of f , and youre ready to run.
Activating the Figure
The l ast step i s to pul l the fi gure out of edi t mode. Thi s i s known as acti -
vati ng the fi gure. Fi rst, cl i ck on the Control l ed Fi gure Li st i n the Gui de
Control Panel where i t says Fi gure No. 1. The Control l ed Fi gure Li st
i ndi cates that Fi gure 1 i s about to be acti vated. Now press the Apply
button, and the fi gure i s acti vated (you are asked i f you want to save the
fi gure fi rst). The resul t i s a brand new MATLAB GUI .
The grid on button is selected.
Notice the pop-up menu
must be set to Callback.
1-9
The Bottom Line
I t wi l l al ways be hard to desi gn good GUI s, but i t shoul dnt be so hard to
i mpl ement them. Gui de i s desi gned to take the tedi um out of the process.
But i n addi ti on to bei ng a l ayout tool for GUI s, Gui de gi ves you powerful
tool s l i ke the Property Edi tor that can be used any ti me youre deal i ng
wi th MATLAB graphi cs. The Property Edi tor al one can be thought of as
a debuggi ng tool , a codi ng assi stant (for rememberi ng al l those property
names and val ues), and a l ayout tool . When combi ned wi th the Gui de
Control Panel , the Cal l back Edi tor, the Menu Edi tor and the Al i gnment
Tool , the resul ti ng combi nati on gi ves you unprecedented command of
MATLAB graphi cs. Good tool s make for pl easant work, and Gui de makes
bui l di ng good tool s easi er than ever.
Figure 1 is now active.
Since there are no
controlled figures, the
New Object Palette
is grayed out.
1 Introduction
1-10

2
GUI Desi gn
2-2 Introduction
2-3 Design Principles
2-4 Si mpl i ci ty
2-7 Consi stency
2-7 Fami l i ari ty
2-9 The Dynami c I nterface
2-11 Keep I t Si mpl e
2-12 Design Process
2-15 A Compl ete Exampl e: Preci pi tati on Fi l es
2 G U I D esign
2-2
Introduction
Thi s chapter i s about the fi rst hal f of the GUI creati on process: desi gni ng
the GUI . Desi gni ng means everythi ng you do before you start to wri te the
code that resul ts i n a fi nal worki ng GUI . Si nce GUI desi gn i s not a si mpl e
reci pe, thi s chapter i s i tsel f di vi ded i nto two parts: gui di ng pri nci pl es for
desi gn, and a suggested process to fol l ow for desi gn.
D esign Principles
2-3
Design Principles
GUI desi gn has been around for a short ti me, but the uni versal qual i ti es
of good desi gn have remai ned unchanged by i ts arri val . Thi s di sappoi nts
some peopl e who bel i eve GUI desi gn ought to be a compl etel y unexpl ored
terri tory. But i t can al so be extremel y comforti ng to tackl e a GUI desi gn
probl em and fi nd centuri es of accumul ated wi sdom wai ti ng pati entl y to
hel p you.
Hundreds of books have been wri tten about desi gn, and the best we can
expect to do here i s emphasi ze fundamental themes. The good news i s
that the same i deas keep comi ng up over and over agai n. Here i s the
short l i st: Si mpl i ci ty, Consi stency, and Fami l i ari ty.
Each word i s real l y the center of a natural group, si nce many words can
be used to descri be the same basi c i deas. But of these concepts, l arge and
smal l , the undi sputed ki ng i s thi s: Si mpl i ci ty.
To the quanti tati vel y i ncl i ned, these i deal s may sound too fuzzy. How
can we be more speci fi c? Wi th respect to GUI desi gn, two metri cs i nform
everythi ng we do:
1 How l ong does i t take to perform a task the fi rst ti me?
2 How l ong does i t take to perform a task once the i nterface i s fami l i ar?
Simplicity
Consistency
Fa milia rity
unity
cla rity
directness
elega nce
cha rm
comfort
a lignment
integrity
ha rmony
friendliness
2 G U I D esign
2-4
Each of the themes above bears di rectl y on these two measures.
Simplicity
Si mpl i ci ty i n desi gn i s our chi ef goal . A si mpl e GUI has a cl ean l ook and
a sense of uni ty. I ts very easy to add functi onal i ty to the GUI youre
bui l di ng, but i f that functi onal i ty real l y doesnt bel ong, take i t out. Avoi d
screen cl utter, and onl y present users wi th choi ces that advance them
toward the compl eti on of the task.
Emphasize Form, not Number Cl utter obscures val uabl e i nformati on.
Si nce vi sual i zati on i s i nherentl y more qual i tati ve than quanti tati ve,
concentrate on the shape and l et the l abel i ng vani sh.
Once you l et yoursel f remove a pi ece of the GUI that doesnt absol utel y
need to be there, you may fi nd that you can el i mi nate a l ot of supporti ng
machi nery that no l onger has any purpose.
Minimize the Area of Interaction Dont use two gures when one wi l l
do. I f youre demonstrati ng i nput-output rel ati onshi ps, put the i nput
ri ght next to the output.
The grid lines on the
left dont really add
value to the image.
D esign Principles
2-5
Thi s Opti mi zati on Tool box demo (bandem. m) shows how di fferent opti mi -
zati on methods fi nd the l owest poi nt i n a compl ex surface.
The fi gure above shows a contour pl ot of a functi on were tryi ng to mi ni -
mi ze. We are presented wi th the starti ng poi nt for the mi ni mi zati on and
the correct endpoi nt at the very l owest poi nt of the surface. We are gi ven,
from the command l i ne, several numbered opti ons to choose from. Type
i n a number and you see an ani mati on of the mi ni mi zati on as i t occurs.
The fi gure above shows an i mproved versi on of the demo. Weve uni fi ed
the presentati on i nto one fi gure to mi ni mi ze the area of i nteracti on.
Weve al so repl aced enteri ng a number between one and si x wi th cl i cki ng
on a button. Thi s i s another way to mi ni mi ze the area of i nteracti on. The
method l abel s are ri ght on the buttons. Fi nal l y, si nce the demo i s qual i -
The original
Banana Function
demo. You have to
shift your attention
fromthe Command
Window to the
figure and back.
The redesigned
Banana Function
demo. Now everything
is on one figure.
2 G U I D esign
2-6
tati ve (the goal i s to fi nd the l owest poi nt), we can throw away the num-
bers on the pl ot and turn up the contrast on the col ors, thereby maki ng
the graph much more readabl e.
Use Graphical Input Rather Than Numeric Rather than typi ng i n num-
bers, l et the user enter data by di rectl y touchi ng the graphi c. Let the
graphi c i ndex i nto i tsel f.
I n the exampl e shown bel ow, you can wal k around the three-di men-
si onal shape shown on the ri ght si de of the fi gure by setti ng the camera
posi ti on of the vi ewpoi nt. Camera posi ti on i s gi ven by three Cartesi an
coordi nates that can be hard to determi ne, but thi s l i ttl e GUI si desteps
the probl em by l etti ng the user pl ace the camera (represented by an X) on
a vi ewi ng ci rcl e around a smal l representati on of the shape.
In this example you click on the X to change
the position of the camera. Click on the dot
to change the position of the light source.
D esign Principles
2-7
Consistency
The further users are from thei r base of experi ence, the more l i kel y they
are to feel di sori ented. Anythi ng you can do to keep the user from feel i ng
confused i s extraordi nari l y i mportant.
The GUI on the l eft shows sound anal ysi s capabi l i ty (fi l ename
x ps ound. m), and the one on the ri ght i ntroduces some graphi cs program-
mi ng concepts (fi l ename gr af 3d. m). They are i n two very di fferent parts
of the MATLAB demo software, but they share (al ong wi th a great many
other MATLAB demos) a number of basi c l ayout characteri sti cs. Thi s
consi stency makes i t easi er to move from one demo to the next by gener-
ati ng a sense of fami l i ari ty, whi ch al so l eads to the next theme.
Familiarity
I f the GUI that you create i s i n some sense fami l i ar to i ts users, then they
can general l y l earn how to use i t more qui ckl y. Thi s i s val ue of basi ng the
GUI on a good metaphor. They mi ght not know how to do a gi ven task,
but the metaphor hel ps them make a good guess.
These two demos are about very different things, but both respect the
convention of putting controls on the right side grouped inside a frame.
Notice the consistent placement of the Info and Close buttons.
2 G U I D esign
2-8
Use the Familiar to Draw Users into the GUI Even a smal l connecti on
to the users real worl d experi ence can bri dge the gap between the
onscreen experi ence and the data i t represents.
These two GUI s are exampl es of drawi ng on experi ence outsi de of
MATLAB to enri ch understandi ng wi thi n i t. On the l eft, were l ooki ng at
the spectral anal ysi s of the tones generated by a touch-tone phone (fi l e-
name phone. m, from the Si gnal Processi ng Tool box). The upper pl ot
shows the sound waveform, and the l ower pl ot shows the spectral con-
tent. To generate the tone, we use a representati on of the phone
touch-tone keypad i tsel f.
The fi gure on the ri ght shows a demonstrati on of the travel i ng sal esman
probl em (fi l ename t r av el . m), whi ch goes l i ke thi s: Gi ven a l i st of ci ti es
to be vi si ted, what route between them resul ts i n the shortest overal l
tri p? I n thi s demo, the ci ti es are real l y just random poi nts on the pl ane.
The touch-tone phone pad in the example on the left and the outline of the U.S.
in the example on the right both provide some familiar context for the GUI.
D esign Principles
2-9
But by superi mposi ng an outl i ne of the Uni ted States, thi s mathemati cal
curi osi ty suddenl y feel s more rel evant.
The GUI shown above i l l ustrates the MATLAB random number gener-
ator by si mul ati ng the tossi ng of a coi n. The i mage of a penny i n the
upper l eft part of the fi gure emphasi zes the content of the two pl ots (a
hi stogram and a hi story pl ot). Fami l i ari ty draws peopl e i nto the GUI and
makes them feel comfortabl e.
The Dynamic Interface
Much of what weve di scussed so far i s bi ased by the stati c worl d of
graphi c desi gn. But the worl d medi ated by the computer i s a dynami c
one, and there are a few more key words to menti on. Where you act usi ng
the GUI , your acti ons shoul d be: I mmedi ate, Conti nuous, and Reversi bl e.
Permit Direct Manipulation Whenever possi bl e, l et the user grab the
data as though i t were a sol i d object.
A photograph of a penny in this demo
helps communicate the basic nature of
this statistical experiment.
Immedia te
Continuous
Reversible
sna ppy
direct
encoura ging
smooth
physica l
friendly
2 G U I D esign
2-10
Wi th respect to i mmedi acy and conti nui ty, cal cul ati on ti me i s the most
i mportant consi derati on. I f you can make a cal cul ati on and di spl ay the
resul t i nstantl y, by al l means do so. But i f cal cul ati on ti me i s si gni fi cant,
you may be better off usi ng a button to i nvoke the acti on.
I n the exampl e above (fi l e name s i gdemo2. m i n the Si gnal Processi ng
Tool box), the cursor i s shown i n the upper pl ot draggi ng a waveform. The
Fouri er transform of the si gnal i s i nstantl y updated i n the l ower pl ot.
The resul t i s an i nsi ghtful i l l ustrati on of the rel ati onshi p between a
si gnal and i ts Fouri er transform.
The GUI above shows the l i ft generated by an ai rfoi l as a functi on of
angl e of attack. I f you cl i ck anywhere on the l i ft curve, the ai rfoi l on the
ri ght si de i mmedi ate rotates to the sel ected angl e and the l i ft arrow
shows the magni tude of the l i ft generated. You can al so set the angl e of
attack by cl i cki ng on the wi ng and rotati ng i t to a new angl e. Thi s ki nd
of i mmedi acy and conti nui ty promotes qui ck l earni ng and a hi gh degree
of i nteracti on.
Fi nal l y, reversi bi l i ty i s most often embodi ed by the Undo menu.
Undoi ng i s someti mes di ffi cul t to i mpl ement, but i ts al ways appreci ated
The fact that you can grab the line
in the top part of this GUI and instantly
see its Fourier transformin the bottom
greatly enhances the GUIs value.
In this demo, you can change the angle
of attack of the airfoil by literally grabbing
the wing and rotating it. The corresponding
lift shows up as a vector and a call-out on
the lift plot.
D esign Principles
2-11
by users. A wel l -bui l t undo capabi l i ty encourages experi mentati on and a
sense of comfort i n worki ng wi th your GUI .
Keep It Simple
Li sts of desi gn gui del i nes grow qui ckl y, and they can eventual l y obscure
the very i deas they were meant to promote. Remember to l earn from
GUI s that you l i ke, and when i t doubt, keep i t si mpl e.
? !
Keep it
SIMPLE
2 G U I D esign
2-12
Design Process
I n thi s secti on, we suggest a road map for creati ng GUI s i n MATLAB.
Li ke everythi ng associ ated wi th desi gn, thi s real l y amounts to some sug-
gesti ons about how to thi nk, rather than a step-by-step reci pe. I ts
hel pful to thi nk about the GUI creati on process as breaki ng i nto a desi gn
phase and an i mpl ementati on phase. Thi s concept i s i l l ustrated i n the
di agram bel ow.
Thi s i s the most i mportant fact presented i n thi s chapter: compl ete the
desi gn of your GUI before you begi n to i mpl ement your GUI .
Dont Start Coding Until Youre Done Designing I f you start worki ng
on the i mpl ementati on too soon, you tend to converge much sl ower on a
nal desi gn.
Of course the desi gn may change once you start codi ng, and there may
wel l be desi gn deci si ons that you cant properl y make unti l youve wri tten
some code. Sti l l , take the desi gn part just as far as you can on paper,
because you are guaranteed to save yoursel f a l ot of ti me.
Noti ce the arrows i n thi s di agram poi nt i n both di recti onssometi mes
you move forward and someti mes back. I n fact, some have drawn thi s
di agram as a spi ral , noti ng that i nevi tabl y your fi rst desi gn needs to go
through the whol e process mul ti pl e ti mes.
Define Task START
STOP
Design Implementation
Draw GUI
Test Design
Write Code
(use Guide)
Test Code
D esign Process
2-13
Start with the Ideal Dont make compromi ses too soon. The best nal
desi gns grow from an i deal i zed i ni ti al vi si on.
The i deal desi gn i s somethi ng that exi sts i n your head after youve spent
a l ong ti me thi nki ng about the task and the user. Thi s desi gn mi ght be
expensi ve i n terms of devel opment effort or computi ng power requi red.
But for whatever reason, i ts the best way to approach the task. Thi nk of
i t as a three-di mensi onal shape that must now be projected down i nto the
two di mensi ons of the fi nal (and achi evabl e) i mpl ementati on. I f you start
out wi th the merel y achi evabl e, the fi nal resul t wi l l be hal f-hearted. I f
you start wi th the i deal , i ts often surpri si ng what you can make the tech-
nol ogy do for you.
Test the GUI on Paper Drawi ng and testi ng your GUI on paper keeps
you and any testers from over-focusi ng on the detai l ed aspects of the
GUI .
Earl y on i n the desi gn process, theres no poi nt i n pl ayi ng wi th font si zes
and button col ors. What matters i s overal l behavi or and appearance of
the GUI . Paper prototypi ng i s a good exerci se for keepi ng thi ngs i n per-
specti ve. The i dea i s to bui l d your enti re i nterface out of paper and try i t
out. Si nce theres no code i nvol ved, you pl ay the rol e of the computer
whi l e a cooperati ve user si tti ng across from you performs a task. I ts an
excel l ent way to see i f the GUI does what you (and the user) want i t to do.
Paper prototyping: these are still video-images frompaper prototype
usability testing at The MathWorks. Notice the simulated watch cursor
in the rightmost image.
2 G U I D esign
2-14
Paper prototypi ng tests the thoroughness of your desi gn and can resol ve
di sagreements about tough desi gn questi ons that mi ght otherwi se be
i ntractabl e.
By the ti me youre ready to start wri ti ng code, you shoul d have a com-
pl ete di agram or set of di agrams of the GUI (the l ayout) and an exact
descri pti on of what functi onal i ty i s associ ated wi th each part of the GUI
(the cal l backs). Actual l y, the term wri te the code i s somewhat mi s-
l eadi ng now that Gui de i s avai l abl e to make your job easi er. Part of the
codi ng process i s about bui l di ng up the GUI wi th MATLAB components
l i ke ui control s and axes, putti ng everythi ng i n the ri ght pl ace. You can
ei ther do thi s di rectl y wi th pages of i ni ti al i zati on code that l ook l i ke thi s.
ui cont r ol ( ' St y l e' , ' pus hbut t on' , . . .
' St r i ng' , ' Pl ot ' , . . .
' Cal l back' , ' pl ot ( x , y ) ' , . . .
' Uni t s ' , ' poi nt ' , . . .
' Pos i t i on' , [ 50 65 75 35] )
or you can use Gui de (MATLABs GUI Devel opment Envi ronment).
Gui de i s descri bed i n more detai l i n Chapter 3, but the basi c i dea i s that
i t l ets you do al l your l ayout graphi cal l y.
As shown i n the i l l ustrati on above, even after youve used Gui de to get
the l ayout ri ght, you sti l l need to wri te the MATLAB l anguage cal l backs.
pl ot ( x , y )
Callback
Load
l oad my dat a;
x =XYDat a( : , 1) ;
y =XYDat a( : , 2) ;
Callback
Plot
cl os e( gcbf )
Callback
Close
Guide helps
you put all the
elements in
place
You still need to
manage what
happens when
the button gets
pushed
La y out
Ca l l b a ck s
Figure 1
D esign Process
2-15
A Complete Example: Precipitation Files
I n thi s secti on we go through the desi gn process from begi nni ng to end,
noti ng each step al ong the way. One thi ng that becomes obvi ous when
you start to work wi th a real exampl e i s how much the di fferent tasks on
our process checkl i st spi l l i nto each other. I n thi s exampl e, the process
breaks i nto three natural cl usters.
We want to use MATLAB to vi ew weather data that we found on the net.
Speci fi cal l y, these fi l es are monthl y preci pi tati on datasets avai l abl e from
the US Nati onal Cl i mati c Data Center (ht t p: //www. ncdc. noaa. gov ) as
part of the NCDC di gi tal database TD3220.
1 . Dene the Ta sk Dra w the GUI
The task i s sti l l somewhat vague, and surpri si ngl y enough thi s i s often
the case i n real worl d exampl es. You dont al ways know what youre
l ooki ng for unti l you start to draw up some scenari os. Here i s an excerpt
from the . pr p preci pi tati on data fi l es we want to pl ot:
We have the . pr p fi l es for a number of di fferent ci ti es. We want to sel ect
the data fi l e for a gi ven ci ty and see a pl ot of the monthl y preci pi tati on
fi gures. Heres si mpl e i l l ustrati on of what we want to do.
NUMBER LOCATI ON STATE YEAR JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC ANNUAL
190770 BOSTON LOGAN I NTL AP MA 1948 511 208 314 262 537 450 453 124 67 484 516 125 4051
. . .
Figure 1
Boston
ra in
Chica go
ra in
SF
ra in
Choose a
da ta file
Selectively
view individua l
curves
Pa rse a nd
plot da ta
1
2
3
2 G U I D esign
2-16
The Ta sk. Sel ect a . pr p preci pi tati on fi l e for a gi ven ci ty and i nteracti vel y
vi ew the rai nfal l fi gures for each year i n that fi l e. Here i s sketch number
one.
Al l the . pr p fi l es i n the current di rectory are di spl ayed i n the l i stbox on
the ri ght. Cl i ck on the fi l e l i stbox and the data for that fi l e are read i nto
a MATLAB vari abl e and pl otted i n the axes on the l eft. Thi s i s a good
start, but we want a way to choose i ndi vi dual years from the l i st associ -
ated wi th any gi ven l ocati on. Heres another sketch that takes that i nto
account.
Plot of the yearly
rainfall data for a
given file
(Rainfall Plot)
List of all *.prp
files in the
current directory
(File Listbox)
Rainfall Plot
File Listbox
List of all years
for a given file
(Year Listbox)
D esign Process
2-17
Weve purposel y l eft i n some of the scri bbl ed annotati ons from these
sketches so you can see how the desi gn trul y proceeded. Here are some
observati ons about what weve got so far:
The fi rst thi ng we have to do i s sel ect a ci ty fi l e, so i t makes sense to
keep that on the l eft, si nce were used to readi ng from l eft to ri ght.
For symmetry and separati on of the l i stboxes, l ets move the year
l i stbox to the ri ght si de (where the fi l e l i stbox started out i n sketch
number one).
Some extra opti ons at the bottom of the fi gure woul d be ni ce. For
i nstance, we al most al ways want to i ncl ude a Close button and a Help
button.
Another ni ce opti on woul d be to pl ot the average rai nfal l for the
sel ected ci ty i n the Rai nfal l Pl ot, al ong wi th the abi l i ty to turn i t off
and on wi th a checkbox.
We can al so add a Select All Years button and a Deselect All Years
button.
Noti ce how fl ui d the desi gn i s at thi s poi nt. Move el ements al l over the
pl ace, test them i n your mi nd, try to see what works. By addi ng the
Average Rai nfal l opti on, weve expanded on the ori gi nal task, too. Heres
sketch number three, our l atest effort. Now we have a reasonabl e
drawi ng of what the GUI i s goi ng to l ook l i ke. Were not done wi th the
desi gn unti l we know exactl y what each part of the i nterface wi l l do. Here
are the procedures for each of the objects.
Rainfall Plot
File Listbox
Year Listbox
Help
Close
Show Average
Select All
Deselect All
2 G U I D esign
2-18
File Listbox. I denti fy the sel ected fi l e, parse i t and l oad the data i nto
MATLAB, put the year l i st i nto the Year Li stbox and pl ot the rai nfal l
data for al l years.
Yea r Listbox. I denti fy the year sel ected, and sel ect that l i ne i n the Rai nfal l
Pl ot and desel ect al l others.
Ra infa ll Plot. I f a l i ne i s cl i cked on, sel ect i t, desel ect al l other l i nes, then
sel ect the appropri ate year i n the Year Li stbox.
Show Avera ge. Thi s i s a checkbox that toggl es the vi si bi l i ty of the average
rai nfal l l i ne.
Help. Open a di al og box wi th some hel p text i n i t.
Close. Cl ose thi s fi gure.
Select All, Deselect All. Ei ther sel ect or desel ect al l of the curves i n the Rai n-
fal l Pl ot. On further consi derati on, these buttons dont seem very useful .
Whats the val ue of sel ecti ng every l ast curve? Lets remove these but-
tons.
Thi s i s our candi date for i mpl ementati on. Does i t meet the cri teri a set
forth i n the task? I n other words, i f we were to test i t agai nst our task,
woul d we be happy?
2 . Dra w the GUI Test the GUI
Testi ng the GUI doesnt mean wri ti ng code fi rst. I t means l ooki ng at
what youve drawn, putti ng yoursel f i n the pl ace of the user and seei ng i f
thi s sati sfi es the task. Thi s i s the stage where we mi ght try bui l di ng a
D esign Process
2-19
paper prototype of the GUI to see i f i t hol ds up wel l . Shown bel ow i s a
recap of the task wi th a cl eaned up versi on of our GUI drawi ngs.
Armed wi th our knowl edge about what each control on the fi gure does,
we can perform a few tests fi rst wi th oursel ves as the subject, then wi th
an offi ce mate or someone down the hal l , and fi nal l y, i f were seri ous
about doi ng the best possi bl e job, wi th real customers.
3 . W rite the Code Test the Code
The desi gn i s now compl ete. Si nce GUI l ayout and cal l back wri ti ng i s the
subject of the next chapter, we have reached the end of thi s exampl e.
Heres what rai nfal l GUI l ooks l i ke after usi ng Gui de to l ay out the
fi gure.
Figure 1
Show Average Help
boston.prp
chicago.prp
sfo.prp
1974
1975
1976
1987
1990
Years Files
Close
Choose a
da ta file
Selectively
view individua l
curves
Pa rse a nd
plot da ta
1
2
3
This is the GUI, built up with Guide,
that represents the final implementation
of our design.
2 G U I D esign
2-20

3
GUI I mpl ementati on
3-2 Introduction
3-3 Handle Graphics and the Property Editor
3-3 The Property Edi tor
3-9 GUI Layout with Guide
3-10 The Control Panel
3-12 The Property Edi tor
3-12 The Cal l back Edi tor
3-14 The Al i gnment Tool
3-15 The Menu Edi tor
3-16 A Compl ete Exampl e
3-25 Writing Callbacks
3-25 Layout vs. Cal l backs
3-25 Cal l back Ti ps
3-35 A Complete Example: Temperature Conversion
3 G U I Im plem entation
3-2
Introduction
Thi s chapter i s about the second hal f of the GUI creati on process: i mpl e-
menti ng the GUI wi th MATLAB code. We assume here that you al ready have
a good i dea of what you want to bui l d, and now you need to know the speci fi cs
about to bui l d i t.
We start off wi th a qui ck i ntroducti on to some Handl e Graphi csbasi cs and
how to use the Property Edi tor. The rest of the chapter di vi des i nto two parts:
how to use Gui de to l ay out a GUI , and how to wri te the cal l backs that do the
work behi nd the scenes.
H andle G raphics and the Property Editor
3-3
Handle Graphics and the Property Editor
Anythi ng that appears i n a MATLAB fi gure i s an exampl e of Handl e Graphi cs,
because every object on the screen has a uni que i denti fi er, cal l ed a handl e, that
al l ows you to go back and modi fy the object at any ti me. General l y theres no
need to worry about the handl es, but theyre al ways there. Shown bel ow i s a
di agram of the Handl e Graphi cs object hi erarchy. These are al l the categori es
of object types i n MATLAB.
The Property Edi tor, one of the Gui de tool s, i s extremel y useful for navi gati ng
the Handl e Graphi cs hi erarchy. I f you need to get or set any Handl e Graphi cs
property on any object, chances are you can do i t most easi l y wi th the Property
Edi tor.
The Property Editor
Lets step through an exampl e of usi ng the Property Edi tor just to get the feel
of how i t works. Try thi s:
s ur f ( peaks ( 25) )
pr opedi t ( gcf )
Remember that gcf , whi ch stands for get current fi gure, returns the handl e
of the current fi gure wi ndow. I f youre uncertai n about functi ons l i ke gcf , get ,
and s et , read the manual Using MATLAB Graphics. The functi on peaks ( 25)
returns some sampl e data i n a 25-by-25 matri x. Now we know that the com-
mand
s et ( gcf , ' Col or ' , ' r ed' )
Root
Figure
Uicontrol
Ima ge
Axes
Line
Uimenu
Pa tch Surfa ce Text Light
3-4
wi l l turn the background of the fi gure red. Si nce col or can al so be speci fi ed by
RGB (red, green, bl ue) tri pl ets, the command
s et ( gcf , ' Col or ' , [ 1 0 0] )
does just as wel l .
Lets take a l ook at how we woul d achi eve the same effect usi ng the Property
Edi tor. Bel ow the l abel f i gur e ( #1) i n the Property Edi tor there i s an edi tabl e
text fi el d. Thi s i s known as the Property Fi el d. Enter the word Col or there and
press the Return key. The RGB val ue for the defaul t fi gure background col or
appears i n the edi tabl e text fi el d just to the ri ght of i t. Thi s i s the Val ue Fi el d.
These two text fi el ds l et you edi t the Property-Val ue pai rs for any object i n
MATLAB. To make the fi gure background red, enter the word ' r ed' i n si ngl e
quotes i n the ri ght-hand, or Val ue Fi el d as shown i n the next fi gure, just the
way you woul d wi th the s et command.
Thats the qui ckest possi bl e i ntroducti on to the most versati l e of the Gui de
tool s, the Property Edi tor. Remember, anything you can vi ew or modi fy wi th
the s et and get commands, you can vi ew or modi fy wi th the Property Edi tor.
Noti ce that what you type i nto the Val ue Fi el d i s the same thi ng you woul d type
on the command l i ne. So coul d al so enter [ 1 0 0] i n the Val ue Fi el d, and the
resul t woul d be exactl y the same.
Using the Proper ty List
One drawback wi th the Property Fi el d i s that you have to know the name of
the property you want to change. Suppose you want to l abel thi s fi gure, but you
Value Field
Property
Field
3-5
dont know the property name that does the ri ght thi ng. I s i t Label or Name?
Cl i ck on the checkbox marked Show Property List and the Property Edi tor
changes shape so that i t i ncl udes a l i stbox wi th al l the properti es of the current
object di spl ayed.
You can now scrol l through al l of the properti es unti l you fi nd the one that l ooks
ri ght: Name. Here weve entered the name ' Red Peaks ' , so now that name
appears i n the ti tl e bar of the fi gure wi ndow.
Some properti es, such as the Vi s i bl e property, can be set to one of onl y a few
possi bi l i ti es. I n the case of Vi s i bl e, si nce the onl y two opti ons are yes and no,
the Val ue Fi el d i s repl aced wi th a pop-up menu. I n other words, the Property
Edi tor i s anti ci pati ng the fact that you onl y get to choose between two thi ngs.
Using the O bject Brow ser
Just as you typed pr opedi t ( gcf ) to edi t the fi gure, you can al so type
>> pr opedi t ( gca)
Value
Field
Checking this
box opens the
Property List
Property
Field
Property
List
3-6
to edi t the current axes. There can onl y be one Property Edi tor open at a ti me,
so i f you al ready had i t poi nti ng at the current fi gure, then i t just gets redi -
rected at the current axes.
The Property Edi tor, Cal l back Edi tor, and Al i gnment Tool al l i ncl ude an Object
Browser. The Object Browser shows you hi erarchi cal l y the name and sel ecti on
state of every object on screen. The Object Browser al l ows you to expand and
col l apse the hi erarchy of objects starti ng wi th the root. A pl us si gn (+) pre-
cedi ng an object i ndi cates that the object has chi l dren and that the hi erarchy
can be expanded. A mi nus si gn (- ) al so i ndi cates that an object has chi l dren
and that the hi erarchy can be col l apsed. I f an object has nei ther a pl us nor
mi nus si gn, then the object has no chi l dren and so cannot be expanded or col -
l apsed.
A sampl e Object Browser i s shown bel ow. The l eft col umn of the Object
Browser l i sts the object type and the ri ght col umn l i sts the tag.
Object Browser
Checking this
box opens the
Object Browser
Root
Figure
Uicontrol
Ima ge
Axes
Line
Uimenu
Pa tch Surfa ce Text Light
Notice the correspondence between the
Handle Graphics hierarchy and the
indentation level on the Object Browser
3-7
You can use the Property Edi tor wi th both the Object Browser and the Property
Li st vi si bl e.
Secrets for the Pow er User
The Property Edi tor i s the Swi ss Army kni fe of MATLAB graphi cs. Here are
some ti ps for maxi mum effi ci ency usage.
Multiple selection. Mul ti pl e objects, even mul ti pl e objects of wi del y
varyi ng types, can be queri ed and modi fi ed together. For i nstance, i f you use
the Object Browser to sel ect a l i ne and a l i stbox, onl y the properti es i n
common are di spl ayed. You can set the Vi s i bl e property to of f and both wi l l
di sappear.
Command completion. I f a fi gure has been sel ected, you can type the l et-
ters col i n the property fi el d (and press Return), and the Property Edi tor
i s smart enough to know that Col or i s the onl y possi bl e compl eti on. Thi s
saves huge amounts of typi ng.
Truncation. The property fi el d i gnores anythi ng after the fi rst space. So i f
you type i nto the begi nni ng of the text fi el d, press space and return, the ol d
Value
Field
Object
Browser
Property Editor
Property
List
Property
Field
3-8
text i s i gnored. Thi s hel ps wi th hands on keyboard edi ti ng, because i t mean
you dont have to sel ect the ol d text wi th the mouse and then erase before
typi ng i n the new val ue.
G U I Layout w ith G uide
3-9
GUI Layout with Guide
Gui de si mpl i fi es the creati on and mani pul ati on of Handl e Graphi cs objects.
Thi s means that:
I t si mpl i fi es access to the properti es of Handl e Graphi cs objects.
I t l ets you pl ace and arrange GUI el ements on a fi gure by cl i cki ng and drag-
gi ng wi th the mouse.
Speci fi cal l y, Gui de consi sts of fi ve MATLAB tool s that offer a streaml i ned
approach to worki ng wi th MATLAB fi gure wi ndows.
The Gui de tool s are the Control Panel , the Property Edi tor, the Cal l back
Edi tor, the Al i gnment Tool , and the Menu Edi tor. Each tool performs a di sti nct
The Menu
Editor
The Alignment
Tool
The Callback
Editor
The Control Panel
The Property
Editor
3-10
task and al so i s aware of and i nteracts wi th other tool s. You can open each
Gui de tool by enteri ng one of these commands at the MATLAB prompt.
gui de (for the Control Panel )
pr opedi t (for the Property Edi tor)
cbedi t (for the Cal l back Edi tor)
al i gn (for the Al i gnment Tool
menuedi t (for the Menu Edi tor)
The Control Panel
The Control Panel i s di vi ded i nto three parts.
The Gui de Tool Li st, for l aunchi ng i ndi vi dual tool
The Gui de-Control l ed Fi gure Li st, for control l i ng and acti vati ng fi gures.
The New Object Pal ette, for addi ng axes and ui control s to a fi gure.
The Control Panel
Buttons for
Guide-Controlled
Figure List for
New Object
Palette for adding
axes and uicontrols
activating and
controlling figures
launching the
Guide tools
3-11
There are ni ne di fferent ki nds of ui control s that can be added:
Push buttons
Radi o buttons
Checkboxes
UI edi tabl e text
UI stati c text
Sl i ders
Frames
Li stboxes
Pop-up menus
Controlling a nd Activa ting the Figure
Wi thi n the context of Gui de, al l MATLAB fi gures are ei ther control l ed or acti -
vated. The normal state of a fi gure i s the acti vated state. I n other words,
everythi ng i s worki ng just as expected: push buttons push, and pop-up menus
pop. But i f you want to rel ocate your push button from one si de of the fi gure to
the other, you need to put the fi gure i nto an edi tabl e, or control l ed state. A
fi gure i s automati cal l y control l ed by the Control Panel whenever you type
gui de from the command l i ne.
Figure 1
Plot
Figure 1
Plot
Guide Control Panel
Guide Controlled Figure List
click
Refresh Add Apply
Figure 1
Plot
Act i v e #1
Guide Control Panel
click
Refresh Add Apply
Cont r ol l ed #1
Guide Control Panel
Refresh Add Apply
Cont r ol l ed #1
To take control of a figure
with Guide, click on the
appropriate line of the
Guide-Controlled Figure List...
... then click on the Apply
button (alternatively, you can
double-click on the listbox).
Now the figure is listed as
controlled by Guide. The Apply
button is disabled.
3-12
To take control of an exi sti ng fi gure, cl i ck on that fi gures name i n the
Gui de-Control l ed Fi gure Li st, and then cl i ck on the Apply button. Whi te gri d
l i nes provi de a vi sual cl ue to remi nd you that a fi gure i s currentl y control l ed.
A control l ed fi gure means you can do the fol l owi ng.
Sel ect ui control s and axes by cl i cki ng on them
Move ui control s and axes by cl i cki ng and draggi ng them
Create and del ete ui control s and axes
You can even control more than one fi gure at a ti me, i f desi red. When you are
fi ni shed maki ng changes to the GUI , cl i ck once on the appropri ate l i ne of the
Gui de-Control l ed Fi gure Li st i n the Control Panel . The Fi gure Li st acknowl -
edges that you are requesti ng that a fi gure be acti vated. Al l you need to do i s
cl i ck on the Apply button and the fi gure i s acti vated.
Al l Gui de tool s are useful wi th both acti ve and control l ed fi gures. Thi s means
you can set the background col or on a fi gure regardl ess of whether i ts currentl y
control l ed by Gui de.
The Property Editor
For a ful l di scussi on of the Property Edi tor turn to the previ ous secti on Handl e
Graphi cs and the Property Edi tor.
The Callback Editor
The Cal l back Edi tor l ets you modi fy the cal l backs of sel ected objects. You can
change mul ti pl e l i nes of code at once usi ng the Edi t Box. The Edi t Box al so
makes i t easi er to enter Handl e Graphi cs code because i t al l ows you to omi t
nested quotes and enter code on mul ti pl e l i nes. You can i ni ti al i ze the Cal l back
3-13
Edi tor by enteri ng cbedi t from the MATLAB prompt, or by cl i cki ng on the
appropri ate button i n the Control Panel .
You can use the Cal l back Edi tor to make changes to any fi gure. For exampl e,
you mi ght want to change the But t onDownFcn for a fi gure di spl ay the current
fi gure handl e.
Begi n by sel ecti ng the Show Object Browser check box to di spl ay a l i st of
objects. Sel ect the property you want to modi fy, i n thi s case the But t onDownFcn.
Sel ect the Apply push button when you have fi ni shed maki ng changes. I f you
cl i ck i n the fi gure now, i t di spl ays the current fi gure i n the MATLAB work-
space.
Object
Browser
Check box
Edit Box
Object
Type
Object
Tag
The Callback Editor
Callback
Edit Box
Object
Browser
Check box
Object
Browser
Callback Editor
Type Pop-up
Menu
3-14
The Alignment Tool
The Al i gnment Tool al l ows you to al i gn sel ected objects usi ng a col l ecti on of
verti cal and hori zontal al i gnment or di stri buti on push buttons. I n the past, you
needed to know and speci fy the exact l ocati on of any object that you wanted to
move usi ng compl i cated Handl e Graphi cs commands. Now you can move
objects rel ati ve to each other or di stri bute the gaps between objects i n a si ngl e
step.
You can open the Al i gnment Tool by enteri ng al i gn from the MATLAB prompt
or by cl i cki ng on the appropri ate button on the Control Panel .
Alignment Tool Fea tures
The verti cal al i gnment or di stri buti on push buttons do the fol l owi ng: al i gn
by top, al i gn by mi ddl e, al i gn by bottom, di stri bute top-to-bottom, and set
expl i ci t spaci ng.
The hori zontal al i gnment or di stri buti on push buttons do the fol l owi ng: al i gn
by l eft, al i gn by mi ddl e, al i gn by ri ght, di stri bute l eft-to-ri ght, and set
expl i ci t spaci ng.
Al i gnment and di stri buti on al ways l eave the affected objects i nsi de the i magi -
nary box that ori gi nal l y bounded them.
Object
Browser
Alignment Tool
3-15
The Menu Editor
Use the Menu Edi tor to add and edi t the user-created pul l -down menus asso-
ci ate wi th a fi gure. The menus you create wi th the Menu Edi tor are i n addi ti on
to the basi c menus that normal l y bel ong to a fi gure (File, Edit, Window,
Help). As far as Gui de i s concerned, those four system-l evel menus are i nvi s-
i bl e and unreachabl e. I t i s possi bl e to hi de the four system-l evel menus by set-
ti ng the MenuBar property of the fi gure to none.
The Menu Edi tor does not di spl ay the new menu unti l the fi gure has been acti -
vated.
Menu Editor
Use the four menu
Object
Browser
hierarchy buttons
to promote and
demote menu
items.
3-16
A Complete Example
Here i s a GUI that l ets you modi fy the col ormap and background col or of a
fi gure wi ndow and to change what i t bei ng pl otted. Lets use Gui de to bui l d i t
from scratch. Thi s exampl e touches on al l the major aspects of Gui de.
Type gui de at the MATLAB command l i ne. A new fi gure and the Gui de Control
Panel wi l l appear. Press the axes button on the Control Panel and sel ect an
area on the control l ed fi gure.
Uimenu
Aligned
buttons
Listbox
Editable text
3-17
After reposi ti oni ng the axes and resi zi ng the fi gure, add a l i stbox ui control by
sel ecti ng from the Edi t/Add Object/l i stbox menu on the Control l ed Fi gure or by
sel ecti ng i t on the Control Panel and then droppi ng i t on the fi gure. Add an
edi tabl e text box bel ow i t as shown here.
Click here to create a new axes.
First add a listbox...
... then add an editable text box.
3-18
Next, l eft-al i gn the l i stbox, the edi t box, and the axes. You can do thi s wi th the
Al i gnment Tool , but fi rst open the Property Edi tor. You can open the Property
Edi tor one of three ways:
Sel ect al l three objects, then doubl e-cl i ck on one of the sel ected objects
Cl i ck on the Property Editor button on the Control Panel
Use the Tools menu on the control l ed fi gure.
Once open, type the l etters pos i n the Property fi el d on the l eft si de of the Edi tor
and the press the Tab key. Command compl eti on puts the word Pos i t i on i n
the Property Fi el d and [ ? ? ? ?] i n the Val ue Fi el d.
Questi on marks are used when mul ti pl e objects are sel ected and the gi ven posi -
ti on val ues for the objects are not equal . You now have the opti on of doi ng one
of two thi ngs to al i gn the sel ected objects to the l eft. You can ei ther repl ace the
fi rst questi on mark i n the Property Edi tor Val ue Fi el d wi th a number or you
can use the Al i gnment Tool .
To use the Al i gnment Tool , open i t from the Control Panel or from the Tools
menu on the control l ed fi gure. Once open, cl i ck on the Align Left button on the
Al i gnment Tool . Press the Apply button and your GUI shoul d now l ook l i ke the
fi gure on the ri ght.
3-19
The three objects are al i gned to the l eft si de of the boundi ng box that encl oses
them.
Next, add the push buttons to the fi gure. Add a push button to the fi gure and
copy i t twi ce. Next, sel ect al l three buttons and l ook at thei r posi ti ons i n the
Property Edi tor. We want thei r wi dths and hei ghts to be equal , so enter
[ ? ? 75 25] i n the val ue fi el d for the Property Edi tor.
This is the
Align Left
button
3-20
Next, we want to al i gn the buttons to the ri ght si de of the axes and di stri bute
the space between the buttons. When fi ni shed, the control l ed fi gure shoul d l ook
l i ke thi s.
Were now done l ayi ng out the fi gure, so acti vate i t and then conti nue to use
the Cal l back Edi tor and Menu Edi tor. To acti vate the fi gure, cl i ck on the Con-
trol l ed Fi gure Li st l i stbox on the Control Panel to get f i gur e #1 to i ndi cate - - >
Act i v e, then press Apply. Make sure to save the fi gure when prompted.
Go back to the Property Edi tor. The root i s now l i sted i n the Object Browser,
al ong wi th any other fi gures that may exi st. Thi s i s because the Gui de tool s are
no l onger l ooki ng at just the l i st of control l ed fi gures; al l graphi cs objects are
vi si bl e to them now.
Our goal i s to put l abel s on the three push buttons and the edi t box and then
to add the stri ng to the l i stbox. Use the Property Edi tor to put the stri ngs
mes h( z ) , s ur f ( z ) , and pcol or ( z ) on the buttons. To add a mul ti l i ne stri ng to
the l i stbox, fi rst create a cel l array i n the base workspace. You can do thi s by
enteri ng
>> maps = {' hs v ' ; ' hot ' ; ' gr ay ' ; ' pr i s m' ; ' cool ' ; ' wi nt er ' ; ' s ummer ' };
at the MATLAB command l i ne. Thi s i s a l i st of just a few of the col ormaps that
are avai l abl e. Next we need to sel ect the St r i ng property for the l i stbox i n the
Property Edi tor. For the val ue, enter the stri ng maps without quotes around it.
Thi s retri eves the vari abl e maps from the workspace. When you appl y thi s
val ue, the edi t fi el d shows the stri ng t owor k, whi ch i s now a vari abl e i n the
All the GUI elements are
in place, so youre ready
to activate the figure.
3-21
workspace equi val ent to the vari abl e maps . t owor k i s used whenever the val ue
for a property has more than one l i ne. The l i stbox now contai ns the correct
stri ng.
Now use the Cal l back Edi tor to assi gn the cal l backs to the push buttons and
l i stbox. The Property Edi tor woul d al so work, but si nce our cal l backs are more
than one l i ne, i ts easi er to use the Cal l back Edi tor. Fi rst, sel ect the l i stbox i n
the Object Browser and then sel ect the Cal l back property.
Enter the cal l back as shown above. The fi rst l i ne of the cal l back gets the val ue
for the current cal l back object, whi ch wi l l be the l i stbox. The second l i ne of the
cal l back gets the l i stboxs stri ng. I t shoul d be noted that the stri ng returned by
The callback:
Val ue = get ( gcbo, ' Val ue' ) ;
St r i ng = get ( gcbo, ' St r i ng' ) ;
col or map( St r i ng{Val ue})
3-22
thi s get command i s a cel l array because i t was entered i nto the l i stbox as a
cel l array. Fi nal l y, set the col ormap of the fi gure to be the current sel ecti on i n
the l i stbox.
Now we want to set the cal l back for al l three push buttons. As before, sel ect the
three push buttons, then sel ect the Cal l back property and then enter the stri ng
as shown bel ow.
Thi s cal l back does the fol l owi ng:
1 Get the pl otti ng command to be executed from the stri ng of the push button.
2 Fi nd the handl e to the edi t box.
3 Get the stri ng from the edi t box.
4 Eval uate the stri ng for the edi t box.
5 Eval uate the pl otti ng command.
The GUI shoul d now be functi oni ng. Before we test i t, go to the File menu on
the fi gure and sel ect Save... You can now test to see that the GUI works.
The l ast step i s to add some menus to the fi gure to al l ow control over the col or
of the fi gure wi th the Menu Edi tor. Open the Menu Edi tor, sel ect the fi gure i n
the Object Browser and cl i ck on New Menu. Enter ' Opt i ons ' for the Label for
The callback:
CommandSt r i ng = get ( gcbo, ' St r i ng' ) ;
Edi t Handl e = f i ndobj ( gcbf , ' Tag' , ' edi t ' ) ;
ZSt r i ng = get ( Edi t Handl e, ' St r i ng' ) ;
ev al ( ZSt r i ng) ;
ev al ( CommandSt r i ng) ;
3-23
the menu and then cl i ck on New Menu agai n to pl ace a sub-menu bel ow the
Options menu.
Label thi s menu Col or and then cl i ck on New Menu a thi rd ti me. Thi s new
menu has a Label of ' whi t e' and a cal l back of
' s et ( gcbf , ' ' Col or ' ' , ' ' whi t e' ' ) ' .
3-24
You can now add addi ti onal menus as desi red. Agai n save the fi gure and test
out your GUI . The fi nal resul t shoul d be si mi l ar to the fi gure bel ow.
W riting C allbacks
3-25
Writing Callbacks
Layout vs. Callbacks
Just as bui l di ng GUI s di vi des i nto desi gn and i mpl ementati on, so does the
i mpl ementati on part di vi de i nto screen l ayout (typi cal l y usi ng Gui de) and cal l -
back handl i ng. Thi s i s the di fference between how the screen l ooks versus what
i t does when you i nteract wi th i t.
Happi l y, usi ng Gui de means that youl l never agai n have to wri te code that
l ooks l i ke thi s:
ui cont r ol ( ' St y l e' , ' pus hbut t on' , . . .
' St r i ng' , ' Pl ot ' , . . .
' Cal l back' , ' pl ot ( x , y ) ' , . . .
' Uni t s ' , ' poi nt ' , . . .
' Pos i t i on' , [ 50 65 75 35] )
I n other words, i ts possi bl e that Gui de i s al l you need to bui l d your GUI , but
chances are you need to wri te some more support code. Usi ng Gui de, you keep
al l your l ayout changes i n the fi gure fi l e. Thi s i s ni ce because i t separates the
graphi c desi gn part of bui l di ng the GUI from the cal l back codi ng part.
Callback Tips
As part of your GUI desi gn, you typi cal l y produce a good descri pti on of how the
GUI shoul d behave. Even i f you have experi ence codi ng i n MATLAB, i t can sti l l
be tri cky to get the cal l backs worki ng robustl y and effi ci entl y I n thi s secti on,
we wal k through a col l ecti on of cal l back codi ng ti ps that you mi ght use i n your
GUI s.
pl ot ( x , y )
Callback
Load
l oad my dat a;
x =XYDat a( : , 1) ;
y =XYDat a( : , 2) ;
Callback
Plot
cl os e( gcbf )
Callback
Close
Guide helps
you put all the
elements in
place
You still need to
manage what
happens when
the button gets
pushed
La y out
Ca l l b a ck s
Figure 1
3-26
Function Callbacks Are Faster Cal l backs that consi st of l ong stri ngs to eval -
uate execute more sl owl y than cal l backs that are short functi on names.
The code that you put i n the cal l back stri ng for any ui control gets eval uated
when that ui control i s acti vated. You can put a l ong stri ng of commands
di rectl y i nto the cal l back. For i nstance, suppose you have a mi ni -GUI that
l oads some data (my dat a. mat ) i nto the workspace, then pl ots i t, as shown i n the
previ ous fi gure.
For speed, robustness, and ease of codi ng, you shoul d make al l of your cal l backs
functi ons. The code i s faster because functi ons, once l oaded and compi l ed by
the i nterpreter, run much faster, whereas the eval uated stri ngs get parsed
anew every ti me. The code i s easier to read and write because you dont have to
doubl e up quotes (though the Cal l back Edi tor al l evi ates the need to doubl e up
quotes). The code i s more robust because i t executes i n the functi ons work-
space, as opposed to the cal l back stri ng, whi ch gets executed di rectl y i n the
base workspace where i t can col l i de wi th other data. I n thi s exampl e, XYDat a
gets deposi ted i n the workspace every ti me you push the button. Here i s the
same appl i cati on wi th functi onal cal l backs.
Noti ce we have to modi fy the cal l backs to handl e the workspace i ssue. I n the
functi ons workspace, we cant si mpl y say pl ot ( x , y ) , because the functi on
doesnt know what x and y are. One way to deal wi th thi s i s to store the data i n
the Us er Dat a property of the fi gure for l ater retri eval , as shown here.
my pl ot f cn
Callback
my l oadf cn
Callback
Load
Plot
my cl os ef cn
Callback
Close
f unct i on my l oadf cn
l oad my dat a;
s et ( gcbf , ' Us er Dat a' , XYDat a)
Function on disk
f unct i on my cl os ef cn
cl os e( gcbf )
Function on disk
f unct i on my pl ot f cn
XYDat a=get ( gcbf , ' Us er Dat a' )
x =XYDat a( : , 1) ;
y =XYDat a( : , 2) ;
pl ot ( x , y )
Function on disk
Figure 1
W riting C allbacks
3-27
Switchyard Programming Prevents Function Proliferation Send al l the cal l -
backs of your GUI to one si ngl e functi on wi th a s wi t ch statement so there
wont be a separate functi on for every cal l back.
Separate functi ons for each cal l back can l ead to a l ot of fi l es to support one
GUI . For reasons of mai ntai nabi l i ty and ease-of-codi ng, were better off putti ng
al l those i nto a si ngl e functi on as shown bel ow. Thi s approach, known as
switchyard programming, keeps al l the code associ ated wi th fi gure cal l backs i n
one central i zed pl ace. I f your GUI uses one fi gure fi l e (and i ts associ ated
MAT-fi l e) and one cal l back functi on l i ke the one bel ow, you need to keep track
of onl y three fi l es per GUI .
Use gcbo and gcbf for Self-Referential Callbacks I f your cal l back needs to
know about or modi fy i ts own state or the state of i ts parent gure, the func-
ti ons gcbo and gcbf are short and conveni ent.
There are several speci al handl es that make wri ti ng cal l backs much easi er.
They al l i nvol ve grabbi ng the current handl e of a certai n type: gcbf (Get Cal l -
back Fi gure), gca (Get Current Axes), gcbo (Get Cal l back Object). These are al l
my gui pl ot
Callback
my gui l oad
Callback
Load
Plot
my gui cl os e
Callback
Close
f unct i on my gui ( act i on)
s wi t ch( act i on)
cas e ' l oad' ,
l oad my dat a;
cas e ' pl ot '
x =XYDat a( : , 1) ;
y =XYDat a( : , 2) ;
pl ot ( x , y )
cas e ' cl os e'
cl os e( gcbf )
end
Function on disk
Figure 1
3-28
si mpl e functi ons that use the Handl e Graphi cs hi erarchy to grab the correct
handl e. Try thi s:
Thi s button has a cal l back that makes i ts own stri ng equal the ti me of day. You
can thi nk of the gcbo functi on as bei ng l oosel y transl ated to me. So i n thi s
exampl e the button i s sayi ng: when I get cl i cked, make my l abel equal to the
ti me of day. The dat es t r functi on, operati ng on the output of the now com-
mand, has many formatti ng opti ons, and opti on 14 corresponds to HH:MM:SS
PM.
Stateless Programming with ndobj I f you use the f i ndobj functi on to l ocate
an object whenever you need to modi fy i t, you can often el i mi nate the need for
redundant state vari abl es.
The command f i ndobj returns the handl e of an object that matches the
descri pti on (a l i st of property name/property val ue pai rs) you gi ve i t. Si nce f i n-
dobj al l ows you to fi nd any object i n the enti re Handl e Graphi cs hi erarchy
qui ckl y and easi l y, you can nd the handl e associ ated wi th a l i ne, for exampl e,
onl y when you need i t, rather than havi ng to remember i t from the moment you
created i t. Heres the ol d way of deal i ng wi th handl es:
l i neHandl e = pl ot ( r and( 10, 1) )
% Remember t hat handl e!
. . . [ l ot s of ot her code her e] . . .
s et ( l i neHandl e, ' Li neWi dt h' , 4, ' Col or ' , ' r ed' )
I f the handl e gets l ost, cl eared, or goes out of scope between the fi rst statement
and the l ast, then you ei ther cause an error or you must regenerate the pl ot
from scratch. There are several strategi es we mi ght use to keep from l osi ng
s et ( gcbo, ' St r i ng' , dat es t r ( now, 14) ) ;
Callback
Figure 1
10:49:52 AM
Figure 1
click
10:47:18 AM
Self-referential callbacks:
An objects callback can
be used to modify the
object itself.
W riting C allbacks
3-29
track of l i neHndl , but they al l have drawbacks. You can usea gl obal vari abl e
(though thi s i s di scouraged) or you can store the handl e i n Us er Dat a some-
where i n the fi gure. Al l of these mean keepi ng track of redundant state. I n
addi ti on, the handl e may change i f the fi gure i s stored and rel oaded, and i f you
use saved fi gure fi l es, then you dont have access to the object handl es at cre-
ati on ti me.
Heres how the same exampl e works wi th f i ndobj .
pl ot ( r and( 10, 1) , ' Tag' , ' My Li ne' )
% Don' t ev en bot her wi t h t he handl e y et ; j us t gi v e i t a Tag
. . . [ l ot s of ot her code her e] . . .
l i neHandl e = f i ndobj ( ' Tag' , ' My Li ne' ) ;
s et ( l i neHandl e, ' Li neWi dt h' , 4, ' Col or ' , ' r ed' )
You can use f i ndobj to search for any property name/property val ue combi na-
ti on, but the Tag property i s general l y the easi est one to use. You can thi nk of
the Tag fi el d as an i nvari ant handl e that you get to desi gnate. I n the exampl e
bel ow, the buttons cal l back needs to determi ne the state of the checkbox before
i t can fi ni sh i ts work. Thi s i s an good exampl e of when f i ndobj i s useful .
One word of warni ng concerni ng f i ndobj : si nce f i ndobj searches through the
object hi erarchy every ti me i ts cal l ed, you may fi nd i t too sl ow for some pur-
poses. I n cases where speed i s essenti al (such as Wi ndowBut t onMot i on l oops,
whi ch are di scussed l ater i n thi s secti on), you may want to store handl es i n the
fi gures Us er Dat a or i n gl obal vari abl es.
gr i dHndl =f i ndobj ( gcbf , . . .
' Tag' , ' Gr i dFl ag' ) ;
pl ot ( x , y ) ;
i f get ( gr i dHndl , ' Val ue' ) ,
gr i d on;
el s e
gr i d of f ;
end
Callback
Gr i dFl ag
Tag
Plot
Grid On
Figure 1
X
click
Here the button is
modifying its action
based on a setting
somewhere else in
the figure (the grid
check box)
3-30
Avoid Potential Errors by Disabling Uicontrols I f a cal l back i s l i kel y to cause
an error i f i nvoked at a certai n ti me, set the Enabl e property on the cal l i ng
object to of f .
I n the exampl e bel ow, the top button l oads the data, and the mi ddl e button
pl ots i t. I f the mi ddl e button i s cl i cked on fi rst, an error resul ts, because the
data wi l l not yet be i n the UserData. Avoi d thi s probl em by di sabl i ng the Plot
button i ni ti al l y (set i ts Enabl e property to of f ), and then usi ng the Load
buttons cal l back to re-enabl e i t.
Use Subfunctions Inside the Switchyard Callback Another good way to keep
the cal l back functi on cl ean i s to route common functi onal i ty i nto a subfuncti on
i n the same l e.
I n thi s exampl e, weve deci ded we want to pl ot at two di fferent ti mes, both
when the Plot button i s pushed, and when the data i s l oaded by the Load
button. Rather than dupl i cate the code, we just create a new functi on i n the
same fi l e cal l ed Local Pl ot Fcn. Thi s functi on i s then executed i n each buttons
my pl ot f cn
Callback
my l oadf cn
Callback
Load
of f
Enable
Plot
my cl os ef cn
Callback
Close
f unct i on my l oadf cn
l oad my dat a;
pl ot Hndl =f i ndobj ( gcbf , . . .
' St r i ng' , ' Pl ot ' ) ;
s et ( pl ot Hndl , ' Enabl e' , ' on' )
Function on disk
f unct i on my cl os ef cn
cl os e( gcbf )
Function on disk
f unct i on my pl ot f cn
x =XYDat a( : , 1) ;
y =XYDat a( : , 2) ;
pl ot ( x , y )
Function on disk
Figure 1
W riting C allbacks
3-31
cal l back. As the compl exi ty of your cal l back functi on ri ses, thi s ki nd of thi ng
becomes very val uabl e.
Dont Forget About the ButtonDownFcn Everythi ng from a l i ne to a gure
has a But t onDownFcn. Use these and other speci al cal l back functi ons to gi ve
your GUI more l everage.
Cal l backs from ui control s are not the onl y way to run code from a GUI . Maki ng
appropri ate But t onDownFcns for l i nes, text, and axes i n your GUI i s one of the
most powerful ways to make i t i nteracti ve. I t al so al l evi ates the need for l ots
and l ots of ui control s.
my gui pl ot
Callback
my gui l oad
Callback
Load
Plot
my gui cl os e
Callback
Close
f unct i on my gui ( act i on)
cas e ' l oad' ,
l oad my dat a;
Local Pl ot Fcn
cas e ' pl ot '
Local Pl ot Fcn
cas e ' cl os e'
cl os e( gcbf )
end
f unct i on Local Pl ot Fcn
% Thi s i s a s ubf unct i on
x =XYDat a( : , 1) ;
y =XYDat a( : , 2) ;
pl ot ( x , y )
Function on disk
Figure 1
s et ( gcbo, ' Li neWi dt h' , 10- get ( gcbo, ' Li neWi dt h' ) )
ButtonDownFcn
Figure 1 Figure 1
click
Figure 1
click
Use the ButtonDownFcn
to toggle the
LineWidth on a
line.
3-32
The fi gure has a number of event functi ons speci fi c to i t, i ncl udi ng the
Res i z eFcn and the Key Pr es s Fcn. Use the Cal l back Edi tor to browse around
and see what cal l back functi ons are associ ated wi th what objects.
Prevent Overplotting with Handle Visibility The Handl eVi s i bi l i t y property
l ets your hi de your GUI from the MATLAB command l i ne so i t cant be tam-
pered wi th.
The Handl eVi s i bi l i t y property (wi th val ue setti ngs on, of f , and cal l back)
has been added so that regul ar pl otti ng commands act as though an object
doesnt exi st.
>> pl ot ( x , y )
of f
HandleVisibility
on
HandleVisibility
Command Window
Figure 1
Figure 2
If there is something
in this figure that you
dont want overwritten,
turn off its Handle
Visibility
W riting C allbacks
3-33
Pl otti ng commands i ssued from cal l backs arent aware of thei r own fi gures i f
the fi gures Handl eVi s i bi l i t y i s of f .
Thi s can be a probl em when youre worki ng on a GUI , si nce the GUI needs to
see i tsel f, so a thi rd val ue, cal l back, exi sts. Pl otti ng commands i ssued from the
Command Wi ndow, for exampl e, wont overwri te the fi gure when
Handl eVi s i bi l i t y i s cal l back. But any commands i ni ti ated by the cal l backs
of the fi gure i tsel f see the fi gure.
I f you set the Handl eVi s i bi l i t y of a fi gure to of f or cal l back, you can no
l onger see i t from the command l i ne. Thi s means you cant cl ose i t wi th the
cl os e command or pl ot i nto i t wi th the pl ot command. How do you cl ose a
hi dden fi gure? There i s an opti on bui l t i nto the cl os e functi on that l ets you
cl ose everythi ng, whether hi dden or not: cl os e hi dden.
of f
HandleVisibility
pl ot ( x , y )
Callback
on
HandleVisibility
Plot
Figure 1
Figure 2
cal l back
HandleVisibility
pl ot ( x , y )
Callback
Plot
Figure 1
>> pl ot ( x , y )
on
HandleVisibility
Command Window
click Figure 2
When the figures
HandleVisibility is
set to callback, you
can see it fromany
callback, but not
fromthe Command
Window.
3-34
Animate with WindowButtonMotionFcn To ani mate a response as the mouse
is being dragged, use a combi nati on of the cal l back functi ons
Wi ndowBut t onDownFcn, Wi ndowBut t onMot i onFcn, and Wi ndowBut t onUpFcn.
One of the ni fti er thi ngs to do wi th a MATLAB GUI i s ani mate a cal cul ati on on
the y. To do thi s, you need a functi on that gets cal l ed whi l e the mouse i s
movi ng across the screen. Thi s gets a l i ttl e tri cky, but the di agram bel ow
expl ai ns the si tuati on. Lets say we want to cl i ck, drag, and rel ease a dot on a
fi gure wi ndow. When we cl i ck down on the dot (a l i ne wi th a si ngl e poi nt, to be
speci fi c), we need to pi ck up the coordi nates of the mouse and set the posi ti on
of the dot accordi ngl y.
We can do exactl y thi s wi th the fi gure property Wi ndowBut t onMot i onFcn. But
the moti on functi on can onl y be acti ve when the mouse button is down.
ani mat or s t ar t
ButtonDownFcn
x or
EraseMode
Figure 1 Figure 1
click,
drag...
Figure 1
...drag,
release
[ empt y]
WindowButtonMotionFcn
[ empt y]
WindowButtonUpFcn
ani mat or mov e
ani mat or s t op
WindowButtonUpFcn
[ empt y]
[ empt y]
WindowButtonUpFcn
f unct i on ani mat or ( act i on)
cas e ' s t ar t ' ,
s et ( gcbf , ' Wi ndowBut t onMot i onFcn' , ' ani mat or mov e' )
s et ( gcbf , ' Wi ndowBut t onUpFcn' , ' ani mat or s t op' )
cas e ' mov e'
cur r Pt =get ( gca, ' Cur r ent Poi nt ' ) ;
s et ( gcbo, ' XDat a' , cur r Pt ( 1, 1) )
s et ( gcbo, ' YDat a' , cur r Pt ( 1, 2) )
cas e ' s t op'
s et ( gcbf , ' Wi ndowBut t onMot i onFcn' , ' ' )
s et ( gcbf , ' Wi ndowBut t onUpFcn' , ' ' )
end
Function on disk
A C om plete Exam ple: Tem perature C onversion
3-35
A Complete Example: Temperature Conversion
Lets consi der a GUI that converts the temperature from Cel si us to Fahrenhei t,
and vi ce versa. We assume that weve al ready gone through the careful desi gn
process from the l ast chapter, and now we want to bui l d the cal l backs i nto the
GUI . Thi s i s what a drawi ng of our desi gn l ooks l i ke:
Heres how i t works. You can enter a temperature i n degrees Fahrenhei t i n the
edi tabl e text fi el d on the l eft (Cal l back = cel s i us f ahr enhei t t ex t ), or a tem-
perature i n degrees Cel si us i n the edi tabl e text fi el d on the ri ght (Cal l back =
cel s i us cel s i us t ex t ). I n ei ther case, the cal l back functi on takes the temper-
ature i n one set of uni ts, converts i t to the other usi ng the equati on
T
cel si us
= ( 5/9) ( T
fahrenhei t
- 32)
then sets the l ength of the red l i ne and the other text fi el d. I n addi ti on, i f you
cl i ck on the red l i ne i n the mi ddl e axes, you ani mate the red l i ne i n the ther-
mometer and update the text fi el ds.
t emper at ur e cel s i us t ex t
Callback
37.0
Degrees
Celsius
98.6
Degrees
Fahrenheit
cel s i us t ex t
Tag
t emper at ur e f ahr enhei t t ex t
Callback
f ahr enhei t t ex t
Tag
t emper at ur e s t ar t
ButtonDownFcn
r edl i ne
Tag
f unct i on t emper at ur e( act i on)
cas e ' s t ar t ' ,
. . .
cas e ' mov e' ,
. . .
cas e ' s t op' ,
. . .
cas e ' cel s i us t ex t ' ,
. . .
cas e ' f ahr enhei t t ex t ' ,
. . .
end
Function on disk
Figure 1
3-36
After worki ng wi th Gui de, we end up wi th the fol l owi ng screen and save i t to
the fi gure fi l e t emper at ur ef i g. m.
And heres what the code l ooks l i ke that makes the GUI work.
This center region is
actually three different
axesthe one in the
middle has the animation
ButtonDownFcn.
A C om plete Exam ple: Tem perature C onversion
3-37
f unct i on t emper at ur e( act i on)
% Thi s i s t he cal l back f unct i on f or t he t emper at ur e conv er s i on f unct i on
s wi t ch act i on

cas e ' s t ar t '
s et ( gcbf , ' Wi ndowBut t onMot i onFcn' , ' t emper at ur e mov e' )
s et ( gcbf , ' Wi ndowBut t onUpFcn' , ' t emper at ur e s t op' )
t emper at ur e mov e

cas e ' mov e'
cur r ent Poi nt = get ( gca, ' Cur r ent Poi nt ' ) ;
newY = cur r ent Poi nt ( 3) ;
% Li mi t t he endpoi nt s of t he mot i on and s et t he poi nt er
f ah = mi n( 240, max ( - 40, newY) ) ;
cel s = ( f ah- 32) *( 5/9) ;

% Set t he t ex t s t r i ngs pr oper l y
Local Set Di s pl ay ( f ah, cel s )

cas e ' s t op'
s et ( gcbf , ' Wi ndowBut t onMot i onFcn' , ' ' )
s et ( gcbf , ' Wi ndowBut t onUpFcn' , ' ' )

cas e ' f ahr enhei t '
f ah = ev al ( get ( gcbo, ' St r i ng' ) ) ;
f ah = mi n( 240, max ( - 40, f ah) ) ;
cel s = ( f ah- 32) *( 5/9) ;

cas e ' cel s i us '
cel s = ev al ( get ( gcbo, ' St r i ng' ) ) ;
cel s = mi n( 120, max ( - 40, cel s ) ) ;
f ah = cel s *( 9/5) +32;

end
f unct i on Local Set Di s pl ay ( f ah, cel s )
% Set t he t ex t s t r i ngs pr oper l y
poi nt er Handl e = f i ndobj ( gcbf , ' Tag' , ' r edl i ne' ) ;
s et ( poi nt er Handl e, ' YDat a' , [ - 40 f ah] )
f ahHndl = f i ndobj ( gcbf , ' Tag' , ' f ahr enhei t t ex t ' ) ;
s et ( f ahHndl , ' St r i ng' , s pr i nt f ( ' %3. 1f ' , f ah) )
cel s Hndl = f i ndobj ( gcbf , ' Tag' , ' cel s i us t ex t ' ) ;
s et ( cel s Hndl , ' St r i ng' , s pr i nt f ( ' %3. 1f ' , cel s ) )
Heres one of the calls
to the subfunction
This is the subfunction
for filling the Celsius and
Fahrenheit text fields
The start, move,
and stop calls are
for animating the
red line
3-38

4
Reference
align
4-2
al i gn
Purpose Al i gn ui control s and axes.
Syntax al i gn
al i gn( Handl eLi st )
al i gn( Handl eLi s t , Hor i zont al Al i gnment , Ver t i cal Al i gnment )
Pos i t i ons =
al i gn( Handl eLi s t , Hor i zont al Al i gnment , Ver t i cal Al i gnment )
Pos i t i ons =
al i gn( Cur Pos i t i ons , Hor i zont al Al i gnment , Ver t i cal Al i gnment )
Description al i gn bri ngs up an al i gnment tool to i nteracti vel y al i gn ui control s and axes.
al i gn( Handl eLi s t ) al i gns the handl es speci fi ed i n Handl eLi st. Cal l i ng the
tool as al i gn( Handl eLi s t , Hor i zont al Al i gnment , Ver t i cal Al i gnment ) auto-
mati cal l y al i gns the objects i n the handl e l i st wi thout openi ng the al i gnment
tool . Addi ng a l eft hand argument to thi s cal l i ng syntax causes the updated
posi ti ons of the objects to be returned whi l e the posi ti on of the objects on the
fi gure does not change. Fi nal l y, cal l i ng the al i gnment tool wi th
Pos i t i ons =al i gn( Cur Pos i t i ons , Hor i zont al Al i gnment ,
Ver t i cal Al i gnment ) returns the updated posi ti on matri x from the i ni ti al posi -
ti on matri x wi thout openi ng the al i gnment tool .
Possi bl e val ues for Hor i zont al Al i gnment are: None, Lef t , Cent er , Ri ght ,
Di s t r i but e, and Fi x ed.
Possi bl e val ues for Ver t i cal Al i gnment are: None, Top, Mi ddl e, Bot t om,
Di s t r i but e, and Fi x ed. Al l al i gnment opti ons wi l l al i gn the objects wi thi n the
boundi ng box that encl oses the objects.
Di s t r i but e and Fi x ed wi l l al i gn objects to the bottom l eft of the boundi ng box.
Di s t r i but e evenl y di stri butes the objects whi l e Fi x ed di stri butes the objects
wi th a fi xed di stance (i n poi nts) between them. I f Fi x ed i s used for
Hor i zont al Al i gnment or Ver t i cal Al i gnment , then the di stance must be
passed i n as an extra argument: al i gn( Handl eLi s t ,
align
4-3
Hor i zont al Al i gnment , Di s t ance, Ver t i cal Al i gnment ) or al i gn
( Handl eLi s t , Hor i zont al Al i gnment , Ver t i cal Al i gnment , Di s t ance) .
The top of the Al i gnment Tool contai ns an Object Browser that l i sts al l ui con-
trol s and axes that can be al i gned. Underneath the Object Browser are the
al i gnment control s. Objects can be al i gned to each other i n both hori zontal and
verti cal di recti ons. The al i gnment takes pl ace i n the boundi ng box contai ni ng
al l of the objects. Objects can al so be di stri buted wi th respect to each other such
that the spaci ng between each object i s equal . Fi nal l y, objects can have a set
spaci ng pl aced between them. The spaci ng opti on starts wi th the object i n the
l ower l eft corner and works i ts way up and ri ght. Thi s i s the onl y type of al i gn-
ment that does not pay attenti on to the boundi ng box that contai ns the objects.
There must be more than one object sel ected i n order for the al i gnment tool to
work.
See Also gui de, cbedi t , menuedi t , pr opedi t , Object Browser, Control l ed Fi gure
cbedit
4-4
cbedi t
Purpose Edi t cal l back.
Syntax cbedi t
cbedi t ( Handl eLi s t )
Description cbedi t i nteracti vel y edi ts cal l back stri ngs for a sel ected object. cbedi t
( Handl eLi s t ) edi ts the properti es for the object(s) i n Handl eLi s t . I f Han-
dl eLi s t i s a vector, onl y si mi l ar object properti es are l i sted.
The Cal l back Edi tor al l ows cal l back type properti es to be modi fi ed by enteri ng
them just as they woul d be entered from the command l i ne. Si mi l ar to the Prop-
erty Edi tor, the top of the Cal l back Edi tor contai ns ei ther the currentl y
sel ected object(s)' Type and Tag or i t contai ns an Object Browser. Bel ow thi s
l i es the l i st of properti es that can be modi fi ed. The property i s the current val ue
of that property.
See Also gui de, al i gn, menuedi t , pr opedi t , Object Browser, Control l ed Fi gure
Controlled Figure
4-5
Control l ed Fi gure
Description A Control l ed fi gure i s a fi gure that has been put i nto an edi tabl e state by the
Gui de Control Panel . When a fi gure i s control l ed, objects may be sel ected,
moved, resi zed, or edi ted i nteracti vel y. The fi gures menus are hi dden from
vi ew and a set of menus rel ated to Gui de are i nserted i n thei r pl ace. To vi ew
the stored menus, acti vate the fi gure. When a fi gure i s control l ed, a whi te gri d
that covers the enti re fi gure i s present.
See Also gui de, al i gn, cbedi t , ct l panel , menuedi t ,pr opedi t , Object Browser
ctlpanel
4-6
ctl panel
Purpose Gui de control panel .
Syntax ct l panel
ct l panel ( Handl eLi s t )
Description ct l panel i s the i ni ti al i zati on functi on for the Gui de Control Panel .
ct l panel ( Handl el i s t ) i ni ti al i zes al l tool s to the fi gure(s) contai ni ng al l han-
dl es i n the Handl eLi s t .
See Also gui de, al i gn, cbedi t , menuedi t , pr opedi t , Object Browser, Control l ed Fi gure
guide
4-7
gui de
Purpose Gui de Control Panel .
Syntax gui de
gui de( Handl eLi s t )
Description gui de i ni ti ates the GUI Desi gn Envi ronment tool s that al l ow Handl e Graphi cs
objects to be mani pul ated i nteracti vel y. Cal l i ng gui de by i tsel f wi l l open the
Control Panel i f i t i s not open al ready and update al l other Gui de tool s that may
al ready be open. Al l tool s are updated to use the current fi gure. gui de
( Handl el i s t ) i ni ti al i zes al l tool s to the fi gure(s) contai ni ng al l handl es i n the
Handl eLi s t .
See Also al i gn, cbedi t , ct l panel , menuedi t , pr opedi t , Object Browser, Control l ed
Fi gure
helpwin
4-8
hel pwi n
Purpose On-l i ne hel p
Syntax hel pwi n t opi c
Description hel pwi n t opi c opens a hel p wi ndow and di spl ays the hel p text for the gi ven
t opi c. Li nks are created to functi ons referenced i n the See Al so l i ne of the
hel p text.
hel pwi n( hel p_s t r , t i t l e) di spl ays the stri ng HELP_STR i n the hel p wi ndow.
hel p_s t r can be passed i n as a stri ng wi th each l i ne separated by carri age
returns, a col umn vector cel l array of stri ngs wi th each cel l (row) representi ng
a l i ne, or a stri ng matri x wi th each row representi ng a l i ne. The opti onal stri ng
t i t l e appears i n the ti tl e edi t box.
hel pwi n( {t i t l e1 hel p_s t r 1; t i t l e2 hel p_s t r 2; . . . }, page) di spl ays one
page of mul ti page hel p text. The mul ti page hel p text i s passed i n as a cel l array
of stri ngs or cel l s contai ni ng t i t l e and hel p_s t r pai rs. Each row of the mul ti -
page hel p text cel l array (di mensi oned number of pages by 2) consi sts of a ti tl e
stri ng pai red wi th a stri ng, cel l array or stri ng matri x of hel p text. The second
argument page i s a stri ng that must match one of the t i t l e entri es i n the mul -
ti page hel p text.The matchi ng t i t l e represents the page that i s to be di spl ayed
fi rst. I f no second argument i s gi ven, the fi rst page i s di spl ayed.
helpwin
4-9
A thi rd argument can be passed to hel pwi n, whi ch i s a stri ng that becomes the
ti tl e of the hel p wi ndow fi gure.
Addi ti onal arguments, after the wi ndow ti tl e, are i nterpreted as Handl e
Graphi cs parameter-val ue pai rs to be appl i ed to the text di spl ayed i n the hel p
wi ndow.
Examples hel pwi n pl ot
hel pwi n( ' Hel p St r i ng' , ' t i t l e' )
hel pwi n( [ ' Hel p t ex t f or ' s pr i nt f ( ' \n' ) ' my m- f i l e. ' ] , ' t i t l e' )
hel pwi n( {' Hel p St r i ng f or ' ; ' my m- f i l e' }, ' t i t l e' )
s t r = { ' Topi c 1' ' Hel p s t r i ng f or Topi c 1' ;
' Topi c 2' ' Hel p s t r i ng f or Topi c 2' ;
' Topi c 3' ' Hel p s t r i ng f or Topi c 3' }
hel pwi n( s t r , ' Topi c 2' , ' My Ti t l e' )
See Also doc, docopt , hel p, web
menuedit
4-10
menuedi t
Purpose Edi t menu.
Syntax menuedi t
menuedi t ( Handl el i s t )
Description menuedi t al l ows the menus on fi gures to be edi ted i nteracti vel y.
menuedi t ( Handl el i s t ) sel ects al l objects i n Handl eLi s t .
The Menu Edi tor al l ows the menus on fi gures to be i nteracti vel y modi fi ed.
Menus can be moved up and down i n the hi erarchy through the use of the
arrow buttons on the l eft hand si de of the tool . The Label , Tag, and Cal l back
properti es can be modi fi ed di rectl y on the tool . Al l other properti es shoul d be
menuedit
4-11
modi fi ed wi th the Property Edi tor or the Cal l back Edi tor. To vi ew menus that
are on a control l ed fi gure, the fi gure must be acti vated.
See Also gui de, al i gn, cbedi t , ct l panel , pr opedi t , Object Browser, Control l ed Fi gure
Object Browser
4-12
Object Browser
Description The Object Browser on the Gui de tool s al l ows objects to be sel ected i nterac-
ti vel y regardl ess of whether or not a control l ed fi gure exi sts. I f any control l ed
fi gures exi st, onl y control l ed fi gures and thei r chi l dren appear i n the Object
Browser. I f no fi gures are control l ed, then al l objects from Root down appear.
There are three di fferent Object Browsers. The Property Edi tor and the Cal l -
back Edi tor show al l objects. The Menu Edi tor onl y shows fi gures and ui menus.
The Al i gnment Tool onl y shows fi gures, ui control s and axes. Sel ecti ng an object
on any one of the tool s al so sel ects that object on al l other tool s. There are four
col umns i n the Object Browser. The fi rst col umn contai ns +, -, or nothi ng
at al l . A + i ndi cates that the object has chi l dren and can be expanded. A -
i ndi cates the object has chi l dren and has al ready been expanded and a bl ank
i ndi cates the object has no chi l dren. The second col umn contai ns the object
type. The thi rd col umn contai ns suppl emental i nformati on and shoul d hel p i n
determi ni ng what object i s sel ected. Fi nal l y the l ast col umn contai ns the tag of
the sel ected object.
Example The fol l owi ng i s an exampl e of an Object Browser when no fi gures are bei ng
control l ed.
See Also gui de, al i gn, cbedi t , ct l panel , menuedi t , pr opedi t , Control l ed Fi gure
propedit
4-13
propedi t
Purpose Edi t property.
Syntax pr opedi t
pr opedi t ( Handl eLi s t )
Description pr opedi t edi ts al l properti es of any sel ected object through the use of a graph-
i cal i nterface. pr opedi t ( Handl eLi s t ) edi ts the properti es for the object(s) i n
Handl eLi s t . I f Handl eLi s t i s a vector, onl y si mi l ar object properti es are l i sted.
The Property Edi tor al l ows object properti es to be modi fi ed i nteracti vel y. The
top of the Property Edi tor shows ei ther the currentl y sel ected objects type and
that objects tag or i t shows the Object Browser. Bel ow thi s l i es the current
property and the val ue of that property. When changi ng properti es, i t i s not
necessary to enter the enti re property name but rather just enough to uni quel y
i denti fy the property. Bel ow the current property, i f open, i s the l i st of al l avai l -
propedit
4-14
abl e properti es for the gi ven object(s) and the correspondi ng val ue of each of
those properti es.
See Also gui de, al i gn, cbedi t , ct l panel , menuedi t , Object Browser, Control l ed Fi gure
I-1
I ndex
A
acti vati ng a fi gure 3-11
al i gn 3-10
Al i gnment tool 3-14
B
But t onDownFcn 3-31
C
Cal l back Edi tor 3-12
cal l backs 2-14
cbedi t 3-10, 3-13
cl os e hi dden command 3-33
col ormaps 3-20
Control Panel 3-10
control l i ng a fi gure 3-11
D
desi gn pri nci pl es 2-3
desi gn process 2-12
E
Enabl e property 3-30
F
f i ndobj 3-28
G
gca 3-27
gcbf 3-27
gcbo 3-27
gui de 3-10
Gui de tool l i st 3-10
Gui de-control l ed fi gure l i st 3-10
H
Handl e Graphi cs 3-2, 3-3
M
Menu Edi tor 3-15
MenuBar property 3-15
menuedi t 3-10
N
new object pal ette 3-10
O
Object Browser 3-5
P
paper prototypi ng 2-13
preci pi tati on fi l es exampl e 2-15
pr opedi t 3-10
Property Edi tor 1-4, 3-3
Property l i st 3-4
S
subfuncti ons 3-30
s wi t ch statement 3-27
swi tchyard programmi ng 3-27
Index
I-2
T
t owor k stri ng 3-20
V
Vi s i bl e property 3-5
W
weather data 2-15

(Ebook) Engineering - Building Gui With Matlab

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

(Ebook) Engineering - Building Gui With Matlab

Uploaded by

Copyright:

Available Formats

M

You might also like