GNU Octave: Introduction to Graphics Structures

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`, and `image`.

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 is at 0. In other words, `get (0)` returns the properties of the root object.

2. Below the root are `figure` objects.

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

4. Below the `axes` objects are `line`, `text`, `patch`, `surface`, and `image` objects.

Graphics handles may be distinguished from function handles (see Function Handles) by means of the function `ishandle`. `ishandle` 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. The test functions return true only if the argument is both a handle and of the correct type (figure or axes).

The `whos` function can be used to show the object type of each currently defined graphics handle. (Note: this is not true today, but it is, I hope, considered an error in whos. It may be better to have whos just show graphics_handle as the class, and provide a new function which, given a graphics handle, returns its object type. This could generalize the ishandle() functions and, in fact, replace them.)

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 are returned by `get (h)` where h is a handle of a graphics object. If only the names of the allowed properties are wanted they may be displayed by: `get (h, "")`.

Thus, for example:

    h = figure ();
    get (h, "type")
    ans = figure
    get (h, "");
    error: get: ambiguous figure property name ; possible matches:

    __enhanced__           hittest                resize
    __graphics_toolkit__   integerhandle          resizefcn
    __guidata__            interruptible          selected
    __modified__           inverthardcopy         selectionhighlight
    __myhandle__           keypressfcn            selectiontype
    __plot_stream__        keyreleasefcn          tag
    alphamap               menubar                toolbar
    beingdeleted           mincolormap            type
    busyaction             name                   uicontextmenu
    buttondownfcn          nextplot               units
    children               numbertitle            userdata
    clipping               outerposition          visible
    closerequestfcn        paperorientation       windowbuttondownfcn
    color                  paperposition          windowbuttonmotionfcn
    colormap               paperpositionmode      windowbuttonupfcn
    createfcn              papersize              windowkeypressfcn
    currentaxes            papertype              windowkeyreleasefcn
    currentcharacter       paperunits             windowscrollwheelfcn
    currentobject          parent                 windowstyle
    currentpoint           pointer                wvisual
    deletefcn              pointershapecdata      wvisualmode
    dockcontrols           pointershapehotspot    xdisplay
    doublebuffer           position               xvisual
    filename               renderer               xvisualmode
    handlevisibility       renderermode

The root figure has index 0. Its properties may be displayed by: `get (0, "")`.

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

Function File: 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]