Understanding Handle Graphics Objects

Learn more about MATLAB

Understanding Handle Graphics Objects

On this page…
Using the Handle Graphics Objects Setting Object Properties Specifying the Axes or Figure Finding the Handles of Existing Objects

On this page…

Using the Handle

Graphics Objects

Setting Object Properties

Specifying the Axes or Figure

Finding the Handles of Existing Objects

Handle Graphics objects are MATLAB objects that implement graphing and visualization functions. Each object created has a fixed set of properties. You can use these properties to control the behavior and appearance of your graph.

When you call a MATLAB plotting function, it creates the graph using various graphics objects, such as a figure window, axes, lines, text, and so on. You can query the value of each property and set the values of most of them.

For example, the following statement creates a figure with a white background color and without displaying the figure toolbar:

figure('Color','white','Toolbar','none')

Using the Handle

Whenever MATLAB creates a graphics object, it assigns an identifier (called a handle) to the object. You can use this handle to access the object's properties with the set and get functions. For example, the following statements create a graph and return a handle to a lineseries object in h:

x = 1:10;
y = x.^3;
h = plot(x,y);

You can use the handle h to set the properties of the lineseries object. For example, you can set its Color property:

set(h,'Color','red')

You can also specify properties when you call the plotting function:

h = plot(x,y,'Color','red');

When you query the lineseries properties,

get(h,'LineWidth')

You obtain the answer:

ans =
	0.5000

Use the handle to see what properties a particular object contains:

get(h)

Graphics Objects

Graphics objects are the basic elements used to display graphs and user interface components. These objects are organized into a hierarchy, as shown by the following diagram.

Key Graphics Objects

When you call a function to create a MATLAB graph, a hierarchy of graphics objects results. For example, calling the plot function creates the following graphics objects:

Lineseries plot objects — Represent the data passed to the plot function.
Axes — Provide a frame of reference and scaling for the plotted lineseries.
Text — Label the axes tick marks and are used for titles and annotations.
Figures — Are the windows that contain axes toolbars, menus, etc.

Different types of graphs use different objects to represent data; however, all data objects are contained in axes and all objects (except root) are contained in figures.

The root is an abstract object that primarily stores information about your computer or MATLAB state. You cannot create an instance of the root object.

For More Information See Handle Graphics Objects in the MATLAB Graphics documentation for details about graphics objects.

User interface objects are used to create graphical user interfaces (GUIs). These objects include components like push buttons, editable text boxes, and list boxes.

For More Information See Creating Graphical User Interfaces for details about user interface objects.

Creating Objects

Plotting functions (like plot and surf) call the appropriate low-level function to draw their respective graph. For information about an object's properties, you can use the Handle Graphics Property Browser in the MATLAB online Graphics documentation.

Functions for Working with Objects

This table lists functions commonly used when working with objects.

Function	Purpose
`allchild`	Find all children of specified objects.
`ancestor`	Find ancestor of graphics object.
`copyobj`	Copy graphics object.
`delete`	Delete an object.
`findall`	Find all graphics objects (including hidden handles).
`findobj`	Find the handles of objects having specified property values.
`gca`	Return the handle of the current axes.
`gcf`	Return the handle of the current figure.
`gco`	Return the handle of the current object.
`get`	Query the values of an object's properties.
`ishandle`	True if the value is a valid object handle.
`set`	Set the values of an object's properties.

Setting Object Properties

All object properties have default values. However, you might find it useful to change the settings of some properties to customize your graph. There are two ways to set object properties:

Specify values for properties when you create the object.
Set the property value on an object that already exists.

Setting Properties from Plotting Commands

You can specify object property value pairs as arguments to many plotting functions, such as plot, mesh, and surf.

For example, plotting commands that create lineseries or surfaceplot objects enable you to specify property name/property value pairs as arguments. The command

surf(x,y,z,'FaceColor','interp',...
			'FaceLighting','gouraud')

plots the data in the variables x, y, and z using a surfaceplot object with interpolated face color and employing the Gouraud face light technique. You can set any of the object's properties this way.

Setting Properties of Existing Objects

To modify the property values of existing objects, you can use the set command or the Property Editor. This section describes how to use the set command. See Using the Property Editor for more information.

Most plotting functions return the handles of the objects that they create so you can modify the objects using the set command. For example, these statements plot a 5-by-5 matrix (creating five lineseries, one per column), and then set the Marker property to a square and the MarkerFaceColor property to green:

