15.3.2.2 Handle Functions

To determine whether a variable is a graphics object index, or an index to an axes or figure, use the functions ishghandle, isgraphics, isaxes, and isfigure.

tf = ishghandle (h) ¶

Return true if h is a graphics handle and false otherwise.

h may also be a matrix of handles in which case a logical array is returned that is true where the elements of h are graphics handles and false where they are not.

See also: isgraphics, isaxes, isfigure, ishandle.

tf = isgraphics (h) ¶

tf = isgraphics (h, type) ¶

Return true if h is a graphics handle (of type type) and false otherwise.

When no type is specified the function is equivalent to ishghandle.

See also: ishghandle, ishandle, isaxes, isfigure.

tf = ishandle (h) ¶

Return true if h is a handle to a graphics or Java object and false otherwise.

h may also be a matrix of handles in which case a logical array is returned that is true where the elements of h are handles to graphics or Java objects and false where they are not.

Programming Note: It is often more useful to test for a specific object type. To determine if a handle belongs to a graphics object use ishghandle or isgraphics. To determine if a handle belongs to a Java object use isjava.

See also: ishghandle, isgraphics, isjava.

tf = isaxes (h) ¶

Return true if h is an axes graphics handle and false otherwise.

If h is a matrix then return a logical array which is true where the elements of h are axes graphics handles and false where they are not.

See also: isfigure, ishghandle, isgraphics.

tf = isfigure (h) ¶

Return true if h is a figure graphics handle and false otherwise.

If h is a matrix then return a logical array which is true where the elements of h are figure graphics handles and false where they are not.

See also: isaxes, ishghandle, isgraphics.

The function gcf returns an index to the current figure object, or creates one if none exists. Similarly, gca returns the current axes object, or creates one (and its parent figure object) if none exists.

h = groot () ¶

Return a handle to the root graphics object.

The root graphics object is the ultimate parent of all graphics objects.

In addition, the root object contains information about the graphics system as a whole such as the ScreenSize. Use get (groot) to find out what information is available.

Defaults for the graphic system as a whole are specified by setting properties of the root graphics object that begin with "Default". For example, to set the default font for all text objects to FreeSans use

set (groot, "DefaultTextFontName", "FreeSans")

Default properties can be deleted by using set with the special property value of "remove". To undo the default font assignment above use

set (groot, "DefaultTextFontName", "remove")

Programming Note: The root graphics object is identified by the special handle value of 0. At some point this unique value may change, but code can be made resistant to future changes by using groot which is guaranteed to always return the root graphics object.

See also: gcf, gca, get, set.

h = gcf () ¶

Return a handle to the current figure.

The current figure is the default target for graphics output. If multiple figures exist, gcf returns the last created figure or the last figure that was clicked on with the mouse.

If a current figure does not exist, create one and return its handle. The handle may then be used to examine or set properties of the figure. For example,

fplot (@sin, [-10, 10]);
fig = gcf ();
set (fig, "numbertitle", "off", "name", "sin plot")

plots a sine wave, finds the handle of the current figure, and then renames the figure window to describe the contents.

Note: To find the current figure without creating a new one if it does not exist, query the "CurrentFigure" property of the root graphics object.

get (groot, "currentfigure");

See also: gca, gco, gcbf, gcbo, get, set.

h = gca () ¶

Return a handle to the current axes object.

The current axes is the default target for graphics output. In the case of a figure with multiple axes, gca returns the last created axes or the last axes that was clicked on with the mouse.

If no current axes object exists, create one and return its handle. The handle may then be used to examine or set properties of the axes. For example,

ax = gca ();
set (ax, "position", [0.5, 0.5, 0.5, 0.5]);

creates an empty axes object and then changes its location and size in the figure window.

Note: To find the current axes without creating a new axes object if it does not exist, query the "CurrentAxes" property of a figure.

get (gcf, "currentaxes");

See also: gcf, gco, gcbf, gcbo, get, set.

h = gco () ¶

h = gco (hfig) ¶

Return a handle to the current object of the current figure, or a handle to the current object of the figure with handle hfig.

The current object of a figure is the object that was last clicked on. It is stored in the "CurrentObject" property of the target figure.

If the last mouse click did not occur on any child object of the figure, then the current object is the figure itself.

If no mouse click occurred in the target figure, this function returns an empty matrix.

Programming Note: The value returned by this function is not necessarily the same as the one returned by gcbo during callback execution. An executing callback can be interrupted by another callback and the current object may be changed.

See also: gcbo, gca, gcf, gcbf, get, set.

The get and set functions may be used to examine and set properties for graphics objects. For example,

get (groot)
    ⇒ ans =
       {
         type = root
         currentfigure = [](0x0)
         children = [](0x0)
         visible = on
         …
       }

returns a structure containing all the properties of the root graphics object. As with all functions in Octave, the structure is returned by value, so modifying it will not modify the internal root object. To do that, you must use the set function. Also, note that in this case, the currentfigure property is empty, which indicates that there is no current figure window.

The get function may also be used to find the value of a single property. For example,

get (gca (), "xlim")
    ⇒ [ 0 1 ]

returns the range of the x-axis for the current axes object in the current figure.

To set graphics object properties, use the set function. For example,

set (gca (), "xlim", [-10, 10]);

