Introduction to Graphics Structures (GNU Octave (version 11.2.0))

#### 15.3.1 Introduction to Graphics Structures ¶

The graphics functions use pointers, which are of class graphics_handle, in order to address the data structures which control visual display. A graphics handle may point to any one of a number of different base object types. These objects are the graphics data structures themselves. The primitive graphic object types are: `figure`, `axes`, `line`, `text`, `patch`, `scatter`, `surface`, `text`, `image`, and `light`.

Each of these objects has a function by the same name, and each of these functions returns a graphics handle pointing to an object of the corresponding type.

In addition, there are several functions which operate on properties of the graphics objects and which also return handles. This includes but is not limited to the following functions: The functions `plot` and `plot3` return a handle pointing to an object of type `line`. The function `subplot` returns a handle pointing to an object of type `axes`. The functions `fill`, `fill3`, `trimesh`, and `trisurf` return a handle pointing to an object of type patch. The function `scatter3` returns a handle to an object of type scatter. The functions `slice`, `surf`, `surfl`, `mesh`, `meshz`, `pcolor`, and `waterfall` each return a handle of type surface. The function `camlight` returns a handle to an object of type light. The functions `area`, `bar`, `barh`, `contour`, `contourf`, `contour3`, `surfc`, `meshc`, `errorbar`, `quiver`, `quiver3`, `stair`, `stem`, `stem3` each return a handle to a complex data structure as documented in Data Sources.

The graphics objects are arranged in a hierarchy:

1. The root object is returned by `groot` (historically, equivalent to the handle 0). In other words, `get (groot)` returns the properties of the root object.

2. Below the root are `figure` objects.

3. Below the `figure` objects are `axes` or `hggroup` objects.

4. Below the `axes` or `hggroup` objects are `line`, `text`, `patch`, `scatter`, `surface`, `image`, and `light` objects.

It is possible to walk this hierarchical tree by querying the `"parent"` and `"children"` properties of the graphics objects.

Graphics handles may be distinguished from function handles (see Function Handles) by means of the function `ishghandle`. `ishghandle` returns true if its argument is a handle of a graphics object. In addition, a figure or axes object may be tested using `isfigure` or `isaxes` respectively. To test for a specific type of graphics handle, such as a patch or line object, use `isgraphics`. The more specific test functions return true only if the argument is both a graphics handle and of the correct type (figure, axes, specified object type).

The `get` and `set` commands are used to obtain and set the values of properties of graphics objects. In addition, the `get` command may be used to obtain property names.

For example, the property `"type"` of the graphics object pointed to by the graphics handle h may be displayed by:

    get (h, "type")

The properties and their current values may be obtained in the form of a structure using `s = get (h)`, where `h` is the handle of a graphics object. If only the names of the properties and the allowed values (for radio properties only) are wanted, one may use `set (h)`.

Thus, for example:

    h = figure ();
    get (h, "type")
    ⇒  ans = figure
    set (h)
    ⇒
            alphamap:
            beingdeleted:  [ {off} | on ]
            busyaction:  [ cancel | {queue} ]
            buttondownfcn:
            clipping:  [ off | {on} ]
            closerequestfcn:
            color:
            colormap:
            createfcn:
            currentaxes:
            deletefcn:
            dockcontrols:  [ {off} | on ]
            filename:
            graphicssmoothing:  [ off | {on} ]
            handlevisibility:  [ callback | off | {on} ]
            ...

The uses of `get` and `set` are further explained in get, set.

`res =` isprop `(obj, "prop")` ¶

  Return true if prop is a property of the object obj.

  obj may also be an array of objects in which case res will be a logical array indicating whether each handle has the property prop.

  For plotting, obj is a handle to a graphics object. Otherwise, obj should be an instance of a class. `isprop` reports whether the class defines a property, but `Access` permissions or visibility restrictions (`Hidden = true`) may prevent use by the programmer.

  See also: get, set, properties, ismethod, isobject.