h = plot(magic(5));
set(h,'Marker','s','MarkerFaceColor','g')

In this case, h is a vector containing five handles, one for each of the five lineseries in the graph. The set statement sets the Marker and MarkerFaceColor properties of all lineseries to the same values.

Setting Multiple Property Values

If you want to set the properties of each lineseries to a different value, you can use cell arrays to store all the data and pass it to the set command. For example, create a plot and save the lineseries handles:

h = plot(magic(5));

Suppose you want to add different markers to each lineseries and color the marker's face color the same color as the lineseries. You need to define two cell arrays—one containing the property names and the other containing the desired values of the properties.

The prop_name cell array contains two elements:

prop_name(1) = {'Marker'};
prop_name(2) = {'MarkerFaceColor'};

The prop_values cell array contains 10 values: five values for the Marker property and five values for the MarkerFaceColor property. Notice that prop_values is a two-dimensional cell array. The first dimension indicates which handle in h the values apply to and the second dimension indicates which property the value is assigned to:

prop_values(1,1) = {'s'};
prop_values(1,2) = {get(h(1),'Color')};
prop_values(2,1) = {'d'};
prop_values(2,2) = {get(h(2),'Color')};
prop_values(3,1) = {'o'};
prop_values(3,2) = {get(h(3),'Color')};
prop_values(4,1) = {'p'};
prop_values(4,2) = {get(h(4),'Color')};
prop_values(5,1) = {'h'};
prop_values(5,2) = {get(h(5),'Color')};

The MarkerFaceColor is always assigned the value of the corresponding line's color (obtained by getting the lineseries Color property with the get command).

After defining the cell arrays, call set to specify the new property values:

set(h,prop_name,prop_values)

Specifying the Axes or Figure

MATLAB always creates an axes or figure if one does not exist when you issue a plotting command. However, when you are creating a graphics M-file, it is good practice to explicitly create and specify the parent axes and figure, particularly if others will use your program. Specifying the parent prevents the following problems:

Your M-file overwrites the graph in the current figure. A figure becomes the current figure whenever a user clicks it.
The current figure might be in an unexpected state and not behave as your program expects.

The following example shows a simple M-file that plots a function and the mean of the function over the specified range:

function myfunc(x)
% x = -10:.005:40; Here's a value you can use for x
y = [1.5*cos(x) + 6*exp(-.1*x) + exp(.07*x).*sin(3*x)];
ym = mean(y);
hfig = figure('Name','Function and Mean',...
		'Pointer','fullcrosshair');
hax = axes('Parent',hfig);
plot(hax,x,y)
hold on
plot(hax,[min(x) max(x)],[ym ym],'Color','red')
hold off
ylab = get(hax,'YTick');
set(hax,'YTick',sort([ylab ym]))
title ('y = 1.5cos(x) + 6e^{-0.1x} + e^{0.07x}sin(3x)')
xlabel('X Axis'); ylabel('Y Axis')

Finding the Handles of Existing Objects

The findobj function enables you to obtain the handles of graphics objects by searching for objects with particular property values. With findobj you can specify the values of any combination of properties, which makes it easy to pick one object out of many. findobj also recognizes regular expressions (regexp).

For example, you might want to find the blue line with square marker having blue face color. You can also specify which figures or axes to search, if there are more than one. The following four sections provide examples illustrating how to use findobj.

Finding All Objects of a Certain Type

Because all objects have a Type property that identifies the type of object, you can find the handles of all occurrences of a particular type of object. For example,

h = findobj('Type','patch');

finds the handles of all patch objects.

Finding Objects with a Particular Property

You can specify multiple properties to narrow the search. For example,

h = findobj('Type','line','Color','r','LineStyle',':');

finds the handles of all red dotted lines.

Limiting the Scope of the Search

You can specify the starting point in the object hierarchy by passing the handle of the starting figure or axes as the first argument. For example,

h = findobj(gca,'Type','text','String','\pi/2');

finds the string π/2 only within the current axes.

Using findobj as an Argument

Because findobj returns the handles it finds, you can use it in place of the handle argument. For example,

set(findobj('Type','line','Color','red'),'LineStyle',':')

finds all red lines and sets their line style to dotted.

Printing Graphics

Programming

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit