The functions described on this page offer an extraordinary easy access for every MATLAB user to produce comfortable user interaction in any MATLAB program. Its possibilities are unlimited, its use idiot proof. Virtually no programming is required to use it; certainly no knowledge about programming is required to understand it. It uses MATLAB classes but hides them from the user.
All functions described here can also be constructed using GUIDE, but with considerable more time and pain... Furthermore the result are less reusable, transferable or readable.
Imagine you want to call a function with a couple of parameters. You don't want to type each parameter in the command line every time and want to make your function usable to others and give it a nice graphical user interface that everybody can understand. Here is the solution! The following example shows how the parameter class makes live easy for you from now on!
First follow the download and installation instructions here. Then download the following function (example1) to a file called example1.m and execute it:
call the function by typing "example1" (without parameters)
A window pops up that looks like:
figure: The gui that appears on the screen executing example1
In the actual source code exactly 10 lines are necessary to define this GUI and bring it on the screen. The user interaction form now on is very simple by only one command: get
Pressing the 'draw' button now plots a circle with the radius ~1 cm (not exactly,
for demonstration purposes only. The actual size depends on your screen resolution).
Try to change the radius or the shape from the gui and redraw them. The tick
box "hold
on" determines if the figure is cleared before drawing. Try also a negative
radius. Playing in it with three times pressing the "draw" button with
different shapes results for example in the following picture:
figure: example output from the gui above
MATLAB input/output is plotted in Courier
function names are plotted bold
names that can be freely defined are in blue.
identifying strings are red
units are green
figure: filecontent after unpacking the zip file
parameters needs MATLAB 7.0
An object of the class parameter is created by calling:
a=parameter;
or with a name:
params=parameter('some parameter');
All the examples for parameter types work by adding them to a parameter object and calling the gui. Since that is always the same it is only shown once:
params=parameter
params=add(params,something(see below)) <- substitute by any example below
parametergui(params);
parameter types can be one of the following:
| float | a floating point variable with a unit |
| slider | a floating point variable with a unit and a slider connected to it |
| int | an integer value. |
| string | a string value |
| bool | a checkbox with values either zero or one |
| panel | a grey rectangle that collects a number of items together |
| radiobutton | a radiobutton is one of several buttons in a box. |
| pop-up menu | pop-up menu that allows the choice between different strings |
| filename | a string and a button for selection of a file name |
| directoryname | a string and a button for selection of a directory name |
| button | a push button that calls a call back routine |
Figure: Example with all possible types of parameters. Each item line is one line in the code, each value can be set or get with the set() or get() command. Each item in this example is connected with a callback that tells it to display the new values as soon its value has changed.
a floating point variable with a unit. See below for more details about units
calling convention:
obj=add(obj,'float',name,unit_type,value,unit,[min_val],[max_val]);
obj is an existing object of type parameter
'float' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
unit_type can be of type (easily extendable see below):
unit_time,unit_length,unit_none,unit_freq, etc.
If unit is unit_none than no unit select box is displayed
unit is the actual unit of that type (e.g. 'cm' for unit_lenght or 'Hz' for unit_freq)
value is the value of the item. This is stored with the actual unit.
min_val and max_val are optional. These are checked automatically by the gui
example:
params=add(params,'float','radius',unit_length,pi,'cm',0,inf);
params=add(params,'float','float with no unit',unit_none,'0:0.1:1');
or
params=add(params,'float','float with no unit','0:0.1:1');
compare with
params=add(params,'float','some float',0:0.3:1); (numerical value instead of string)
retrieving values:
val=getas(obj,'name','unit') (returns the value in that specific unit)
val=get(obj,'name') (returns the value in its original unit)
val=getstringvalue(obj,'name') (returns the value in its form on the screen)
If the value of a float is returned by get() or getas() then the numeric values are returned as a number or a vector. If the input is of the form 1:10 or similar then getasstringvalue() returns the string value. Accordingly setstringvalue sets the value as string. In this case the automatic unit transformation does not transform the numbers.
possible inputs
inputs can be in be in normal MATLAB input conventions.
Examples for float input
1:0.1:1 results in 0,0.1...1
[1:10] results in 0,1,2,...10
0,1.2,3 results in 0,1.2,3
'0:3' (in colons) -> the value in the field is always carried as a string, but the values you get with get() are 0 1 2 3
inf, -inf
a float value can also have the value 'auto'. In this case it is a string. You can check this from your program. (with isequal())
If no value is given, the value is automatically set to 0.
out of bound error
By default floats are restricted to the range -realmax to +realmax (1.7977e+308). By setting the min and max values these are checked automatically by the gui. A warning box pops up if a value is entered that is not valid
floats are left aligned
a floating point variable with a unit and a slider on its side . The value of the edit field and the slider field are connected, so when one is changed, the other one is automatically updated. Sliders are float values and have therefore an unit
calling convention:
obj=add(obj,'slider',name,unit_type,value,unit,min_val,max_val[,is_log]);
obj is an existing object of type parameter
'float' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
unit_type can be of type (easily extendable see below):
unit_time,unit_length,unit_none,unit_freq, etc.
If unit is unit_none than no unit select box is displayed
unit is the actual unit of that type (e.g. 'cm' for unit_lenght or 'Hz' for unit_freq)
value is the value of the item. This is stored with the actual unit.
min_val and max_val are not optional. They must be set!. These are checked automatically by the gui
is_log defines if the slider incement is linear (default) or logarithmic (that means, if you click on the right arrow, is the value increased by a constant amount or multiplied with a constant factor. possible values: 0 (linear), 1 (logarithmic)
example:
params=add(params,'slider','float',unit_length,pi,'cm',1,10,1);
example: (works with copy/paste)
params=parameter('slider panel');
params=add(params,'slider','a slider value',unit_length,5,'cm',1,10,0);
params=add(params,'slider','another slider value',5,1,10);
params=add(params,'button','OK');
params=parametergui(params);
An integer value. Integer values can also be of the form 1:10 or [1:10 13,15] etc...
calling convention:
obj=add(obj,'int',name[,value][,min_val][,max_val]);
obj is an existing object of type parameter
'float' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
value is the value of the item. If the value is a numerical value then the value of the parameter is set to this value. If it is given as a string ('1:10') then it is kept internally as string. If no value is given, the value is automatically set to 0.
min_val and max_val are optional, if not set they are set to -intmax and +intmax.. If included these are checked automatically by the gui
example:
params=add(params,'int','some int value','1:3',0,inf);
retrieving values:
get() returns the numerical value. If you are interested in the entry in the form as in 1:10 get it with getstringvalue(). Otherwise the standard get() function returns in this case [1 2 3 ...10].
a int value can also have the value 'auto'. In this case it is a string. You can check this from your program. (with isequal())
Integer values are right aligned.
string values are normal MATLAB strings. No checking is done with them.
calling convention:
obj=add(obj,'string',name,value,gui_length);
obj is an existing object of type parameter
'float' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
value is the string value of the item.
example:
params=add(params,'string','some string value','hallo world',33);
retrieving values
string_value=get(params,'some int value') returns the string value
bool: a checkbox with values either zero or one
calling convention:
obj=add(obj,'bool',name,value);
obj is an existing object of type parameter
'bool' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
value is either 0 or 1 or 'true' or 'false'
example:
params=add(params,'bool','yes or no','true');
retrieving values
bool_value=get(params,'yes or no')
remarks:
bool items can be used to enable or disable other parameter to make guis easier to understand for other users. Example (runs with copy/paste):
params=parameter('example parameters');
params=add(params,'panel','',3);
params=add(params,'bool','enable the following:',1);
params=add(params,'string','one parameter','is enabled');
params=add(params,'string','another parameter','is disabled');
params=enablefield(params,'enable the following:','one parameter');
params=disablefield(params,'enable the following:','another parameter');
params=add(params,'button','OK')
params=parametergui(params);
figure: ticking the first line enables or disables the following lines
panels group together several items visually by a rectangle. Except from radiobutton they only have an optic effect.
calling convention:
obj=add(obj,'panel',name,nr_rows);
obj is an existing object of type parameter
'panel' identifies the type of the parameter.
name is the the text that appears in the top line of the rectangular.
nr_rows indicates how many of the next objects are grouped in this panel.
example:
params=add(params,'panel','a panel with 2 items',2);
params=add(params,'float','first line',unit_none,1);
params=add(params,'float','second line',unit_none,2);
remarks
there can be as many panels in a gui as you want. Parameters in different panels can have the same name! They are referred to with the name of the panel in the end. See example for radiobutton
If two items have the same name and are in different panels then they must be referred by by adding the panel name in the get() or set() methods.
a radiobutton is one of several buttons in a box. Radiobuttons only make sense in plural.
calling convention:
obj=add(obj,'radiobutton',name,[value]);
obj is an existing object of type parameter
'radiobutton' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
value is either 0 or 1 or 'true' or 'false'. If no value is given it is automatically set to 0.
example:
params=add(params,'panel','make your choice',3);
params=add(params,'radiobutton','choice 1');
params=add(params,'radiobutton','choice 2',1);
params=add(params,'radiobutton','choice 3');
retrieving values
string_value=get(params,'make your choice') returns the actual selected string of the radiobutton.
remarks
radiobuttons only make sense in groups. Groups are defined by items of the type 'panel'.
if one of the items of a radiobutton is called 'other...' then it gets an extra string input box to the right where you can type in a string 'other...' must be in exact form (with three dots)
params=add(params,'panel','make your choice',3);
params=add(params,'radiobutton','choice 1');
params=add(params,'radiobutton','choice 2',1);
params=add(params,'radiobutton','other','what else');
get()now returns either the string 'choice 1' or 'choice 2' as before or the string that the user typed next to the 'other...' radiobutton. If a string is entered in the box the selection is automatically set to this box. If the 'other...' radiobutton is selected, the box is automatically highlighted and selected.
creates a pop-up menu that allows the choice between different strings
calling convention:
obj=add(obj,'pop-up menu',name,string_struct);
obj is an existing object of type parameter
'pop-up menu' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
string_struct is a structure of strings.
example:
string_struct={'selection 1','selection 2','selection 3'};
params=add(params,'pop-up menu','several strings',string_struct);
retrieving values
string_value=get(params,'several strings'). This returns the actual string that was selected.
generates a string box with a button. If you press the button a file select box pops up that allows to select a file.
calling convention:
obj=add(obj,'filename',name[,default_file]);
obj is an existing object of type parameter
'filename' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
default_file is the name of any file.
example:
params=add(params,'filename','select file name','c:\test.m');
retrieving values
file_name=get(params,'select file name'). This returns the actual file that is selected.
remarks
filename opens the file box in the directory that is given in the input box. After selecting a file the file is referenced absolute (with path).
works exactly like 'filename', but works with directories instead
calling convention:
obj=add(obj,'directoryname',name[,default_file]);
obj is an existing object of type parameter
'filename' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
default_file is the name of any file.
example:
params=add(params,'directoryname','select directory name','c:\temp');
retrieving values
folder_name=get(params,'select directory name'). This returns the actual directory that is selected.
creates a push button that calls a call back routine
calling convention:
obj=add(obj,'button',name,callback_function);
obj is an existing object of type parameter
'button' identifies the type of the parameter.
name is the the text that appears to the left of the input field and with which the value is returned or set.
callback_function is the name of a function or some code that is executed when the button is pressed
example:
params=add(params,'button','press this button','msgbox(''button pressed'')');
remarks
setting a button as default button:
the button can be made the default button by adding a "1" in the calling line params=add(params,'button','press this button','msgbox(''button pressed'')',1)
If nothing else is selected the callback of this function is called when the space bar or return is pressed on the keyboard.
Since MATLAB unfortunately does not support a proper graphic for that a black box is plotted around the button instead.
OK button
If a button is called with the string 'OK', it is automatically designed as a close button, no call back function is required:
params=add(params,'button','OK')
all of the different types can be assigned with a callback so that the action takes place immediately when you changed the selection. This is done by
params=setcallback(params,'name',callback);
The callback is now called every time the item looses its focus.
Objects of the parameter class can be used without gui. This is useful for collecting data structures in a single object, saving and loading them to disk or whatever. Furthermore parameters can be used to translate between units.
Parameters are displayed when you type the name in the MATLAB command line or when you move the mouse over them in the editor.
Example (works with copy/paste)
params=parameter('example parameters');
params=add(params,'float','time parameter',unit_time,1,'s')
params=add(params,'button','OK')
produces the following output:
example parameters: object of class datastruct with 2 entries:
( float) time parameter = 1 s
( button) OK (callback:) close
Each parameter can be accessed by a number of different ways:
given a float value:
params=add(params,'float','a float value','1:5')
The value of each parameter can be set with the command set(param,'name',value). In case of floats it can also be set with a unit: setas(param,'name',value,'unit'). When the parameter group has an open representation in a gui on the screen, the value in the gui is automatically updated.
Example (works with copy/paste)
params=parameter('watch!');
params=add(params,'int','random value');
params=parametergui(params);
setval='set(params,''random value'',rand*100);';
start(timer('period',0.5,'timerfcn',setval,'ExecutionMode','fixedDelay'));
Every float value has a unit (unless its defined without a unit or with "unit_none")
Units work automatically. The value of the parameter can be recalled either with the standard "get" function (in the same unit as it was defined in the first place) or with the getas function in any unit.
Example (works with copy/paste): Translation from cm to inches:
P=parameter;
P=add(P,'float','cm value',unit_length,1,'cm')
in_inch=getas(P,'cm value','inch')
Units that are implemented:
| unit type | unit type class name | implemented units of this type (first one is the definition unit) |
| time | unit_time | s, ms, µs, Hz, min, hours, days, weeks |
| length | unit_length | m, cm, mm, µm, inch, yards, mile,foot, parsec, points |
| frequency | unit_frequency | Hz, KHz, MHz, sec, ms |
| frequency ratio | unit_fratio | ratio, octave |
| voltage | unit_voltage | V, mV, µV, nV |
| voltage ratio | unit_vratio | ratio, dB, dB(attenuation) |
| modulation depth | unit_mod | lin, perc,dB, dB(attenuation), max_to_min |
| angle | unit_angle | deg, rad, perc, frac |
| weight | unit_weight | g, kg, t, mg, µg |
| capacity | unit_capacity | F, mF, µF, nF, pF |
| temperature | unit_temperature | Celsius, Kelvin, Fahrenheit |
| resistance | unit_resistance | Ohm, KOhm, MOhm, GOhm |
| current | unit_current | A, mA, µA, nA |
| no unit | unit_none |
params=parameter('example parameters');
params=add(params,'float','time parameter',unit_time,1,'s');
params=add(params,'float','length parameter',unit_length,1,'cm');
params=add(params,'float','frequency parameter',unit_frequency,1,'Hz');
params=add(params,'float','frequency ratio parameter',unit_fratio,1,'frequency
ratio');
params=add(params,'float','voltage parameter',unit_voltage,1,'V');
params=add(params,'float','voltage ratio parameter',unit_vratio,1,'volt ratio');
params=add(params,'float','modulation depth parameter',unit_mod,1,'lin');
params=add(params,'float','angle parameter',unit_angle,1,'deg');
params=add(params,'float','weight parameter',unit_weight,1,'g');
params=add(params,'float','capacity parameter',unit_capacity,1,'F');
params=add(params,'float','temperature parameter',unit_temperature,1,'°C');
params=add(params,'float','resistance parameter',unit_resistance,1,'Ohm');
params=add(params,'float','current parameter',unit_current,1,'A');
params=parametergui(params)
after copy paste the output is as follows
example parameters: object of class datastruct with 13 entries:
( float) time parameter = 1 s
( float) length parameter = 1 cm
( float) frequency parameter = 1 Hz
( float) frequency ratio parameter = 1 frequency ratio
( float) voltage parameter = 1 V
( float) voltage ratio parameter = 1 volt ratio
( float) modulation depth parameter = 1 lin
( float) angle parameter = 1 deg
( float) weight parameter = 1 g
( float) capacity parameter = 1 F
( float) temperature parameter = 1 °C
( float) resistance parameter = 1 Ohm
( float) current parameter = 1 A
please free to add your own units (and send copy to stefan@bleeck.de!), Adding your own units is straightforward. For a start just copy one of the existing units to a new directory and rename it. Then change the names and units translations accordingly.
Units have nice tooltips that describe them when you move the mouse over them
(runs with copy/paste)
params=parameter('convert scales');
params=add(params,'float','temperature',unit_temperature,23,'°C');
params=parametergui(params);
If the unit is changed to °Fahrenheit, the result is (with tooltips)
The result can be retrieved by:
(in Celsius:) getas(params,'temperature','°C')
(in Fahrenheit:) getas(params,'temperature','°F')
(in Kelvin:) getas(params,'temperature','K')
The following constructors are available:
parameter
parameter(name[,mode][,position])
mode is either 'modal' or 'nonmodal'
if mode is modal then the the gui is modal that means no other action is possible until the gui is closed.
The default is nonmodal
position defines where on the screen the gui is placed
position must be one of the following
% north - top center edge of screen
% south - bottom center edge of screen
% east - right center edge of screen
% west - left center edge of screen
% northeast - top right corner of screen
% northwest - top left corner of screen
% southeast - bottom right corner of screen
% southwest - bottom left corner
% center - center of screen
% onscreen - nearest location with respect to current location that is on
% screen The position argument can also be a two-element vector [h,v], where depending on sign, h specifies the
the default position of the gui is in the top right corner
every object of the parameter class can be displayed as graphical user interface. From here user interaction with the object is possible. To display the gui call
parametergui(params) or
params=parametergui(params) in
this case the new parameter object is returned. In case of a modal dialog the
result is returned when the gui is closed. In
nonmodal dialogs the object is returned immediately with the handles so that
the program can continue to communicate with it.
param=add(param,type,text,
|
adds an item to a parameter object (description see above) param must be an object of type parameter type can be one of the following: text is the description of the item the usage of the arguments4 to 8 depend on the type of item. |
| param=disablefield(param, paramtext, disablesthese, in_panel) |
when the parameter in paramtext is of type "bool" then switching it off enables the fields in disablethese |
| disp(params) | shows the content of the parameter param when you move the mouse over it |
| display(params) | shows the content of the parameter param on the screen |
| param=enable(param,text, disablevalue,in_panel) |
if it has a grafical representation then enable or disable according
to value of disablevalue |
| param=enablefield(param, paramtext,enablesthese,in_panel) |
when the parameter in paramtext is of type "bool" then switching it on enables the fields in disablethese |
| val=exist(param,text,in_panel) | returns 0 or 1 accoring to the existence of the parameter in text |
| val=get(param,text,in_panel) | returns the value of the parameter |
| val=getas(param,text,unit,in_panel) | returns the value of the floating parameter with the unit |
| param=getdefaultbutton(param) | returns the parameter that is set as the default button |
| entry=getentrybyhandle(param, hand) |
returns the entry with that handle |
| nr=getentrynumberbytext(param, text,in_panel) |
returns the numbe of the entry with that name |
| val=getfirstfocus(param) | returns the entry that gets the first focus after opening the gui |
| hand=gethandle(param,text, in_panel,handnr) |
returns the handle to the entry with that name |
| val=getmode(param) | returns the mode. Either 'modal' or 'nonmodal' |
| name=getname(param) | returns the name of the parameter object |
| pos=getposition(param) |
moves the figure identified by handle h to the specified screen location, preserving the figure's size. The position argument can be any of the following strings: north - top center edge of screen south - bottom center edge of screen east - right center edge of screen west - left center edge of screen northeast - top right corner of screen northwest - top left corner of screen southeast - bottom right corner of screen southwest - bottom left corner center - center of screen onscreen - nearest location with respect to current location that is on screen The position argument can also be a two-element vector [h,v], where depending on sign, h specifies the |
| val=getraw(param,text,in_panel) | returns the current value of the parameter as it is, no transformation |
function val=getstringvalue(param, |
returns the current value of the parameter as a string this is particulary useful for integer values in the form 1:10 |
| name=gettext(param,i,in_panel) |
return the description text of the parameter with the entry number
i. if i is a string then return the full string of the probably abbreviated |
| data=getuserdata(param,text,in_panel) |
the whole struct can have an user entry and every part of the structure as well. These can be used by the user for example for the 'other...' % radiobutton |
| val=getversion(param) | returns the version number of the parameter project |
| param=set(param,text,newvalue,in_panel) |
sets the parameter value in the parameter "text" in the
panel "in_panel" to
the value "value". if its a float then the unit is assumed to be the one with wich the parameter was first defined |
| param=setas(param,text,value, unit,in_panel) |
sets the parameter value in the parameter "text" in the
panel "in_panel" to the value "value". param must be of type float or int |
| param=setcallback(param,text, cback,in_panel) |
every entry can have a callback function that is called when the item looses its focus |
| params=setfirstfocus(params,where) |
sets the first focus to an element. When the gui is opend this one gets the focus |
| param=sethandle(param,text,hand, in_panel,handle_nr) |
sets the handle of this item. handles_nr is usually 1 but can be 2 in cases when more then one object is on the screen (float with unit, filename...) |
| param=setmode(param,mode) |
sets the mode of the gui. Can be 'modal' or 'nonmodal' |
| param=setposition(param,mode) | see getposition() |
| function param=setstringvalue(param, text,strvalue,in_panel) |
sets the parameter value in the parameter "text" in the panel "in_panel" to the value "strvalue" no units or anything are used |
| param=setuserdata(param,data,text,in_panel) |
the whole struct can have an user entry and every part of the structure as well. These can be used by the user for example for the 'other...' radiobutton |
| aram=settooltip(param,text, tooltiptext,in_panel) |
defines the tooltip for that entry |
Question:
I have unziped your file, but I still get the same message:
>> cd mfiles
>> example1
??? Undefined function or variable 'unit_length'.
Answer
You have to include the folder and the subfolders in the MATLAB path (File/Set Path...)
©Stefan Bleeck, University of Cambridge, 2004
many thanks to M. Lloyd for the idea!
