(octave.info)Introduction to Graphics Structures

---

Next: Graphics Objects Up: Graphics Data Structures

---

Enter node , (file) or (file)node

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 Note:
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 (Note:
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 *note get:
XREFget, Note: 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: Note: get, Note: set, *note ismethod:
     XREFismethod, Note: isobject.