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

Next: Graphics Objects, Up: Graphics Data Structures [Contents][Index]

#### 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 and these objects are the graphics data structures themselves. The primitive graphic object types are: `figure`, `axes`, `line`, `text`, `patch`, `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: 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 function `fill` returns a handle pointing to an object of type patch, the functions `area`, `bar`, `barh`, `contour`, `contourf`, `contour3`, `surf`, `mesh`, `surfc`, `meshc`, `errorbar`, `quiver`, `quiver3`, `scatter`, `scatter3`, `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` objects are `line`, `text`, `patch`, `surface`, `image`, and `light` 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.

  See also: get, set, ismethod, isobject.

Next: Graphics Objects, Up: Graphics Data Structures [Contents][Index]