Introduction to Graphics Structures - GNU Octave
Description: GNU Octave

Next: Graphics Objects, Up: Graphics Data Structures

#### 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 graphical displays. A graphics handle may point any one of a number of different object types. The objects are the graphics data structures. The types of objects 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 corresponding type. In addition there are several functions which operate on properties of the graphics objects and which 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 as documented in Data Sources.

The graphics objects are arranged in a hierarchy:

1. The root is at 0. i.e., `get (0)` returns the properties of the root object.

2. Below the root are `figure` objects.

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

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

Graphics handles may be distinguished from function handles (Function Handles) by means of the function `ishandle`. `ishandle` returns true if its argument is a handle of a graphics object. In addition, the figure object may be tested using `isfigure`. `isfigure` returns true only if its argument is a handle of a figure. ishghandle() is synonymous with ishandle(). 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:

         __graphics_toolkit__  hittest              resize
         __enhanced__          integerhandle        resizefcn
         __modified__          interruptible        selected
         __myhandle__          inverthardcopy       selectionhighlight
         __plot_stream__       keypressfcn          selectiontype
         alphamap              keyreleasefcn        tag
         beingdeleted          menubar              toolbar
         busyaction            mincolormap          type
         buttondownfcn         name                 uicontextmenu
         children              nextplot             units
         clipping              numbertitle          userdata
         closerequestfcn       paperorientation     visible
         color                 paperposition        windowbuttondownfcn
         colormap              paperpositionmode    windowbuttonmotionfcn
         createfcn             papersize            windowbuttonupfcn
         currentaxes           papertype            windowbuttonwheelfcn
         currentcharacter      paperunits           windowstyle
         currentobject         parent               wvisual
         currentpoint          pointer              wvisualmode
         deletefcn             pointershapecdata    xdisplay
         dockcontrols          pointershapehotspot  xvisual
         doublebuffer          position             xvisualmode
         filename              renderer
         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 (h, prop)

> Return true if prop is a property of the object with handle h.

> See also: get, set.