Graphics Handles Are Now Objects, Not Doubles

Graphics Handles Are Object Handles

In previous releases, graphics handles are numeric handles of type double. Starting in R2014b, graphics handles are object handles of various types, depending on the class of the graphics object. Graphics objects now behave like other MATLAB® objects.

Most code written for numeric handles still works with object handles. For example, you can access graphics object properties and you can combine graphics objects into arrays, even if the objects belong to different classes. However, you should not perform operations that assume or require graphics handles to be numeric values, such as:

  • Perform arithmetic operations on handles

  • Use handles directly in logical statements without converting to a logical value

  • Rely on the numeric values of the root object (0) or figure handles (integers) in logical statements

  • Combine handles with data in numeric arrays

  • Use any program logic that depends on handles being numeric

  • Converting handles to character vectors or use handles in character vector operations

Accessing Properties of Graphics Objects

There are two ways to access properties of graphics objects that have object handles:

  • Use dot notation to refer to a particular object and property. Property names are case sensitive when using dot notation. For example, this code sets the Color property of a line to 'red'.

    h = plot(1:10);
    h.Color = 'red';

  • Use the set and get functions to access properties for an array of objects. For example, this code sets the LineWidth property for multiple lines.

    h = plot(rand(4));

Graphics Handle Arrays

Starting in R2014b, preallocate arrays of graphics handles using the gobjects function instead of the zeros or ones function. Preallocating with zeros or ones still runs without error, but can be slow.

The syntax for gobjects is the same as the syntax for ones and zeros.

h = gobjects(3,1); % preallocate
h(1) = figure;
h(2) = plot(1:10);
h(3) = gca;
You can combine graphics handles into arrays even if the handles are different classes. MATLAB casts the array to a common base class.
ans =

Testing Validity of Graphics Handles

Starting in R2014b, test the validity of graphics handles using the isgraphics function instead of ishghandle.

x = 1:10;
y = sin(x);

p = plot(x,y);
ax = gca;
ans =

     1     1 

Referring to Figures by Integer Handles

Starting in R2014b, you can refer to a figure by either its object handle or its integer handle. The integer handle is the value in the new Number property of the figure.

h = figure; % object handle
fignum = h.Number; % integer handle
The integer handle, fignum, is a valid figure handle.
isgraphics(fignum) % test handle validity
ans =


Deleting Multiple Graphics Objects

Starting in R2014b, the delete function accepts only one input argument. To delete multiple graphics objects, pass a single handle array to the function, instead of using multiple arguments.

h1 = annotation('line');
h2 = annotation('ellipse');
h3 = annotation('rectangle');

Logical Expressions with Graphics Handles

Starting in R2014b, you cannot use graphics handles in logical expressions or rely on MATLAB to return a nonzero value or an empty double []. Use functions such as isempty, isgraphics, and isequal instead.

  • To determine if there are existing figures, use isempty. The new groot command references the root object.

    if ~isempty(get(groot,'CurrentFigure'))
        disp('There are existing figures.')
        disp('There are no existing figures.')

  • To determine if there are graphics objects with a certain tag, use isempty.

    if ~isempty(findobj('Tag','myFigures'))
        disp('There are objects with this tag.')
        disp('There are no objects with this tag.')

  • To determine if a handle is a valid figure handle, use isgraphics and the object Type.

    if isgraphics(h,'figure')
        disp('h is a valid figure handle.')
        disp('h is not a valid figure handle.')

  • To determine if a handle is the root handle, use the new groot command.

    if isequal(h,groot)
        disp('h is the root handle')
        disp('h is not the root handle')

Converting Cell Arrays of Graphics Handles

Starting in R2014b, you cannot use cell2mat on a cell array of graphics handles to create a numeric array. Create an object array from the cell array instead.

p = plot(magic(3));
par = get(p,'Parent');
objarray = [par{:}]';
whos objarray
  Name          Size            Bytes  Class   Attributes

  objarray      3x1             128 

Testing Equality of Graphics Handles

Starting in R2014b, test the equality of graphics handles using == or isequal.

  • To determine if handles reference the same object, therefore, are the same handle, use ==.

    p1 = plot(1:10);
    p2 = p1;
    p2 == p1
    ans =

  • To determine if handles refer to objects of the same class with the same property values, but are not necessarily the same object, use isequal.

    l1 = line;
    l2 = line;
    ans =

Returning Graphics Objects From cellfun and arrayfun Functions

To use the cellfun and arrayfun functions to return graphics objects, set UniformOutput to false.

For example:

t = num2str(rand);
fh = @(t) text(1,1,t);
th = cellfun(fh,{t},'UniformOutput',false); 

Saving Graphics Objects

Starting in R2014b, if you save a graphics object in a MAT-file using the save function, then the MAT-file contains all the information required to regenerate the object. In previous releases, the save function stores the object as a double and you cannot regenerate the object when you load the MAT-file.

Avoid saving figures with the save function. Using save to save a figure in R2014b or later makes the MAT-file inaccessible in earlier versions of MATLAB. If you use save to save a figure, then the function displays warning message. Save figures using the savefig function instead.

Writing MEX-Files

If you write MEX-files or build engine applications, then the mexGet and mexSet functions do not work on graphic object handles. Use the mxGetProperty and mxSetProperty functions in the C/C++ or Fortran Matrix Library instead.