Basics of Handle Graphics

Understanding Handle Graphics

Handle Graphics is the system MATLAB uses to represent and control anything you see in a figure. When you create a plot, MATLAB creates objects such as figures, axes, and lines, and gives you a way to access and modify them using handles. In this chapter you will focus on what handles are, how to get them, and how to use them to customize graphics in a more precise way than plain plotting commands.

Graphics Objects and Handles

Whenever you create a plot, MATLAB creates graphics objects. Examples of these objects are figures, axes, lines, images, surfaces, and text. Each object has properties, such as color, line width, position, and many more. To work with these properties, you need a reference to the object. This reference is the handle.

A handle is a variable that stores a special value that points to a graphics object. In modern MATLAB, this value is an object of a specific graphics class, such as matlab.ui.Figure or matlab.graphics.chart.primitive.Line. When you store this handle in a variable, you can later use it to inspect or change the appearance and behavior of the object.

For example, if you write:

h = plot(1:10, rand(1,10));

the variable h receives the handle to the line object that plot created. You do not see the line object itself in the Workspace, only this handle. The handle allows you to query and modify the line properties through functions or dot notation.

Getting and Using Handles from Plotting Commands

Many plotting functions return one or more handles when you capture their output. If you ignore the output, MATLAB still creates the objects, but you lose the easiest direct access to them. For that reason, it is good practice to assign outputs from plotting functions to variables whenever you plan to customize them later.

For a simple line plot, you can retrieve a line handle as shown before:

x = 0:0.1:2*pi;
y = sin(x);
hLine = plot(x, y);

Now hLine is the handle to the line object. You can use it with get and set, or with dot notation, to modify things like color, line style, and line width.

Some plotting functions return multiple handles. For example:

x = 0:0.1:2*pi;
hLines = plot(x, sin(x), x, cos(x));

Here hLines is an array of line handles, one for each line created. You can index into this array to affect one line at a time:

hLines(1).Color = 'r';
hLines(2).Color = 'b';

Other graphics functions return handles for different kinds of objects. For instance, figure returns a figure handle, axes returns an axes handle, and bar, scatter, or surf return handles to their respective chart objects. The pattern is always the same: capture the result in a variable and then operate on that variable to customize your graphic.

Accessing Existing Objects with gcf, gca, and findobj

Sometimes you want to modify an object, but you did not capture its handle when you created it. MATLAB provides functions to access the current graphics objects so that you can still work with them.

The function gcf returns the handle to the current figure, that is, the figure that MATLAB considers active. If no figure exists, MATLAB creates one. For example:

plot(1:5);
hFig = gcf;

Now hFig refers to the figure that contains the plot you just made.

The function gca returns the handle to the current axes. Again, if no axes exists, MATLAB will create one in the current figure. For example:

plot(1:5);
hAx = gca;

The variable hAx now contains the axes handle. You can use it to change axes properties such as limits or background color.

For more specific searches, findobj lets you search for graphics objects by type or property. You usually call it with property name-value pairs. For example, to find all line objects in the current axes you can write:

hLines = findobj(gca, 'Type', 'line');

The result is an array of handles that match your search. You can then loop over them or set properties on all of them at once with vectorized syntax.

Inspecting and Changing Properties

Every graphics object has properties that define its appearance and some aspects of its behavior. The main way to work with these properties is through the handle.

There are two main approaches: the older get and set functions, and the newer dot notation. Both operate on handles, but dot notation is usually simpler and more readable.

If you have a line handle hLine, you can list its properties with:

get(hLine)

MATLAB prints all property names and their current values. To get a specific property, provide the property name:

currentColor = get(hLine, 'Color');

To change a property, use set:

set(hLine, 'LineWidth', 2);

Dot notation is shorter and more common in recent code. The previous two commands become:

currentColor = hLine.Color;
hLine.LineWidth = 2;

The property names you see from get correspond to field names you use after the dot. This pattern applies to other object types as well:

