You may find this document helpful if you are modifying your plots and/or GUIs. You have control over your plots and/or GUIs through various properties that you can change. This document explains how to work with these properties.

Section 2: Introduction

First of all, we need to explain some terms that will be used often in this document.

Graphics objects

Graphics objects are the basic elements used to display graphics and user interface elements. Here is the list of graphics objects you can create in MATLAB:

Root	Top of the hierarchy corresponding to the computer screen
Figure	Window used to display axes, uicontrols, uimenus, and uicontextmenus
Axes	Axes for displaying graphics in a figure
Uicontrol	User interface control that executes a function or functions in response to user interaction
Uimenu	User-defined figure window menu
Uicontextmenu	Pop-up menu invoked by right clicking on a graphics object
Image	Two-dimensional pixel-based picture
Light	Light sources that affect the coloring of patch and surface objects
Line	Line used by functions such as plot, plot3, semilogx
Patch	Filled polygon with edges
Rectangle	Two-dimensional shape varying from rectangles to ovals
Surface	Three-dimensional representation of matrix data created by plotting the value of the data as heights above the x-y plane
Text	Character string

High-Level Versus Low-Level

The MATLAB high-level graphics routines (e.g., PLOT or SURF) call the appropriate object creation function to draw graphics objects. However, high-level routines also clear the axes or create a new figure, depending on the settings of the axes and figure NextPlot properties.

In contrast, object creation functions simply create their respective graphics objects and place them in the current parent object. They do not respect the setting of the figure or axes NextPlot property. For example, if you call the line function,

line('XData',x,'YData',y,'ZData',z,'Color','r')

MATLAB draws a red line in the current axes using the specified data values. If there is no axes, MATLAB creates one. If there is no figure window in which to create the axes, MATLAB creates it as well.

The following table shows some examples of high-level versus low-level graphics functions:

High Level	Low Level
`PLOT`	`LINE`
`SURF`	`SURFACE`
	`TEXT`

Graphics object handles

Whenever MATLAB creates a graphics object, it assigns an identifier (a number) called a handle to the object. You can use this handle to access the object's properties. Root has handle 0, generally all others have integer handles.

Graphics object properties

Every graphics object has a set of properties associated with it. You can set these properties at the time of creation specifying property name and property value pairs. The properties define different attributes of an object, such as color, size, position, etc. For example, to create a figure with a green background and a landscape orientation, you can use the following command:

fig = figure('Color',[0 1 0],'PaperOrientation','landscape')

where [0 1 0] is the RGB values for the color green. This command will use the default values for properties that are not explicitly set in the command. The default properties for each graphics object are listed in the Handle Graphics Property Browser.

If you are familiar with object oriented programming, you can find an analogy with a constructor method. If there are no input arguments, the constructor should create a default object. If the input arguments exist, then the constructor creates the object using the input data.

Handle Graphics Property Browser

The Handle Graphics Property Browser is useful to view all handle graphics object properties. It can be found from the Help Browser for MATLAB 6.5 and 7.0 (R13.5 and R14):

Type doc at the MATLAB Command Prompt.
Click on the 'Content' tab.
Click on 'Handle Graphics Property Browser' under 'MATLAB' in the tree.
Click on the object of your interest on the right.

For MATLAB 5.x (R11.x):

Type doc at the MATLAB Command Prompt.
Click on 'Handle Graphics Properties' on the left.
Click on the object of your interest.

For the latest versions, see the Handle Graphics Property Browser.

MATLAB 5.x (R11.x) documentation is not available on the web, but it is similar to MATLAB 6.5 and 7.0 (R13.5 and R14).

Section 3: How do I find graphics object handles?

There are several functions for locating graphics object handles (click on the function to display a corresponding help page with examples):

GCF - get current figure (return the handle to the current figure)

GCA - get current axes (return the handle to the current axes)

GCO - get current object (return the handle to the current object)

GCBF - get handle of parent figure of the graphics object whose callback is executing.

GCBO - get handle of the graphics object whose callback is executing.

FINDOBJ - find objects, not including those whose HandleVisibility property set to 'off', with specified property values.

FINDALL - find all objects, including those whose HandleVisibility property set to 'off', with specified property values.

Example:

h1 = plot(1:10)

