Next: , 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 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:

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

The properties of the root figure may be displayed by: get (groot, "").

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: , Up: Graphics Data Structures   [Contents][Index]