sets the range of the x-axis for the current axes object in the current figure to ‘[-10, 10]’.

Default property values can also be queried if the set function is called without a value argument. When only one argument is given (a graphic handle) then a structure with defaults for all properties of the given object type is returned. For example,

set (gca ())

returns a structure containing the default property values for axes objects. If set is called with two arguments (a graphic handle and a property name) then only the defaults for the requested property are returned.

val = get (h) ¶

val = get (h, p) ¶

Return the value of the named property p from the graphics handle h.

If p is omitted, return the complete property list for h.

If h is a vector, return a cell array including the property values or lists respectively.

See also: set.

set (h, property, value, …) ¶

set (h, {properties}, {values}) ¶

set (h, pv) ¶

value_list = set (h, property) ¶

all_value_list = set (h) ¶

Set named property values for the graphics handle (or vector of graphics handles) h.

There are three ways to give the property names and values:

• as a comma-separated list of property, value pairs

  Each property is a string containing the property name, each value is a value of the appropriate type for the property. When there are multiple handles in h, each one is assigned the same value. For example:

  h = plot ([0, 1]);
  set (h, 'color', 'green');
  

• as a cell array of strings properties containing property names and a cell array values containing property values.

  In this case, the number of columns of values must match the number of elements in properties. The first column of values contains values for the first entry in properties, etc. The number of rows of values must be 1 or match the number of elements of h. In the first case, each handle in h will be assigned the same values. In the second case, the first handle in h will be assigned the values from the first row of values and so on. For example:

  h = plot ([0, 1; 1, 0]);
  set (h, {'color'}, {'green'; 'red'});
  

• as a structure pv

  This is the same as the first case where the field names of pv represent the property names, and the field values give the property values. As with the first case, it is only possible to set one value for a property which will be applied to all handles in h. For example:

  h = plot ([0, 1]);
  props.color = 'green';
  set (h, props);
  

The three syntaxes for setting properties may appear in any combination.

set is also used to query the list of values a named property will take. clist = set (h, "property") will return the list of possible values for "property" in the cell list clist. If no output variable is used then the list is formatted and printed to the screen.

If no property is specified (slist = set (h)) then a structure slist is returned where the fieldnames are the properties of the object h and the fields are the list of possible values for each property. If no output variable is used then the list is formatted and printed to the screen.

When querying properties only a single graphics handle h for a single graphics object is permitted.

Example Query

hf = figure ();
set (hf, "paperorientation")
⇒  [ landscape | {portrait} ]

shows the paperorientation property can take two values with the default being "portrait".

See also: get.

parent = ancestor (h, type) ¶

parent = ancestor (h, type, "toplevel") ¶

Return the first ancestor of handle object h whose type matches type, where type is a character string.

If type is a cell array of strings, return the first parent whose type matches any of the given type strings.

If the handle object h itself is of type type, return h.

If "toplevel" is given as a third argument, return the highest parent in the object hierarchy that matches the condition, instead of the first (nearest) one.

See also: findobj, findall, allchild.

h = allchild (handles) ¶

Find all children, including hidden children, of a graphics object.

This function is similar to get (h, "children"), but also returns hidden objects (HandleVisibility = "off").

If handles is a scalar, h will be a vector. Otherwise, h will be a cell matrix of the same size as handles and each cell will contain a vector of handles.

See also: findall, findobj, get, set.

findfigs () ¶

Find all visible figures that are currently off the screen and move them onto the screen.

See also: allchild, figure, get, set.

Figures can be printed or saved in many graphics formats with print and saveas. Occasionally, however, it may be useful to save the original Octave handle graphic directly so that further modifications can be made such as modifying a title or legend.

This can be accomplished with the following functions by

fig_struct = hdl2struct (gcf);
save myplot.fig -struct fig_struct;
…
fig_struct = load ("myplot.fig");
struct2hdl (fig_struct);

s = hdl2struct (h) ¶

Return a structure, s, whose fields describe the properties of the object, and its children, associated with the handle, h.

The fields of the structure s are "type", "handle", "properties", "children", and "special".

See also: struct2hdl, hgsave, findobj.

h = struct2hdl (s) ¶

h = struct2hdl (s, p) ¶

h = struct2hdl (s, p, hilev) ¶

Construct a graphics handle object h from the structure s.

The structure must contain the fields "handle", "type", "children", "properties", and "special".

If the handle of an existing figure or axes is specified, p, the new object will be created as a child of that object. If no parent handle is provided then a new figure and the necessary children will be constructed using the default values from the root object.

A third boolean argument hilev can be passed to specify whether the function should preserve listeners/callbacks, e.g., for legends or hggroups. The default is false.

See also: hdl2struct, hgload, findobj.

hnew = copyobj (horig) ¶

hnew = copyobj (horig, hparent) ¶

Construct a copy of the graphic objects associated with the handles horig and return new handles hnew to the new objects.

If a parent handle hparent (root, figure, axes, or hggroup) is specified, the copied object will be created as a child of hparent.

If horig is a vector of handles, and hparent is a scalar, then each handle in the vector hnew has its "Parent" property set to hparent. Conversely, if horig is a scalar and hparent a vector, then each parent object will receive a copy of horig. If horig and hparent are both vectors with the same number of elements then hnew(i) will have parent hparent(i).

See also: struct2hdl, hdl2struct, findobj.