h1= 3.0020

ht1 = text(0.1,2,'text1')

ht = 101.0026

ht2 = text(.1,4,'text2','HandleVisibility','off')

ht2= 102.0009

% will not find ht2, since HandleVisibility is 'off'
findobj(gcf,'type','text')

ans= 101.0026

% will find all of text objects within the current figure 
% regardless HandleVisibility settings 
findall(gcf,'type','text')

ans=
102.0009
101.0026

For more information on finding graphic object handles, see the documentation.

Section 4: How do I query and change graphics object properties?

There are two methods of querying and changing with graphics object properties:

Using the property editors (interactive method)
Using GET and SET functions (script or Command Line method)

Using the property editors (interactive method).

In MATLAB 6.5 and later versions, you can use a graphical user interface, called the Property Editor, to edit many properties of graphics objects.

You can start the Property Editor by clicking on the arrow button on the figure's toolbar to enable plot editing mode and double-clicking on an object in a graph, such as a line, or by right-clicking on an object and selecting the Properties option from the object's context menu.

You can also start the Property Editor by selecting either the Figure Properties, Axes Properties, or Current Object Properties from the figure window Edit menu. These options automatically enable plot editing mode, if it is not already enabled.

One more option is to use the PROPEDIT command.

See the Property Editor for more information.

In MATLAB 5.x (R11.x) the Plot Editor can be used for some axes, line, and text properties editing.

In MATLAB 6.x (R12.x and R13), if you are using GUIDE to design your GUI, you can edit component object properties using the Properties Inspector.

You can display the Property Inspector by:

Double-clicking on a component in the Layout Editor.
Selecting Property Inspector from the View menu.
Right-clicking on a component and selecting Property Inspector (or Inspect Properties for MATLAB 6.0 (R12.0)) from the context menu.

See the Property Inspector for more information.

In MATLAB 5.x (R11.x) you can edit component object properties using Property Editor from the GUIDE Control Panel.

`GET` and `SET` commands (Command Line or script method)

After an object is created, it is possible to query and change its properties by using the GET and SET commands. GET is used to get information about the object:

get(<Object Handle>)
 
<m structure with n fields> = get(<m vector of Object Handles>)

In the above syntax,<m structure with n fields> is an m structure array whose field names are the object property names and whose field values are (1)the values of the corresponding properties or (2)a particular property associated with the object:

get(<Object Handle>,<Property>)
 
<m-by-n cell array of Property Values> = ...
    get(<m vector of Object Handles>,<n cell array of Property Names>)

