Next: Graphics Object Properties, Previous: Introduction to Graphics Structures, Up: Graphics Data Structures

#### 15.3.2 Graphics Objects

The hierarchy of graphics objects was explained above. (See Introduction to Graphics Structures. Here the specific objects are described, and the properties contained in these objects are discussed. Keep in mind that graphics objects are always referenced by handle.

root figure
  the top level of the hierarchy and the parent of all figure objects. The `handle` index of the root figure is 0.
figure
  A figure window.
axes
  A set of axes. This object is a child of a figure object and may be a parent of line, text, image, patch, or surface objects.
line
  A line in two or three dimensions.
text
  Text annotations.
image
  A bitmap image.
patch
  A filled polygon, currently limited to two dimensions.
surface
  A three-dimensional surface.

##### 15.3.2.1 Handle Functions

To determine whether a variable is a graphics object index or a figure index, use the functions `ishandle` and `isfigure`.

— Built-in Function: ishandle (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: isfigure.

— Function File: ishghandle (h)

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

— Function File: isfigure (h)

> Return true if h is a graphics handle that contains a figure object.

> See also: ishandle.

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.

— Function File: gcf ()

> Return the current figure handle. If a 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, "visible", "off");

> plots a sine wave, finds the handle of the current figure, and then makes that figure invisible. Setting the visible property of the figure to `"on"` will cause it to be displayed again.

> See also: get, set.

— Function File: gca ()

> Return a handle to the current axis object. If no axis 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, then changes its location and size in the figure window.

> See also: get, set.

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

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

returns a structure containing all the properties of the root figure. As with all functions in Octave, the structure is returned by value, so modifying it will not modify the internal root figure plot 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]`’. Additionally, calling set with a graphics object index as the only argument returns a structure containing the default values for all the properties for the given object type. For example,

         set (gca ())

returns a structure containing the default property values for axes objects.

— Built-in Function: get (h, p)

> Return 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.

— Built-in Function: set (h, property, value, ...)
— Built-in Function: set (h, properties, values)
— Built-in Function: set (h, pv)

> Set named property values for the graphics handle (or vector of graphics handles) h. There are three ways how to give the property names and values:

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

>   Here, each property is a string containing the property name, each value is a value of the appropriate type for the property.

> - 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 latter case, the first handle in h will be assigned the values from the first row of values and so on.

> - as a structure array pv

>   Here, the field names of pv represent the property names, and the field values give the property values. In contrast to the previous case, all elements of pv will be set in all handles in h independent of the dimensions of pv.

— Function File: parent = ancestor (h, type)
— Function File: 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 is of type type, return h.

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

> See also: get, set.

— Function File: 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. 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: get, set, findall, findobj.