<html lang="en">
<head>
<title>Graphics Objects - GNU Octave</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Octave">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Graphics-Data-Structures.html#Graphics-Data-Structures" title="Graphics Data Structures">
<link rel="prev" href="Introduction-to-Graphics-Structures.html#Introduction-to-Graphics-Structures" title="Introduction to Graphics Structures">
<link rel="next" href="Graphics-Object-Properties.html#Graphics-Object-Properties" title="Graphics Object Properties">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Graphics-Objects"></a>
<p>
Next: <a rel="next" accesskey="n" href="Graphics-Object-Properties.html#Graphics-Object-Properties">Graphics Object Properties</a>,
Previous: <a rel="previous" accesskey="p" href="Introduction-to-Graphics-Structures.html#Introduction-to-Graphics-Structures">Introduction to Graphics Structures</a>,
Up: <a rel="up" accesskey="u" href="Graphics-Data-Structures.html#Graphics-Data-Structures">Graphics Data Structures</a>
<hr>
</div>
<h4 class="subsection">15.3.2 Graphics Objects</h4>
<p><a name="index-graphics-objects-1488"></a>
The hierarchy of graphics objects was explained above. (See
<a href="Introduction-to-Graphics-Structures.html#Introduction-to-Graphics-Structures">Introduction to Graphics Structures</a>. 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 <dfn>handle</dfn>.
<dl>
<!-- @group -->
<dt>root figure<dd><a name="index-root-figure-graphics-object-1489"></a><a name="index-graphics-object_002c-root-figure-1490"></a>the top level of the hierarchy and the parent of all figure objects.
The <code>handle</code> index of the root figure is 0.
<br><dt>figure<dd><a name="index-figure-graphics-object-1491"></a><a name="index-graphics-object_002c-figure-1492"></a>A figure window.
<br><dt>axes<dd><a name="index-axes-graphics-object-1493"></a><a name="index-graphics-object_002c-axes-1494"></a>A set of axes. This object is a child of a figure object and may be a
parent of line, text, image, patch, or surface objects.
<br><dt>line<dd><a name="index-line-graphics-object-1495"></a><a name="index-graphics-object_002c-line-1496"></a>A line in two or three dimensions.
<br><dt>text<dd><a name="index-text-graphics-object-1497"></a><a name="index-graphics-object_002c-text-1498"></a>Text annotations.
<br><dt>image<dd><a name="index-image-graphics-object-1499"></a><a name="index-graphics-object_002c-image-1500"></a>A bitmap image.
<br><dt>patch<dd><a name="index-patch-graphics-object-1501"></a><a name="index-graphics-object_002c-patch-1502"></a>A filled polygon, currently limited to two dimensions.
<br><dt>surface<dd><a name="index-surface-graphics-object-1503"></a><a name="index-graphics-object_002c-surface-1504"></a>A three-dimensional surface.
<!-- @end group -->
</dl>
<h5 class="subsubsection">15.3.2.1 Handle Functions</h5>
<p><a name="index-handle-functions-1505"></a>
To determine whether a variable is a graphics object index or a figure
index, use the functions <code>ishandle</code> and <code>isfigure</code>.
<!-- ishandle src/graphics.cc -->
<p><a name="doc_002dishandle"></a>
<div class="defun">
— Built-in Function: <b>ishandle</b> (<var>h</var>)<var><a name="index-ishandle-1506"></a></var><br>
<blockquote><p>Return true if <var>h</var> is a graphics handle and false otherwise.
<var>h</var> may also be a matrix of handles in which case a logical
array is returned that is true where the elements of <var>h</var> are
graphics handles and false where they are not.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002disfigure.html#doc_002disfigure">isfigure</a>.
</p></blockquote></div>
<!-- ishghandle scripts/plot/ishghandle.m -->
<p><a name="doc_002dishghandle"></a>
<div class="defun">
— Function File: <b>ishghandle</b> (<var>h</var>)<var><a name="index-ishghandle-1507"></a></var><br>
<blockquote><p>Return true if <var>h</var> is a graphics handle and false otherwise.
</p></blockquote></div>
<!-- isfigure scripts/plot/isfigure.m -->
<p><a name="doc_002disfigure"></a>
<div class="defun">
— Function File: <b>isfigure</b> (<var>h</var>)<var><a name="index-isfigure-1508"></a></var><br>
<blockquote><p>Return true if <var>h</var> is a graphics handle that contains a figure
object.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dishandle.html#doc_002dishandle">ishandle</a>.
</p></blockquote></div>
<p>The function <code>gcf</code> returns an index to the current figure object,
or creates one if none exists. Similarly, <code>gca</code> returns the
current axes object, or creates one (and its parent figure object) if
none exists.
<!-- gcf scripts/plot/gcf.m -->
<p><a name="doc_002dgcf"></a>
<div class="defun">
— Function File: <b>gcf</b> ()<var><a name="index-gcf-1509"></a></var><br>
<blockquote><p>Return the current figure handle. If a 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,
<pre class="example"> fplot (@sin, [-10, 10]);
fig = gcf ();
set (fig, "visible", "off");
</pre>
<p class="noindent">plots a sine wave, finds the handle of the current figure, and then
makes that figure invisible. Setting the visible property of the
figure to <code>"on"</code> will cause it to be displayed again.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dget.html#doc_002dget">get</a>, <a href="doc_002dset.html#doc_002dset">set</a>.
</p></blockquote></div>
<!-- gca scripts/plot/gca.m -->
<p><a name="doc_002dgca"></a>
<div class="defun">
— Function File: <b>gca</b> ()<var><a name="index-gca-1510"></a></var><br>
<blockquote><p>Return a handle to the current axis object. If no axis object
exists, create one and return its handle. The handle may then be
used to examine or set properties of the axes. For example,
<pre class="example"> ax = gca ();
set (ax, "position", [0.5, 0.5, 0.5, 0.5]);
</pre>
<p class="noindent">creates an empty axes object, then changes its location and size in
the figure window.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dget.html#doc_002dget">get</a>, <a href="doc_002dset.html#doc_002dset">set</a>.
</p></blockquote></div>
<p>The <code>get</code> and <code>set</code> functions may be used to examine and set
properties for graphics objects. For example,
<pre class="example"> get (0)
⇒ ans =
{
type = root
currentfigure = [](0x0)
children = [](0x0)
visible = on
...
}
</pre>
<p class="noindent">returns a structure containing all the properties of the root figure.
As with all functions in Octave, the structure is returned by value, so
modifying it will not modify the internal root figure plot object. To
do that, you must use the <code>set</code> function. Also, note that in this
case, the <code>currentfigure</code> property is empty, which indicates that
there is no current figure window.
<p>The <code>get</code> function may also be used to find the value of a single
property. For example,
<pre class="example"> get (gca (), "xlim")
⇒ [ 0 1 ]
</pre>
<p class="noindent">returns the range of the x-axis for the current axes object in the
current figure.
<p>To set graphics object properties, use the set function. For example,
<pre class="example"> set (gca (), "xlim", [-10, 10]);
</pre>
<p class="noindent">sets the range of the x-axis for the current axes object in the current
figure to ‘<samp><span class="samp">[-10, 10]</span></samp>’. Additionally, calling set with a graphics
object index as the only argument returns a structure containing the
default values for all the properties for the given object type. For
example,
<pre class="example"> set (gca ())
</pre>
<p class="noindent">returns a structure containing the default property values for axes
objects.
<!-- get src/graphics.cc -->
<p><a name="doc_002dget"></a>
<div class="defun">
— Built-in Function: <b>get</b> (<var>h, p</var>)<var><a name="index-get-1511"></a></var><br>
<blockquote><p>Return the named property <var>p</var> from the graphics handle <var>h</var>.
If <var>p</var> is omitted, return the complete property list for <var>h</var>.
If <var>h</var> is a vector, return a cell array including the property
values or lists respectively.
</p></blockquote></div>
<!-- set src/graphics.cc -->
<p><a name="doc_002dset"></a>
<div class="defun">
— Built-in Function: <b>set</b> (<var>h, property, value, <small class="dots">...</small></var>)<var><a name="index-set-1512"></a></var><br>
— Built-in Function: <b>set</b> (<var>h, properties, values</var>)<var><a name="index-set-1513"></a></var><br>
— Built-in Function: <b>set</b> (<var>h, pv</var>)<var><a name="index-set-1514"></a></var><br>
<blockquote><p>Set named property values for the graphics handle (or vector of graphics
handles) <var>h</var>.
There are three ways how to give the property names and values:
<ul>
<li>as a comma separated list of <var>property</var>, <var>value</var> pairs
<p>Here, each <var>property</var> is a string containing the property name, each
<var>value</var> is a value of the appropriate type for the property.
<li>as a cell array of strings <var>properties</var> containing property names
and a cell array <var>values</var> containing property values.
<p>In this case, the number of columns of <var>values</var> must match the number of
elements in <var>properties</var>. The first column of <var>values</var> contains
values for the first entry in <var>properties</var>, etc. The number of rows of
<var>values</var> must be 1 or match the number of elements of <var>h</var>. In the
first case, each handle in <var>h</var> will be assigned the same values. In the
latter case, the first handle in <var>h</var> will be assigned the values from
the first row of <var>values</var> and so on.
<li>as a structure array <var>pv</var>
<p>Here, the field names of <var>pv</var> represent the property names, and the field
values give the property values. In contrast to the previous case, all
elements of <var>pv</var> will be set in all handles in <var>h</var> independent of
the dimensions of <var>pv</var>.
</ul>
</p></blockquote></div>
<!-- ancestor scripts/plot/ancestor.m -->
<p><a name="doc_002dancestor"></a>
<div class="defun">
— Function File: <var>parent</var> = <b>ancestor</b> (<var>h, type</var>)<var><a name="index-ancestor-1515"></a></var><br>
— Function File: <var>parent</var> = <b>ancestor</b> (<var>h, type, 'toplevel'</var>)<var><a name="index-ancestor-1516"></a></var><br>
<blockquote><p>Return the first ancestor of handle object <var>h</var> whose type matches
<var>type</var>, where <var>type</var> is a character string. If <var>type</var> is a
cell array of strings, return the first parent whose type matches
any of the given type strings.
<p>If the handle object <var>h</var> is of type <var>type</var>, return <var>h</var>.
<p>If <code>"toplevel"</code> is given as a 3rd argument, return the highest
parent in the object hierarchy that matches the condition, instead
of the first (nearest) one.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dget.html#doc_002dget">get</a>, <a href="doc_002dset.html#doc_002dset">set</a>.
</p></blockquote></div>
<!-- allchild scripts/plot/allchild.m -->
<p><a name="doc_002dallchild"></a>
<div class="defun">
— Function File: <var>h</var> = <b>allchild</b> (<var>handles</var>)<var><a name="index-allchild-1517"></a></var><br>
<blockquote><p>Find all children, including hidden children, of a graphics object.
<p>This function is similar to <code>get (h, "children")</code>, but also
returns hidden objects. If <var>handles</var> is a scalar,
<var>h</var> will be a vector. Otherwise, <var>h</var> will be a cell matrix
of the same size as <var>handles</var> and each cell will contain a
vector of handles.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dget.html#doc_002dget">get</a>, <a href="doc_002dset.html#doc_002dset">set</a>, <a href="doc_002dfindall.html#doc_002dfindall">findall</a>, <a href="doc_002dfindobj.html#doc_002dfindobj">findobj</a>.
</p></blockquote></div>
</body></html>
