Next: , 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 (see 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. 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 (h, "prop")

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

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

See also: get, set, ismethod, isobject.