Next: Graphics Object Properties, Previous: Introduction to Graphics Structures, Up: Graphics Data Structures [Contents][Index]
The hierarchy of graphics objects was explained above. See Introduction to Graphics Structures. Here the specific objects are described, and the properties contained in these objects are discussed. Keep in mind that graphics objects are always referenced by handle.
The top level of the hierarchy and the parent of all figure objects.
Use groot to obtain the handle of the root graphics object.
A figure window.
A set of axes. This object is a child of a figure object and may be a parent of line, text, image, patch, surface, or light objects.
A line in two or three dimensions.
Text annotations.
A bitmap image.
A filled polygon, currently limited to two dimensions.
A three-dimensional surface.
A light object used for lighting effects on patches and surfaces.
You can create any graphics object primitive by calling the function of the
same name as the object; In other words, figure, axes,
line, text, image, patch, surface, and
light functions. These fundamental graphic objects automatically become
children of the current axes object as if hold on was in place.
Separately, axes will automatically become children of the current figure
object and figures will become children of the root object.
If this auto-joining feature is not desired then it is important to call
newplot first to prepare a new figure and axes for plotting.
Alternatively, the easier way is to call a high-level graphics routine which
will both create the plot and then populate it with low-level graphics objects.
Instead of calling line, use plot. Or use surf instead of
surface. Or use fill instead of patch.
Create a Cartesian axes object and return a handle to it, or set the current axes to hax.
Called without any arguments, or with property/value pairs, construct a new axes. The optional argument hpar is a graphics handle specifying the parent for the new axes and may be a figure, uipanel, or uitab.
Called with a single axes handle argument hax, the function makes
hax the current axes (as returned by gca). It also makes
the figure which contains hax the current figure (as returned by
gcf). Finally, it restacks the parent object’s children
property so that the axes hax appears before all other axes handles
in the list. This causes hax to be displayed on top of any other axes
objects (Z-order stacking). In addition it restacks any legend or colorbar
objects associated with hax so that they are also visible.
Programming Note: The full list of properties is documented at Axes Properties.
Create a line object from x and y (and possibly z) and insert it in the current axes.
In the standard calling form the data x, y, and z may be
scalars, vectors, or matrices. In the case of matrix inputs, line
will attempt to orient scalars and vectors so the results can be plotted.
This requires that one of the dimensions of the vector match either the
number of rows or the number of columns of the matrix.
In the low-level calling form (50% higher performance) where the data is
specified by name (line ("xdata", x, …)) the data must be
vectors. If no data is specified (line ()) then
x == y = [0, 1].
Multiple property-value pairs may be specified for the line object, but they must appear in pairs.
If called with only property/value pairs then any unspecified properties use their default values as specified on the root object.
If the first argument hax is an axes handle, then plot into this axes,
rather than the current axes returned by gca.
The optional return value h is a graphics handle (or vector of handles) to the line objects created.
Programming Note: The full list of properties is documented at Line Properties.
The function line differs from plot in that line objects are
inserted in to the current axes without first clearing the plot.
Create patch object in the current axes with vertices at locations (x, y) and of color c.
If the vertices are matrices of size MxN then each polygon patch has M vertices and a total of N polygons will be created. If some polygons do not have M vertices use NaN to represent "no vertex". If the z input is present then 3-D patches will be created.
The color argument c can take many forms. To create polygons
which all share a single color use a string value (e.g., "r" for
red), a scalar value which is scaled by caxis and indexed into the
current colormap, or a 3-element RGB vector with the precise TrueColor.
If c is a vector of length N then the ith polygon will have a color
determined by scaling entry c(i) according to caxis and then
indexing into the current colormap. More complicated coloring situations
require directly manipulating patch property/value pairs.
Instead of specifying polygons by matrices x and y, it is
possible to present a unique list of vertices and then a list of polygon
faces created from those vertices. In this case the
"Vertices" matrix will be an Nx2 (2-D patch) or
Nx3 (3-D patch). The MxN "Faces" matrix
describes M polygons having N vertices—each row describes a
single polygon and each column entry is an index into the
"Vertices" matrix to identify a vertex. The patch object
can be created by directly passing the property/value pairs
"Vertices"/verts, "Faces"/faces as
inputs.
Instead of using property/value pairs, any property can be set by passing a structure propstruct with the respective field names.
If the first argument hax is an axes handle, then plot into this axes,
rather than the current axes returned by gca.
The optional return value h is a graphics handle to the created patch object.
Programming Note: The full list of properties is documented at
Patch Properties. Useful patch properties include:
"cdata", "edgecolor", "facecolor", "faces",
and "facevertexcdata".
Create a surface graphic object given matrices x and y from
meshgrid and a matrix of values z corresponding to the
x and y coordinates of the surface.
If x and y are vectors, then a typical vertex is
(x(j), y(i), z(i,j)). Thus, columns of z correspond
to different x values and rows of z correspond to different
y values. If only a single input z is given then x is
taken to be 1:columns (z) and y is
1:rows (z).
Any property/value input pairs are assigned to the surface object.
If the first argument hax is an axes handle, then plot into this axes,
rather than the current axes returned by gca.
The optional return value h is a graphics handle to the created surface object.
Programming Note: The full list of properties is documented at Surface Properties.
Create a light object in the current axes or for axes hax.
When a light object is present in an axes object, and the properties
"EdgeLighting" or "FaceLighting" of a patch or
surface object are set to a value other than "none", these
objects are drawn with lighting effects. Supported values for Lighting
properties are "none" (no lighting effects), "flat" (faceted
look of the objects), and "gouraud" (linear interpolation of the
lighting effects between the vertices). If the lighting mode is set to
"flat", the "FaceNormals" property is used for lighting.
For "gouraud", the "VertexNormals" property is used.
Up to eight light objects are supported per axes. (Implementation dependent)
Lighting is only supported for OpenGL graphic toolkits (i.e., "fltk"
and "qt").
A light object has the following properties which alter the appearance of the plot.
"Color": The color of the light can be passed as anRGB-vector (e.g., [1 0 0] for red) or as a string (e.g., "r"
for red). The default color is white ([1 1 1]).
"Position": The direction from which the light emanates as a1x3-vector. The default direction is [1 0 1].
"Style": This string defines whether the light emanates from alight source at infinite distance ("infinite") or from a local point
source ("local"). The default is "infinite".
If the first argument hax is an axes handle, then add the light object
to this axes, rather than the current axes returned by gca.
The optional return value h is a graphics handle to the created light object.
Programming Note: The full list of properties is documented at Light Properties.
To determine whether a variable is a graphics object index, or an index
to an axes or figure, use the functions ishghandle, isgraphics,
isaxes, and isfigure.
Return true if h is a graphics handle and false otherwise.
h may also be a matrix of handles in which case a logical array is returned that is true where the elements of h are graphics handles and false where they are not.
See also: isgraphics, isaxes, isfigure, ishandle.
Return true if h is a graphics handle (of type type) and false otherwise.
When no type is specified the function is equivalent to
ishghandle.
See also: ishghandle, ishandle, isaxes, isfigure.
Return true if h is a handle to a graphics or Java object and false otherwise.
h may also be a matrix of handles in which case a logical array is returned that is true where the elements of h are handles to graphics or Java objects and false where they are not.
Programming Note: It is often more useful to test for a specific object
type. To determine if a handle belongs to a graphics object use
ishghandle or isgraphics. To determine if a handle belongs
to a Java object use isjava.
See also: ishghandle, isgraphics, isjava.
Return true if h is an axes graphics handle and false otherwise.
If h is a matrix then return a logical array which is true where the elements of h are axes graphics handles and false where they are not.
See also: isfigure, ishghandle, isgraphics.
Return true if h is a figure graphics handle and false otherwise.
If h is a matrix then return a logical array which is true where the elements of h are figure graphics handles and false where they are not.
See also: isaxes, ishghandle, isgraphics.
The function gcf returns an index to the current figure object,
or creates one if none exists. Similarly, gca returns the
current axes object, or creates one (and its parent figure object) if
none exists.
Return a handle to the root graphics object.
The root graphics object is the ultimate parent of all graphics objects.
In addition, the root object contains information about the graphics
system as a whole such as the ScreenSize. Use get (groot)
to find out what information is available.
Defaults for the graphic system as a whole are specified by setting
properties of the root graphics object that begin with "Default".
For example, to set the default font for all text objects to FreeSans use
set (groot, "DefaultTextFontName", "FreeSans")
Default properties can be deleted by using set with the special
property value of "remove". To undo the default font assignment
above use
set (groot, "DefaultTextFontName", "remove")
Programming Note: The root graphics object is identified by the special
handle value of 0. At some point this unique value may change, but code can
be made resistant to future changes by using groot which is
guaranteed to always return the root graphics object.
Return a handle to the current figure.
The current figure is the default target for graphics output. If multiple
figures exist, gcf returns the last created figure or the last figure
that was clicked on with the mouse.
If a current figure does not exist, create one and return its handle. The handle may then be used to examine or set properties of the figure. For example,
fplot (@sin, [-10, 10]); fig = gcf (); set (fig, "numbertitle", "off", "name", "sin plot")
plots a sine wave, finds the handle of the current figure, and then renames the figure window to describe the contents.
Note: To find the current figure without creating a new one if it does not
exist, query the "CurrentFigure" property of the root graphics
object.
get (groot, "currentfigure");
Return a handle to the current axes object.
The current axes is the default target for graphics output. In the case
of a figure with multiple axes, gca returns the last created axes
or the last axes that was clicked on with the mouse.
If no current axes object exists, create one and return its handle. The handle may then be used to examine or set properties of the axes. For example,
ax = gca (); set (ax, "position", [0.5, 0.5, 0.5, 0.5]);
creates an empty axes object and then changes its location and size in the figure window.
Note: To find the current axes without creating a new axes object if it
does not exist, query the "CurrentAxes" property of a figure.
get (gcf, "currentaxes");
Return a handle to the current object of the current figure, or a handle to the current object of the figure with handle fig.
The current object of a figure is the object that was last clicked on. It
is stored in the "CurrentObject" property of the target figure.
If the last mouse click did not occur on any child object of the figure, then the current object is the figure itself.
If no mouse click occurred in the target figure, this function returns an empty matrix.
Programming Note: The value returned by this function is not necessarily the
same as the one returned by gcbo during callback execution. An
executing callback can be interrupted by another callback and the current
object may be changed.
The get and set functions may be used to examine and set
properties for graphics objects. For example,
get (groot)
⇒ ans =
{
type = root
currentfigure = [](0x0)
children = [](0x0)
visible = on
…
}
returns a structure containing all the properties of the root graphics object.
As with all functions in Octave, the structure is returned by value, so
modifying it will not modify the internal root object. To do that, you must
use the set function. Also, note that in this case, the
currentfigure property is empty, which indicates that there is no
current figure window.
The get function may also be used to find the value of a single
property. For example,
get (gca (), "xlim")
⇒ [ 0 1 ]
returns the range of the x-axis for the current axes object in the current figure.
To set graphics object properties, use the set function. For example,
set (gca (), "xlim", [-10, 10]);
sets the range of the x-axis for the current axes object in the current figure to ‘[-10, 10]’.
Default property values can also be queried if the set function is
called without a value argument. When only one argument is given (a graphic
handle) then a structure with defaults for all properties of the given object
type is returned. For example,
set (gca ())
returns a structure containing the default property values for axes objects.
If set is called with two arguments (a graphic handle and a property
name) then only the defaults for the requested property are returned.
Return the value of the named property p from the graphics handle h.
If p is omitted, return the complete property list for h.
If h is a vector, return a cell array including the property values or lists respectively.
See also: set.
Set named property values for the graphics handle (or vector of graphics handles) h.
There are three ways to give the property names and values:
Here, each property is a string containing the property name, each value is a value of the appropriate type for the property.
In this case, the number of columns of values must match the number of elements in properties. The first column of values contains values for the first entry in properties, etc. The number of rows of values must be 1 or match the number of elements of h. In the first case, each handle in h will be assigned the same values. In the latter case, the first handle in h will be assigned the values from the first row of values and so on.
Here, the field names of pv represent the property names, and the field values give the property values. In contrast to the previous case, all elements of pv will be set in all handles in h independent of the dimensions of pv.
set is also used to query the list of values a named property will
take. clist = set (h, "property") will return the list
of possible values for "property" in the cell list clist.
If no output variable is used then the list is formatted and printed to the
screen.
If no property is specified (slist = set (h)) then a
structure slist is returned where the fieldnames are the properties of
the object h and the fields are the list of possible values for each
property. If no output variable is used then the list is formatted and
printed to the screen.
For example,
hf = figure ();
set (hf, "paperorientation")
⇒ [ landscape | {portrait} ]
shows the paperorientation property can take two values with the default
being "portrait".
See also: get.
Return the first ancestor of handle object h whose type matches type, where type is a character string.
If type is a cell array of strings, return the first parent whose type matches any of the given type strings.
If the handle object h itself is of type type, return h.
If "toplevel" is given as a third argument, return the highest
parent in the object hierarchy that matches the condition, instead
of the first (nearest) one.
Find all children, including hidden children, of a graphics object.
This function is similar to get (h, "children"), but also returns
hidden objects (HandleVisibility = "off").
If handles is a scalar, h will be a vector. Otherwise, h will be a cell matrix of the same size as handles and each cell will contain a vector of handles.
Find all visible figures that are currently off the screen and move them onto the screen.
Figures can be printed or saved in many graphics formats with print and
saveas. Occasionally, however, it may be useful to save the original
Octave handle graphic directly so that further modifications can be made such
as modifying a title or legend.
This can be accomplished with the following functions by
fig_struct = hdl2struct (gcf);
save myplot.fig -struct fig_struct;
…
fig_struct = load ("myplot.fig");
struct2hdl (fig_struct);
Return a structure, s, whose fields describe the properties of the object, and its children, associated with the handle, h.
The fields of the structure s are "type", "handle",
"properties", "children", and "special".
See also: struct2hdl, hgsave, findobj.
Construct a graphics handle object h from the structure s.
The structure must contain the fields "handle", "type",
"children", "properties", and "special".
If the handle of an existing figure or axes is specified, p, the new object will be created as a child of that object. If no parent handle is provided then a new figure and the necessary children will be constructed using the default values from the root object.
A third boolean argument hilev can be passed to specify whether the function should preserve listeners/callbacks, e.g., for legends or hggroups. The default is false.
See also: hdl2struct, hgload, findobj.
Construct a copy of the graphic objects associated with the handles horig and return new handles hnew to the new objects.
If a parent handle hparent (root, figure, axes, or hggroup) is specified, the copied object will be created as a child of hparent.
If horig is a vector of handles, and hparent is a scalar,
then each handle in the vector hnew has its "Parent" property
set to hparent. Conversely, if horig is a scalar and
hparent a vector, then each parent object will receive a copy of
horig. If horig and hparent are both vectors with the
same number of elements then hnew(i) will have parent
hparent(i).
See also: struct2hdl, hdl2struct, findobj.
Next: Graphics Object Properties, Previous: Introduction to Graphics Structures, Up: Graphics Data Structures [Contents][Index]