SET is used to determine the properties that can be controlled by the user along with their possible values (assuming the property has a discrete set of values:

set(<Object Handle>)
 
<n-field structure> = set(h)

In the above syntax, <n-field structure> is a structure array whose field names are the object property names and whose field values are (1)the values of the corresponding properties or (2)exhibit the change of the property values of one or more objects:

set(<m vector of object handles>,'<Property Name 1>',...
    <Property Value 1>,...,'<Property Name n>',<Property Value n>)

set(<m vector of object handles>, <m structure with n fields>)

In the above syntax, <m structure with n fields> is an m structure array whose field names are the object property names and whose field values are the values of the corresponding properties:

set(<m vector of object handles>,<n cell array of property names>,... 
    n cell array of property values>)
 
set (<m vector of object handles>,<n cell array of property names>,...
    m-by-n cell array of property values>)

Examples:

To determine the properties associated with the current figure, type
```
get(gcf)
```
This command produces the following output:
```
Alphamap = [ (1 by 64) double array]  
BackingStore = on  
CloseRequestFcn = closereq  
Color = [0.8 0.8 0.8]  
Colormap = [ (64 by 3) double array]  
...
```
The names to the left of the equal sign are the property names, and the values to the right are the current property value.
To see the properties of a figure object that can be controlled by the user, type
```
set(gcf)
```
This returns:
```
Alphamap  
BackingStore: [ {on} | off ]  
CloseRequestFcn: string -or- function handle -or- cell array  
Color  
Colormap  
...
```
As you can see, the property names are listed along with the valid options for the property value, when appropriate. The default values for a property are enclosed in the curly braces {}. For example, the valid property values for BackingStore are 'on' and 'off' with the default being 'on'. However, Color does not have any values for the property value. The color can be any valid RGB vector. This holds true for other properties that do not display any options; they can be set to any valid value.
To get the Color property value for the line:
```
h = plot(1:10); 
col = get(h,'Color');
```
To set the LineStyle property for the line to dotted:
```
h = plot(1:10); 
set(h,'LineStyle',':')
```

When using GET, you can query multiple properties for multiple objects in a single statement, as long as all the properties are common to each object. The property names are defined in a cell array and the object handles are enclosed in brackets. For example, the statements below will query the Color, LineStyle and LineWidth of 3 lines.

h1 = plot(1:10,'LineWidth',4);
hold on
h2 = plot(11:20,'r:');
h3 = plot(21:30,'g--');


% Create a cell array containing the property names:
info(1,1)={'Color'};
info(1,2)={'LineStyle'};
info(1,3)={'LineWidth'};


% Query the Color, LineStyle, and LineWidth of lines
lines_info = get([h1 h2 h3],info)

lines_info = 

    [1x3 double]    '-'     [     4]
    [1x3 double]    ':'     [0.5000]
    [1x3 double]    '--'    [0.5000]

When using SET, you can change multiple property values for multiple objects in a single statement using structure arrays, as long as each property is common to each object. This is useful when you want to change a property that many objects have in common.
The statements below will set the FontAngle and FontSize properties for the current axes and axes tick marks.
```
ht = text(.3,.6,'text');


% Create a structure array containing the property 
% name/property value pairs
data.FontAngle='italic';
data.FontSize=18;


% Set the text objects
set([gca ht],data)
     
```

If you assign the output of GET or SET to a variable, MATLAB creates a structure array whose field names are the property names and whose field values are the current or possible values of the named properties. For example,

h=plot(1:10); 
details=get(h); 
details.Color

            ans =     0 0 1

            details.LineStyle
            ans =
    - 

            details=set(h);
details.LineStyle
      ans = 
      '-' 

      '--' 

      ':' 

      '-.' 

       'none'

How do I control the fonts for labels and titles?

Below is a list of font-related properties and their default values. Click on the property name below to go to the documentation for that property. The documentation will show all possible property values.

Property Name	Default Value
FontAngle	normal
FontName	Helvetica
FontSize	10
FontUnits	points
FontWeight	Normal

If you use GET or SET for the axes object, note that these 5 properties relate ONLY to axis tick mark labels. If you want to use these properties for axes labels or a title, you can use the XLABEL, YLABEL, ZLABEL, or TITLE commands.For example,

h = title('This is the title')
set(h, 'FontName','Helvetica')

Use this format to set the FontName for the title related to the current axes to Helvetica, if you did not assign a handle during object creation:

title('This is the title')
h = get(gca,'title');
set(h,'FontName','Helvetica')

Use the same procedure to set the FontName of labels (xlabel, ylabel, and zlabel). For example,

h = xlabel('This is the label')
set(h,'FontName','Times')

Use this format to set the FontName for the xlabel related to the current axes to Times, if you did not assign a handle during object creation:

xlabel('This is the label')
h = get(gca,'xlabel');
set(h,'FontName','Times')

MATLAB uses fonts installed on your machine. In MATLAB 6.5, 7.0 (R13.5, R14) and later versions, you can get the list of available fonts by typing:

listfonts

at the MATLAB Command Prompt. The default font is Helvetica.

These settings can be combined to create almost any combination that your machine supports. For example, to specify a 12-point Helvetica bold oblique font, do one of the following:

h = text(.5,.5,'Text String','FontName','Helvetica',... 
'FontSize',12,'FontWeight','bold','FontAngle',... 
'oblique');


h = text(.5,.5,'Text String');
set(h,'FontName','Helvetica','FontSize',12, ...
'FontWeight','bold','FontAngle','oblique');

If your machine does not support a particular collection of font settings, then MATLAB uses the following rules for selecting the font:

MATLAB accepts oblique in place of italic and vice versa.
If a match is still not found, MATLAB ignores the FontAngle.
If a match is still not found, MATLAB ignores the FontWeight.
If a match is still not found, MATLAB ignores the FontSize.
If a match is still not found, MATLAB does not change the font.

For more information on GET and SET, see the documentation.

Section 5: Setting default property values

Changing the characteristics of an object and having the change recognized throughout all MATLAB sessions or the current MATLAB session. In either of these cases, the default settings can apply to figures or to axes.

All MATLAB sessions - the default values will affect figures created in the current MATLAB session and all sessions afterwards.
Current MATLAB session - the default values will only affect figures created in the current MATLAB session. When you quit from MATLAB, those default values will no longer hold.
Figure - the default value will only affect the chosen figure and its children; other figures created in the same MATLAB session will not be affected
Axes - the default value will only affect the chosen axes its children; other axes in the same figure will not be affected by the default values

The closer to the root of the hierarchy you define the default, the broader its scope. If you specify a default value for line objects on the root level, MATLAB uses that value for all lines (since the root is at the top of the hierarchy). If you specify a default value for line objects on the axes level, then MATLAB uses that value for line objects drawn only in that axes. If you define default values on more than one level, the value defined on the closest ancestor takes precedence since MATLAB terminates the search as soon as it finds a value. Note that setting default values affects only those objects created after you set the default. Existing graphics objects are not affected.

The object handle used with SET must be an ancestor of the object you are changing the default property value of. This is because the object will inherit the property values from an ancestor. Below is the basic structure for setting defaults.

set(<Ancestor>,'Default<Object><Property Name>',<Property Value>)

where <Ancestor> is the handle of the ancestor, <Object> is the name of the object, <Property Name> is the name of the property, and <property value> is the new property setting. Below are some examples of setting defaults.

Examples:

Set the default figure window position (note that figures are children of Root)
```
set(0,'DefaultFigurePosition',[100 200 200 300])
```
Set the default axes color for the current figure window
```
set(gcf,'DefaultAxesColor',[0 1 0])
```
Every axes created in this figure window will be green. If another figure window is created, the color of the axes in that figure will be the original default color, unless you specify otherwise.
Set the default color of the axes for the MATLAB session
```
set(0,'DefaultAxesColor',[0 1 0])
```
Every axes will be green, regardless of the figure window they were created in.
Set the default line width to 2 points for lines in the current axes
```
set(gca,'DefaultLineLineWidth',2)
```
After this SET command, every line plotted in the current axes will have a width of 2 points.

If you want to use the default values you set in future MATLAB sessions, you can insert the corresponding SET commands into a startup.m file which is always executed when you start MATLAB. If you do not have a startup.m file on the MATLAB path, you can create one. It will be executed next time you start MATLAB. For more information on getting and setting default property values, see the documentation.

Section 6: Options used to unset properties

After changing the property value, you may decide that you want to revert back to the default value or factory value. Depending on what you want to do and the property you are working with, you can use one of the following:

OPTIONS	PURPOSE
default	This changes the property back to its default value
factory	This changes the property back to the factory installed value
remove	This removes the user-defined propertyvalues

For example, the factory installed color for a figure is black. If the default color is set to green and then changed to blue, you can easily change the color back to black or green by using factory or default.

set(0,'DefaultFigureColor','g') % Set the default color to green
set(gcf,'Color','b') % Set the color to blue
set(gcf,'Color','factory') % Makes the figure black again
set(gcf,'Color','default') % Makes the figure green again

Here is an example on how to use remove to get back to the default figure color:

get(0,'DefaultFigureColor')

ans= 0.8000 0.8000 0.8000

set(gcf,'Color','y') % Makes the figure yellow
set(gcf,'Color','b') % Makes the figure blue
set(gcf,'Color','remove') % Returns to the gray default color

To remove the default figure color use the following command:

set(0,'DefaultFigureColor','remove') 
% Makes the figure black (the factory color)

For more information on topics discussed in this section, see the documentation.

Section 7: How can I keep track of my GUI object handles?

In any large graphical user interface (GUI) driven application, the issue of keeping track of all the object handles can become very complex. This section discusses the various options available, along with the strengths and weaknesses of each.

NOTE: This section does not go into detail about building these interfaces, and it assumes that the reader is familiar with the control of handle graphics properties. See the MATLAB guide, Creating Graphical User Interfaces, for information on building GUIs. Also, see previous sections of this document for a general discussion on controlling properties.

Question: How can I access stored handles across function workspaces?

When building graphical interfaces, it is often convenient to break the process into several functions. However, if you use a standard function to create graphical objects, the variables containing their handles are lost once the function exits. In particular, uicontrol callbacks do not have access to the variables defined during the uicontrol's creation. How can you get around this? There are several solutions.

Answer #1 (for MATLAB 6.x (R13) and later) - The 'handles' structure, as GUIDE uses by default

The MATLAB functions GUIDATA and GUIHANDLES provide a mechanism for storing and retrieving global data using the same structure that contains the GUI component handles. The 'handles' structure, which is automatically generated for GUIs built with GUIDE, contains handles to all the components in the GUI. The 'handles' structure is passed to each callback in the application M-file. Therefore, this structure is useful for saving any global data. For example, the following excerpt uses the 'handles' structure to obtain the handles of the edit text and the slider, then set the edit text String to the slider Value:

set(handles.edit1,'String',... 
num2str(get(handles.slider1,'Value'))); 
guidata(gcbo,handles); 
%save the current handles structure 
%for the GUI figure

It is crucial to save changes to the 'handles' structure using the GUIDATA function, otherwise modifications to the 'handle' structure will be lost when the current function exits.

This method is best for GUIs with a large number of uicontrols and other graphics objecst. The 'handles' structure may not be well suited for storing large data sets. The SETAPPDATA and GETAPPDATA provide a better approach.

For more information on the Handles Structure, see the documentation.

Answer #2 - (for MATLAB 7.x (R14) and later) - Nested Functions

As of MATLAB 7.0, you have the ability to nest one function inside of another. The advantage is Nested Functions have access to the variables in the workspace of its parent main function. This is ideal for smaller GUIs with a few uicontrols and callback functions. The uicontrols can be created programmmatically in a main function, while the callbacks to the uicontrols can be Nested Functions within the main function. This avoids passing handles as input arguments to a callback or other function that modifies graphical element properties.

There are several examples located on MATLAB Central that illustrate the usage of Nested Functions. They can be found from the following links:

Nested Functions used as GUI callbacks

GUI examples using Nested Functions

Rubix Cube

In addition, there is more information regarding the first linked example at the following web address:

www.mathworks.com/company/newsletters/news_notes/jan06/patterns.html

Using Nested Functions may get more tedious in GUIs with a large number of uicontrols and graphics objects. This is primarily because there is no automation to assist in creating the uicontrols programmmatically.

Answer #3 - The SETAPPDATA and GETAPPDATA functions

The SETAPPDATA and GETAPPDATA are lower level functions that allow you to associate and store data with a graphics object. It stores data in name/value pairs much like the properties of graphics objects. The GUIDATA function actually uses these lower level functions to store the 'handles' structure to the figure object that contains the GUI. In this case you can specify the name of the data stored in association with a graphics object, and the graphics objects are not limited to figures.

This affords other options if you were interested in storing a large data set for use within a GUI, but did not want to pass it to each callback function. Instead you could retrieve it at will using the GETAPPDATA function. For example, in a GUI creation function:

set(handles.edit1,'String',... 
A = rand(1000); 
setappdata(fig_hndl,'MyRandomData', A); 
%saves the values in A to 'MyRandomData' 
%as application data of the figure 
%associated with the handle in "fig_hndl"

A callback function that uses this particular dataset can access it as follows:

set(handles.edit1,'String',... 
Data = getappdata(fig_hndl,'MyRandomData'); 
%retrieves the values in 'MyRandomData' and stores them
%in the variable "Data"

Application data is stored when figure is saved to a FIG-file. You may want to keep this in mind when saving and reloading figures used as GUIs.

As mentioned above, using the application data is ideal for accessing largere data sets from within specific callback functions. However it is generally easier to use the 'handles' structure for storing most GUI related data.

Answer #4 - The FINDOBJ and FINDALL functions

The FINDOBJ and FINDALL functions allows you to search for an object with a given property name and value pair (see also Section 3 for details).

Given these functions, the necessity arises for some method of keeping uicontrols unique. Searching for a slider, for example, based on its position would again become tedious. The solution is to use the Tag property.

The Tag property allows you to give a graphics object a name. You can then search for an object with a given name. The name can denote a class of objects, in which case FINDOBJ (or FINDALL) returns a vector of handles.

Example:
The example below has seven uicontrol objects: three sliders, three texts, and one push button. Each text uicontrol displays the current value of one of the sliders, while the push button resets the values of the sliders. The sliders' callbacks set the string property of the text uicontrols, while the push button's callback resets both the sliders and the texts.

function guitest(option)
if nargin == 0 % set up
  figure('menu','none','pos',[50 50 180 200]);
  % Set up uicontrols; 'Tag' them as belonging to a group
  uicontrol('Style','slider','Position', ...
    20 20 20 80],'Tag','#1','min',-1, ...
    'Callback','guitest set');
  uicontrol('Style','slider','Position', ...
    [80 20 20 80],'Tag','#2','min',-1, ...
    'Callback','guitest set');
  uicontrol('Style','slider','Position', ...
    [140 20 20 80],'Tag','#3','min',-1, ...
    'Callback','guitest set');
  % Set up text uicontrols; 'Tag' them as belonging
  % to a group
  uicontrol('Style','text','String',num2str(0), ...
    'Tag','#1','Position',[10 110 40 15]);
  uicontrol('Style','text','String',num2str(0), ...
    'Tag','#2','Position',[70 110 40 15]);
  uicontrol('Style','text','String',num2str(0), ...
    'Tag','#3','Position',[130 110 40 15]);
  % Set up push button control
  uicontrol('Position',[60 140 60 20],'String', ...
    'Reset','Callback','guitest reset');
elseif strcmp(option,'set')
  % Set the text above the slider to reflect the string
  % value. Get handle to accompanying text uicontrol --
  % i.e., find matching 'Tag'
  txthndl = findobj(gcf,'Style','text', ...
    'Tag',get(gco,'Tag'));
  % Set value to current value of slider
  set(txthndl,'String',num2str(get(gco,'value')));
elseif strcmp(option,'reset')
  % Reset all slider values and text values
  % Get handles to text and slider objects. Notice that,
  % by restricting the search to this figure, we avoid
  % resetting other figure windows' uicontrols.
  texts = findobj(gcf,'Style','text');
  sliders = findobj(gcf,'Style','slider');
  set(texts,'string',num2str(0));
  set(sliders,'value',0);
end

This is a simple example, but there are several things to note. First, there are no explicit references to handles stored -- all references are via either the GCO or FINDOBJ function. The syntax of the FINDOBJ function allows us to search only the current figure and ignore any other figures. Second, the Tag property is used to divide the uicontrols into groups, each consisting of one slider and one text uicontrol. This allows each slider to set only its associated text uicontrol's String property.

The advantage of using the FINDOBJ and FINDALL functions is the ability to access a particular graphics object without having the handle to the object. However this is generally slower than using stored handles.

Answer #5 - The UserData property

Handles can also be stored with graphics objects themselves. The UserData property can store any matrix, including handles to other graphics objects.

The disadvantage of this method is that the UserData property must itself be accessible to the function. This limits handles to being stored in one of four places:

the UserData property of root (not recommended)
the UserData property of the current figure
the UserData property of the current axes
the UserData property of the current object

Lists of object handles can be stored, or UserData properties can store handles in hierarchies. However, this means that the designer must keep track of the entire list or hierarchy to access one element. While this is plausible for small projects, it can quickly become tedious for larger projects.

UserData is commonly used with GCBF and GCBO, making it possible for Handle Graphics objects to update themselves.

This method is closely related to using an object's application data, but it only allows storage of one array. The application data can store numerous arrays of different datatypes.

Answer #6 - Global variables (not recommended)

Another method is to declare all handle variables global when the uicontrols are created. Then, any function that uses those uicontrols (including callbacks) can declare the appropriate global variables and have access to the handles.

You should be aware that by using global variables your variables may inadvertently be changed by other programs or by the user of your program. The use of global variables means you may have name conflicts with global variables belonging to other programs. You should also know that the command clear all deletes all of your global variables and therefore your handles.

Finally, all variables representing handles must be stored in the same workspace, which can be somewhat confusing to manage. For these reasons, the use of global variables is often not the best solution.

Section 8: Commonly used Handle Graphics Tricks and Tips

Products & Services	Industries	Academia	Support	User Community	Company