Main Content

Prevent Access to Figures and Axes

Why Prevent Access

In some situations it is important to prevent particular figures or axes from becoming the target for graphics output. That is, prevent them from becoming the current figure, as returned by gcf, or the current axes, as returned by gca.

You might want to prevent access to a figure containing the controls that implement a user interface. Or, you might want to prevent access to an axes that is part of an application program accessed only by the application.

How to Prevent Access

Prevent MATLAB® functions from targeting a particular figure or axes by removing their handles from the list of visible handles.

Two properties control handle visibility: HandleVisibility and ShowHiddenHandles

HandleVisibility is a property of all graphics objects. It controls the visibility of the object’s handle to three possible values:

  • 'on' — You can obtain the object's handle with functions that return handles, such as (gcf, gca, gco, get, and findobj). This is the default behavior.

  • 'callback' — The object's handle is visible only within the workspace of a callback function.

  • 'off' — The handle is hidden from all functions executing in the command window and in callback functions.

Properties Affected by Handle Visibility

When an object’s HandleVisibility is set to 'callback' or 'off':

  • The object's handle does not appear in its parent's Children property.

  • Figures do not appear in the root's CurrentFigure property.

  • Axes do not appear in the containing figure's CurrentAxes property.

  • Graphics objects do not appear in the figure's CurrentObject property.

Functions Affected by Handle Visibility

When a handle is not visible in its parent's list of children, functions that obtain handles by searching the object hierarchy cannot return the handle. These functions include get, findobj, gca, gcf, gco, newplot, cla, clf, and close.

Values Returned by gca and gcf

When a hidden-handle figure is topmost on the screen, but has visible-handle figures stacked behind it, gcf returns the topmost visible-handle figure in the stack. The same behavior is true for gca. If no visible-handle figures or axes exist, calling gcf or gca creates one.

Access Hidden-Handle Objects

The root ShowHiddenHandles property enables and disables handle visibility control. By default, ShowHiddenHandles is 'off', which means MATLAB follows the setting of every object’s HandleVisibility property.

Setting ShowHiddenHandles to on is equivalent to setting the HandleVisibility property of all objects in the graphics hierarchy to on.

Note

Axes title and axis label text objects are not children of the axes. To access the handles of these objects, use the axes Title, XLabel, YLabel, and ZLabel properties.

The close function also allows access to hidden-handle figures using the hidden option. For example:

close('hidden')

closes the topmost figure on the screen, even if its handle is hidden.

Combining all and hidden options:

close('all','hidden')

closes all figures.

Handle Validity Versus Handle Visibility

All handles remain valid regardless of the state of their HandleVisibility property. If you have assigned an object handle to a variable, you can always set and get its properties using that handle variable.