hFig = gcf;
hFig.Color = [1 1 1];     % white figure background
hAx = gca;
hAx.FontSize = 14;        % larger axes font
hAx.XLim = [0 10];        % change x-axis limits

You can also set multiple properties in one statement with set:

set(hLine, 'Color', 'r', 'LineStyle', '--', 'Marker', 'o');

With dot notation, you simply write multiple assignments on separate lines.

Object Hierarchy and Parent–Child Relationships

Graphics objects are organized in a hierarchy. At the top is the figure. Inside the figure you typically have one or more axes. Inside each axes you have child objects such as lines, images, surfaces, text, and patches. Each object has a Parent property that points to the object above it in the hierarchy, and many objects also have a Children property that stores handles to the objects below.

For example, suppose you create a standard plot:

plot(1:10, rand(1,10));

The line you see has a parent axes. That axes has a parent figure. You can examine this:

hLine = findobj(gca, 'Type', 'line');
hAx   = hLine.Parent;
hFig  = hAx.Parent;

Here, hLine.Parent returns the axes that contains the line. Then hAx.Parent returns the figure that contains the axes. The hierarchy lets you reason about where an object lives and how it inherits some behavior from its parents.

You can also inspect the children of a figure or axes. For a figure, Children usually returns a list of axes and other top level components:

hFig = gcf;
figChildren = hFig.Children;

For an axes, Children returns its plot objects, such as lines and text:

hAx = gca;
axChildren = hAx.Children;

The order in Children is often the reverse of the plotting order, with the most recently created child at the beginning. Understanding this hierarchy is important when you want to apply changes to many objects at once, or when you need to find a particular object programmatically.

Working Programmatically with Graphics Objects

Once you understand handles and the graphics hierarchy, you can start to control your graphics programmatically. Instead of manually clicking and editing in the figure window, you use code that inspects and changes properties. This is useful for automation and reproducibility.

Suppose you have several lines on the same axes and you want to set their line widths and colors based on some rule. You can get all line handles and then work with them as a group:

x = 0:0.1:2*pi;
plot(x, sin(x), x, cos(x), x, sin(2*x));
hLines = findobj(gca, 'Type', 'line');
for k = 1:numel(hLines)
    hLines(k).LineWidth = 1 + 0.5*k;
end

Because all lines are of the same object type, you can treat them like elements of an array and set properties for each element inside a loop.

You can also use logical or numeric indexing if you store handles in your own arrays. For example:

h1 = plot(x, sin(x));
hold on
h2 = plot(x, cos(x));
h3 = plot(x, sin(2*x));
hold off
hAll = [h1 h2 h3];
hAll(1:2).Color = 'k';   % set first two to black
hAll(3).Color   = 'r';   % third to red

Each element of hAll is a handle. MATLAB supports setting the same property for several elements at once as long as they share that property. This style of programming is a key advantage of handle graphics, especially when you scale up to more complex figures.

Handle Lifetime and Validity

A handle is only valid while its corresponding graphics object exists. If you close a figure, all the objects in that figure are destroyed and their handles become invalid. If you try to use one of these handles later, MATLAB will report an error.

You can test whether a handle is still valid with the isvalid function:

hFig = figure;
isvalid(hFig)    % returns true
close(hFig);
isvalid(hFig)    % now returns false

Because handles are references, copying them into multiple variables does not create new objects. All those variables point to the same underlying graphics object. If you change a property through one variable, the change is visible through all other variables that hold that handle, and in the figure window as well.

Handle Graphics and Interactive Editing

While you can edit graphics interactively using tools in the figure window, handle graphics gives you a precise and reproducible way to make the same changes. Any action you perform interactively, such as changing line colors or axis limits, corresponds to setting properties on the underlying graphics objects.

A nice workflow is to experiment interactively to find settings you like, then inspect object properties using gca, gcf, get, or the Property Inspector in the figure window, and finally write code that sets the same properties through handles. Over time, this approach helps you move from manual figure editing to fully automated, script-driven visualizations.