@c Copyright (C) 1996, 1997, 1999, 2000, 2002, 2003, 2004, 2005,
@c               2006, 2007 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Plotting
@chapter Plotting
@cindex plotting
@cindex graphics

@menu
* Plotting Basics::             
* Advanced Plotting::           
@end menu

@node Plotting Basics
@section Plotting Basics

Octave makes it easy to create many different types of two- and
three-dimensional plots using a few high-level functions.

If you need finer control over graphics, see @ref{Advanced Plotting}.

@menu
* Two-Dimensional Plots::       
* Three-Dimensional Plotting::  
* Plot Annotations::            
* Multiple Plots on One Page::  
* Multiple Plot Windows::       
* Printing Plots::              
* Interacting with plots::
* Test Plotting Functions::     
@end menu

@node Two-Dimensional Plots
@subsection Two-Dimensional Plots

The @code{plot} function allows you to create simple x-y plots with
linear axes.  For example,

@example
@group
x = -10:0.1:10;
plot (x, sin (x));
@end group
@end example

@noindent
displays a sine wave shown in @ref{fig:plot}.  On most systems, this
command will open a separate plot window to display the graph.

@float Figure,fig:plot
@image{plot,8cm}
@caption{Simple Two-Dimensional Plot.}
@end float

@DOCSTRING(plot)

The @code{plotyy} function may be used to create a plot with two
independent y axes.

@DOCSTRING(plotyy)

The functions @code{semilogx}, @code{semilogy}, and @code{loglog} are
similar to the @code{plot} function, but produce plots in which one or
both of the axes use log scales.

@DOCSTRING(semilogx)

@DOCSTRING(semilogy)

@DOCSTRING(loglog)

The functions @code{bar}, @code{barh}, @code{stairs}, and @code{stem}
are useful for displaying discrete data.  For example,

@example
@group
hist (randn (10000, 1), 30);
@end group
@end example

@noindent
produces the histogram of 10,000 normally distributed random numbers
shown in @ref{fig:hist}.

@float Figure,fig:hist
@image{hist,8cm}
@caption{Histogram.}
@end float

@DOCSTRING(bar)

@DOCSTRING(barh)

@DOCSTRING(hist)

@DOCSTRING(stairs)

@DOCSTRING(stem)

@DOCSTRING(stem3)

@DOCSTRING(scatter)

@DOCSTRING(scatter3)

@DOCSTRING(plotmatrix)

@DOCSTRING(pareto)

@DOCSTRING(rose)

The @code{contour}, @code{contourf} and @code{contourc} functions
produce two-dimensional contour plots from three dimensional data.

@DOCSTRING(contour)

@DOCSTRING(contourf)

@DOCSTRING(contourc)

@DOCSTRING(contour3)

The @code{errorbar}, @code{semilogxerr}, @code{semilogyerr}, and
@code{loglogerr} functions produce plots with error bar markers.  For
example,

@example
x = 0:0.1:10;
y = sin (x);
yp =  0.1 .* randn (size (x));
ym = -0.1 .* randn (size (x));
errorbar (x, sin (x), ym, yp);
@end example

@noindent
produces the figure shown in @ref{fig:errorbar}.

@float Figure,fig:errorbar
@image{errorbar,8cm}
@caption{Errorbar plot.}
@end float

@DOCSTRING(errorbar)

@DOCSTRING(semilogxerr)

@DOCSTRING(semilogyerr)

@DOCSTRING(loglogerr)

Finally, the @code{polar} function allows you to easily plot data in
polar coordinates.  However, the display coordinates remain rectangular
and linear.  For example,

@example
polar (0:0.1:10*pi, 0:0.1:10*pi);
@end example

@noindent
produces the spiral plot shown in @ref{fig:polar}.

@float Figure,fig:polar
@image{polar,8cm}
@caption{Polar plot.}
@end float

@DOCSTRING(polar)

@DOCSTRING(pie)

@DOCSTRING(quiver)

@DOCSTRING(quiver3)

@DOCSTRING(compass)

@DOCSTRING(feather)

@DOCSTRING(pcolor)

@DOCSTRING(area)

@DOCSTRING(comet)

The axis function may be used to change the axis limits of an existing
plot and various other axis properties, such as the aspect ratio and the
appearance of tic marks.

@DOCSTRING(axis)

Similarly the axis limits of the colormap can be changed with the caxis
function.

@DOCSTRING(caxis)

The @code{xlim}, @code{ylim}, and @code{zlim} functions may be used to
get or set individual axis limits.  Each has the same form.

@anchor{doc-ylim}
@anchor{doc-zlim}
@DOCSTRING(xlim)

@menu
* Two-dimensional Function Plotting::
@end menu

@node Two-dimensional Function Plotting
@subsubsection Two-dimensional Function Plotting

Octave can plot a function from a function handle inline function or
string defining the function without the user needing to explicitly
create the data to be plotted. The function @code{fplot} also generates
two-dimensional plots with linear axes using a function name and limits
for the range of the x-coordinate instead of the x and y data.  For
example,

@example
@group
fplot (@@sin, [-10, 10], 201);
@end group
@end example

@noindent
produces a plot that is equivalent to the one above, but also includes a
legend displaying the name of the plotted function.

@DOCSTRING(fplot)

Other functions that can create two-dimensional plots directly from a
function include @code{ezplot}, @code{ezcontour}, @code{ezcontourf} and
@code{ezpolar}.

@DOCSTRING(ezplot)

@DOCSTRING(ezcontour)

@DOCSTRING(ezcontourf)

@DOCSTRING(ezpolar)

@node Three-Dimensional Plotting
@subsection Three-Dimensional Plotting

The function @code{mesh} produces mesh surface plots.  For example,

@example
@group
tx = ty = linspace (-8, 8, 41)';
[xx, yy] = meshgrid (tx, ty);
r = sqrt (xx .^ 2 + yy .^ 2) + eps;
tz = sin (r) ./ r;
mesh (tx, ty, tz);
@end group
@end example

@noindent
produces the familiar ``sombrero'' plot shown in @ref{fig:mesh}.  Note
the use of the function @code{meshgrid} to create matrices of X and Y
coordinates to use for plotting the Z data.  The @code{ndgrid} function
is similar to @code{meshgrid}, but works for N-dimensional matrices.

@float Figure,fig:mesh
@image{mesh,8cm}
@caption{Mesh plot.}
@end float

The @code{meshc} function is similar to @code{mesh}, but also produces a
plot of contours for the surface.

The @code{plot3} function displays arbitrary three-dimensional data,
without requiring it to form a surface.  For example

@example
@group
t = 0:0.1:10*pi;
r = linspace (0, 1, numel (t));
z = linspace (0, 1, numel (t));
plot3 (r.*sin(t), r.*cos(t), z);
@end group
@end example

@noindent
displays the spiral in three dimensions shown in @ref{fig:plot3}.

@float Figure,fig:plot3
@image{plot3,8cm}
@caption{Three dimensional spiral.}
@end float

Finally, the @code{view} function changes the viewpoint for
three-dimensional plots.

@DOCSTRING(mesh)

@DOCSTRING(meshc)

@DOCSTRING(meshz)

@DOCSTRING(hidden)

@DOCSTRING(surf)

@DOCSTRING(surfc)

@DOCSTRING(surfl)

@DOCSTRING(surfnorm)

@DOCSTRING(diffuse)

@DOCSTRING(specular)

@DOCSTRING(meshgrid)

@DOCSTRING(ndgrid)

@DOCSTRING(plot3)

@DOCSTRING(view)

@DOCSTRING(slice)

@DOCSTRING(ribbon)

@DOCSTRING(shading)

@menu
* Three-dimensional Function Plotting::
* Three-dimensional Geometric Shapes::
@end menu

@node Three-dimensional Function Plotting
@subsubsection Three-dimensional Function Plotting

@DOCSTRING(ezplot3)

@DOCSTRING(ezmesh)

@DOCSTRING(ezmeshc)

@DOCSTRING(ezsurf)

@DOCSTRING(ezsurfc)

@node Three-dimensional Geometric Shapes
@subsubsection Three-dimensional Geometric Shapes

@DOCSTRING(cylinder)

@DOCSTRING(sphere)

@DOCSTRING(ellipsoid)

@node Plot Annotations
@subsection Plot Annotations

You can add titles, axis labels, legends, and arbitrary text to an
existing plot.  For example,

@example
@group
x = -10:0.1:10;
plot (x, sin (x));
title ("sin(x) for x = -10:0.1:10");
xlabel ("x");
ylabel ("sin (x)");
text (pi, 0.7, "arbitrary text");
legend ("sin (x)");
@end group
@end example

The functions @code{grid} and @code{box} may also be used to add grid
and border lines to the plot.  By default, the grid is off and the
border lines are on.

@DOCSTRING(title)

@DOCSTRING(legend)

@DOCSTRING(text)

See @ref{Text Properties} for the properties that you can set.

@anchor{doc-ylabel}
@anchor{doc-zlabel}
@DOCSTRING(xlabel)

@DOCSTRING(clabel)

@DOCSTRING(box)

@DOCSTRING(grid)

@DOCSTRING(colorbar)

@node Multiple Plots on One Page
@subsection Multiple Plots on One Page

Octave can display more than one plot in a single figure.  The simplest
way to do this is to use the @code{subplot} function to divide the plot
area into a series of subplot windows that are indexed by an integer.
For example,

@example
@group
subplot (2, 1, 1)
fplot (@@sin, [-10, 10]);
subplot (2, 1, 2)
fplot (@@cos, [-10, 10]);
@end group
@end example

@noindent
creates a figure with two separate axes, one displaying a sine wave and
the other a cosine wave.  The first call to subplot divides the figure
into two plotting areas (two rows and one column) and makes the first plot
area active.  The grid of plot areas created by @code{subplot} is
numbered in column-major order (top to bottom, left to right).

@DOCSTRING(subplot)

@node Multiple Plot Windows
@subsection Multiple Plot Windows

You can open multiple plot windows using the @code{figure} function.
For example

@example
figure (1);
fplot (@@sin, [-10, 10]);
figure (2);
fplot (@@cos, [-10, 10]);
@end example

@noindent
creates two figures, with the first displaying a sine wave and
the second a cosine wave.  Figure numbers must be positive integers.

@DOCSTRING(figure)

@node Printing Plots
@subsection Printing Plots

The @code{print} command allows you to save plots in a variety of
formats.  For example,

@example
print -deps foo.eps
@end example

@noindent
writes the current figure to an encapsulated PostScript file called
@file{foo.eps}.

@DOCSTRING(print)

@DOCSTRING(orient)

@node Interacting with plots
@subsection Interacting with plots

The user can select points on a plot with the @code{ginput} function or
selction the position at which to place text on the plot with the
@code{gtext} function using the mouse.

@DOCSTRING(ginput)

@DOCSTRING(waitforbuttonpress)

@DOCSTRING(gtext)

@node Test Plotting Functions
@subsection Test Plotting Functions

The functions @code{sombrero} and @code{peaks} provide a way to check
that plotting is working.  Typing either @code{sombrero} or @code{peaks}
at the Octave prompt should display a three dimensional plot.

@DOCSTRING(sombrero)

@DOCSTRING(peaks)

@node Advanced Plotting
@section Advanced Plotting

@menu
* Graphics Objects::
* Graphics Object Properties::  
* Managing Default Properties::  
* Colors::
* Line Styles::
* Marker Styles::
* Callbacks::
* Object Groups::
* Graphics backends::
@end menu

@node Graphics Objects
@subsection Graphics Objects

Plots in Octave are constructed from the following @dfn{graphics
objects}.  Each graphics object has a set of properties that define its
appearance and may also contain links to other graphics objects.
Graphics objects are only referenced by a numeric index, or @dfn{handle}.

@table @asis
@item root figure
@cindex root figure graphics object
@cindex graphics object, root figure
The parent of all figure objects.  The index for the root figure is
defined to be 0.

@item figure
@cindex figure graphics object
@cindex graphics object, figure
A figure window.

@item axes
@cindex axes graphics object
@cindex graphics object, axes
An 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.

@item line
@cindex line graphics object
@cindex graphics object, line
A line in two or three dimensions.

@item text
@cindex text graphics object
@cindex graphics object, text
Text annotations.

@item image
@cindex image graphics object
@cindex graphics object, image
A bitmap image.

@item patch
@cindex patch graphics object
@cindex graphics object, patch
A filled polygon, currently limited to two dimensions.

@item surface
@cindex surface graphics object
@cindex graphics object, surface 
A three-dimensional surface.
@end table

To determine whether an object is a graphics object index or a figure
index, use the functions @code{ishandle} and @code{isfigure}.

@DOCSTRING(ishandle)

@DOCSTRING(ishghandle)

@DOCSTRING(isfigure)

The function @code{gcf} returns an index to the current figure object,
or creates one if none exists.  Similarly, @code{gca} returns the
current axes object, or creates one (and its parent figure object) if
none exists.

@DOCSTRING(gcf)

@DOCSTRING(gca)

The @code{get} and @code{set} functions may be used to examine and set
properties for graphics objects.  For example,

@example
@group
get (0)
    @result{} ans =
       @{
         type = root figure
         currentfigure = [](0x0)
         children = [](0x0)
         visible = on
       @}
@end group
@end example

@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} function.  Also, note that in this
case, the @code{currentfigure} property is empty, which indicates that
there is no current figure window.

The @code{get} function may also be used to find the value of a single
property.  For example,

@example
@group
get (gca (), "xlim")
    @result{} [ 0 1 ]
@end group
@end example

@noindent
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,

@example
set (gca (), "xlim", [-10, 10]);
@end example

@noindent
sets the range of the x-axis for the current axes object in the current
figure to @samp{[-10, 10]}.  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,

@example
set (gca ())
@end example

@noindent
returns a structure containing the default property values for axes
objects.

@DOCSTRING(get)

@DOCSTRING(set)

@DOCSTRING(ancestor)

@DOCSTRING(allchild)

You can create axes, line, and patch objects directly using the
@code{axes}, @code{line}, and @code{patch} functions.  These objects
become children of the current axes object.

@DOCSTRING(axes)

@DOCSTRING(line)

@DOCSTRING(patch)

@DOCSTRING(fill)

@DOCSTRING(surface)

By default, Octave refreshes the plot window when a prompt is printed,
or when waiting for input.  To force an update at other times, call the
@code{drawnow} function.

@DOCSTRING(drawnow)

Only figures that are modified will be updated. The @code{refresh}
function can also be to force an update of the current figure, even if
it is nor modified.

@DOCSTRING(refresh)

Normally, high-level plot functions like @code{plot} or @code{mesh} call
@code{newplot} to initialize the state of the current axes so that the
next plot is drawn in a blank window with default property settings.  To
have two plots superimposed over one another, call the @code{hold}
function.  For example,

@example
@group
hold ("on");
x = -10:0.1:10;
plot (x, sin (x));
plot (x, cos (x));
hold ("off");
@end group
@end example

@noindent
displays sine and cosine waves on the same axes.  If the hold state is
off, consecutive plotting commands like this will only display the last
plot.

@DOCSTRING(newplot)

@DOCSTRING(hold)

@DOCSTRING(ishold)

To clear the current figure, call the @code{clf} function.  To clear the
current axis, call the @code{cla} function. To bring the current fingure
to the top of the window stack, call the @code{shg} function.  To delete
a graphics object, call @code{delete} on its index.  To close the
figure window, call the @code{close} function.

@DOCSTRING(clf)

@DOCSTRING(cla)

@DOCSTRING(shg)

@DOCSTRING(delete)

@DOCSTRING(close)

@DOCSTRING(closereq)

@node Graphics Object Properties
@subsection Graphics Object Properties
@cindex graphics object properties

@menu
* Root Figure Properties::      
* Figure Properties::           
* Axes Properties::             
* Line Properties::             
* Text Properties::             
* Image Properties::            
* Patch Properties::            
* Surface Properties::          
* Searching Properties::
@end menu

@node Root Figure Properties
@subsubsection Root Figure Properties

@table @code
@item currentfigure
Index to graphics object for the current figure.

@c FIXME -- does this work?
@c @item visible
@c Either @code{"on"} or @code{"off"} to toggle display of figures.
@end table

@node Figure Properties
@subsubsection Figure Properties
@cindex figure properties

@table @code
@item nextplot
May be one of
@table @code
@item "new"
@item "add"
@item "replace"
@item "replacechildren"
@end table

@item closerequestfcn
Handle of function to call when a figure is closed.

@item currentaxes
Index to graphics object of current axes.

@item colormap
An N-by-3 matrix containing the color map for the current axes.

@item visible
Either @code{"on"} or @code{"off"} to toggle display of the figure.

@item paperorientation
Indicates the orientation for printing.  Either @code{"landscape"} or
@code{"portrait"}.
@end table

@node Axes Properties
@subsubsection Axes Properties
@cindex axes properties

@table @code
@item position
A vector specifying the position of the plot, excluding titles, axes and
legend.  The four elements of the vector are the coordinates of the
lower left corner and width and height of the plot, in units normalized
to the width and height of the plot window.  For example, @code{[0.2,
0.3, 0.4, 0.5]} sets the lower left corner of the axes at @math{(0.2,
0.3)} and the width and height to be 0.4 and 0.5 respectively.  See also
the @code{outerposition} property.

@item title
Index of text object for the axes title.

@item box
Either @code{"on"} or @code{"off"} to toggle display of the box around
the axes.

@item key
Either @code{"on"} or @code{"off"} to toggle display of the legend.
Note that this property is not compatible with @sc{Matlab} and may be
removed in a future version of Octave.

@item keybox
Either @code{"on"} or @code{"off"} to toggle display of a box around the
legend.  Note that this property is not compatible with @sc{Matlab} and
may be removed in a future version of Octave.

@item keypos
An integer from 1 to 4 specifying the position of the legend.  1
indicates upper right corner, 2 indicates upper left, 3 indicates lower
left, and 4 indicates lower right.  Note that this property is not
compatible with @sc{Matlab} and may be removed in a future version of
Octave.

@item dataaspectratio
A two-element vector specifying the relative height and width of the
data displayed in the axes.  Setting @code{dataaspectratio} to @samp{1,
2]} causes the length of one unit as displayed on the y axis to be the
same as the length of 2 units on the x axis.  Setting
@code{dataaspectratio} also forces the @code{dataaspectratiomode}
property to be set to @code{"manual"}.

@item dataaspectratiomode
Either @code{"manual"} or @code{"auto"}.

@item xlim
@itemx ylim
@itemx zlim
@itemx clim
Two-element vectors defining the limits for the x, y, and z axes and the 
Setting one of these properties also forces the corresponding mode
property to be set to @code{"manual"}.

@item xlimmode
@itemx ylimmode
@itemx zlimmode
@itemx climmode
Either @code{"manual"} or @code{"auto"}.

@item xlabel
@itemx ylabel
@itemx zlabel
Indices to text objects for the axes labels.

@item xgrid
@itemx ygrid
@itemx zgrid
Either @code{"on"} or @code{"off"} to toggle display of grid lines.

@item xminorgrid
@itemx yminorgrid
@itemx zminorgrid
Either @code{"on"} or @code{"off"} to toggle display of minor grid lines.

@item xtick
@itemx ytick
@itemx ztick
Setting one of these properties also forces the corresponding mode
property to be set to @code{"manual"}.

@item xtickmode
@itemx ytickmode
@itemx ztickmode
Either @code{"manual"} or @code{"auto"}.

@item xticklabel
@itemx yticklabel
@itemx zticklabel
Setting one of these properties also forces the corresponding mode
property to be set to @code{"manual"}.

@item xticklabelmode
@itemx yticklabelmode
@itemx zticklabelmode
Either @code{"manual"} or @code{"auto"}.

@item xscale
@itemx yscale
@itemx zscale
Either @code{"linear"} or @code{"log"}.

@item xdir
@itemx ydir
@itemx zdir
Either @code{"forward"} or @code{"reverse"}.

@item xaxislocation
@itemx yaxislocation
Either @code{"top"} or @code{"bottom"} for the x axis and @code{"left"}
or @code{"right"} for the y axis.

@item view
A three element vector specifying the view point for three-dimensional plots.

@item visible
Either @code{"on"} or @code{"off"} to toggle display of the axes.

@item nextplot
May be one of
@table @code
@item "new"
@item "add"
@item "replace"
@item "replacechildren"
@end table

@item outerposition
A vector specifying the position of the plot, including titles, axes and
legend.  The four elements of the vector are the coordinates of the
lower left corner and width and height of the plot, in units normalized
to the width and height of the plot window.  For example, @code{[0.2,
0.3, 0.4, 0.5]} sets the lower left corner of the axes at @math{(0.2,
0.3)} and the width and height to be 0.4 and 0.5 respectively.  See also
the @code{position} property.
@end table

@node Line Properties
@subsubsection Line Properties
@cindex line properties

@table @code
@itemx xdata
@itemx ydata
@itemx zdata
@itemx ldata
@itemx udata
@itemx xldata
@itemx xudata
The data to be plotted.  The @code{ldata} and @code{udata} elements are
for errorbars in the y direction, and the @code{xldata} and @code{xudata}
elements are for errorbars in the x direction.

@item color
The RGB color of the line, or a color name.  @xref{Colors}.

@item linestyle
@itemx linewidth
@xref{Line Styles}.

@item marker
@item markeredgecolor
@item markerfacecolor
@item markersize
@xref{Marker Styles}.

@item keylabel
The text of the legend entry corresponding to this line.  Note that this
property is not compatible with @sc{Matlab} and may be removed in a
future version of Octave.
@end table

@node Text Properties
@subsubsection Text Properties
@cindex text properties

@table @code
@item string
The character string contained by the text object.

@item units
May be @code{"normalized"} or @code{"graph"}.

@item position
The coordinates of the text object.

@item rotation
The angle of rotation for the displayed text, measured in degrees.

@item horizontalalignment
May be @code{"left"}, @code{"center"}, or @code{"right"}.

@item color
The color of the text.  @xref{Colors}.

@item fontname
The font used for the text.

@item fontsize
The size of the font, in points to use.

@item fontangle
Flag whether the font is italic or normal. Valid values are 'normal',
'italic' and 'oblique'.

@item fontweight
Flag whether the font is bold, etc. Valid values are 'normal', 'bold',
'demi' or 'light'.

@item interpreter
Determines how the text is rendered. Valid values are 'none', 'tex' or
'latex'.
@end table

All text objects, including titles, labels, legends, and text, include
the property 'interpreter', this property determines the manner in which
special control sequences in the text are rendered. If the interpreter
is set to 'none', then no rendering occurs. At this point the 'latex'
option is not implemented and so the 'latex' interpreter also does not
interpret the text.

The 'tex' option implements a subset of @sc{TeX} functionality in the
rendering of the text. This allows the insertion of special characters
such as Greek or mathematical symbols within the text. The special
characters are also inserted with a code starting with the back-slash
(\) character, as in the table @ref{tab:extended}. 

In addition, the formatting of the text can be changed within the string
with the codes 

@multitable @columnfractions .2 .2 .6 .2
@item @tab \bf @tab Bold font @tab
@item @tab \it @tab Italic font @tab
@item @tab \sl @tab Oblique Font @tab
@item @tab \rm @tab Normal font @tab
@end multitable

These are be used in conjunction with the @{ and @} characters to limit
the change in the font to part of the string. For example

@example
xlabel ('@{\bf H@} = a @{\bf V@}')
@end example

where the character 'a' will not appear in a bold font. Note that to
avoid having Octave interpret the backslash characters in the strings,
the strings should be in single quotes.

It is also possible to change the fontname and size within the text 

@multitable @columnfractions .1 .4 .6 .1
@item @tab \fontname@{@var{fontname}@} @tab Specify the font to use @tab
@item @tab \fontsize@{@var{size}@} @tab Specify the size of the font to
use @tab
@end multitable

Finally, the superscript and subscripting can be controlled with the '^'
and '_' characters. If the '^' or '_' is followed by a @{ character,
then all of the block surrounded by the @{ @} pair is super- or
sub-scripted. Without the @{ @} pair, only the character immediately
following the '^' or '_' is super- or sub-scripted.

@float Table,tab:extended
@iftex
@tex
\vskip 6pt
{\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt 
\halign{
\vrule height2.0ex depth1.ex width 0.6pt #\tabskip=0.3em &
# \hfil & \vrule # & # \hfil & # \vrule &
# \hfil & \vrule # & # \hfil & # \vrule &
# \hfil & \vrule # & # \hfil & # \vrule 
width 0.6pt \tabskip=0pt\cr
\noalign{\hrule height 0.6pt}
& Code && Sym && Code && Sym && Code && Sym &\cr
\noalign{\hrule}
& $\backslash$forall    && $\forall$ 
&& $\backslash$exists   && $\exists$ 
&& $\backslash$ni       && $\ni$       &\cr
& $\backslash$cong      && $\cong$ 
&& $\backslash$Delta    && $\Delta$ 
&& $\backslash$Phi      && $\Phi$      &\cr
& $\backslash$Gamma     && $\Gamma$ 
&& $\backslash$vartheta && $\vartheta$ 
&& $\backslash$Lambda   && $\Lambda$   &\cr
& $\backslash$Pi        && $\Pi$ 
&& $\backslash$Theta    && $\Theta$ 
&& $\backslash$Sigma    && $\Sigma$    &\cr
& $\backslash$varsigma  && $\varsigma$ 
&& $\backslash$Omega    && $\Omega$ 
&& $\backslash$Xi       && $\Xi$       &\cr
& $\backslash$Psi       && $\Psi$ 
&& $\backslash$perp     && $\perp$ 
&& $\backslash$alpha    && $\alpha$    &\cr
& $\backslash$beta      && $\beta$ 
&& $\backslash$chi      && $\chi$ 
&& $\backslash$delta    && $\delta$    &\cr
& $\backslash$epsilon   && $\epsilon$ 
&& $\backslash$phi      && $\phi$ 
&& $\backslash$gamma    && $\gamma$    &\cr
& $\backslash$eta       && $\eta$ 
&& $\backslash$iota     && $\iota$ 
&& $\backslash$varphi   && $\varphi$   &\cr
& $\backslash$kappa     && $\kappa$ 
&& $\backslash$lambda   && $\lambda$ 
&& $\backslash$mu       && $\mu$       &\cr
& $\backslash$nu        && $\nu$ 
&& $\backslash$o        && $\o$ 
&& $\backslash$pi       && $\pi$       &\cr
& $\backslash$theta     && $\theta$ 
&& $\backslash$rho      && $\rho$ 
&& $\backslash$sigma    && $\sigma$    &\cr
& $\backslash$tau       && $\tau$
&& $\backslash$upsilon  && $\upsilon$ 
&& $\backslash$varpi    && $\varpi$    &\cr
& $\backslash$omega     && $\omega$ 
&& $\backslash$xi       && $\xi$ 
&& $\backslash$psi      && $\psi$      &\cr
& $\backslash$zeta      && $\zeta$ 
&& $\backslash$sim      && $\sim$ 
&& $\backslash$Upsilon  && $\Upsilon$  &\cr
& $\backslash$prime     && $\prime$ 
&& $\backslash$leq      && $\leq$ 
&& $\backslash$infty    && $\infty$    &\cr
& $\backslash$clubsuit  && $\clubsuit$ 
&& $\backslash$diamondsuit    && $\diamondsuit$ 
&& $\backslash$heartsuit      && $\heartsuit$     &\cr
& $\backslash$spadesuit       && $\spadesuit$ 
&& $\backslash$leftrightarrow && $\leftrightarrow$ 
&& $\backslash$leftarrow      && $\leftarrow$     &\cr
& $\backslash$uparrow         && $\uparrow$ 
&& $\backslash$rightarrow     && $\rightarrow$ 
&& $\backslash$downarrow      && $\downarrow$     &\cr
& $\backslash$circ      && $\circ$ 
&& $\backslash$pm       && $\pm$ 
&& $\backslash$geq      && $\geq$      &\cr
& $\backslash$times     && $\times$ 
&& $\backslash$propto   && $\propto$ 
&& $\backslash$partial  && $\partial$  &\cr
& $\backslash$bullet    && $\bullet$
&& $\backslash$div      && $\div$ 
&& $\backslash$neq      && $\neq$      &\cr
& $\backslash$equiv     && $\equiv$ 
&& $\backslash$approx   && $\approx$ 
&& $\backslash$ldots    && $\ldots$ &\cr
& $\backslash$mid       && $\mid$ 
&& $\backslash$aleph    && $\aleph$ 
&& $\backslash$Im       && $\Im$ &\cr
& $\backslash$Re        && $\Re$ 
&& $\backslash$wp       && $\wp$ 
&& $\backslash$otimes   && $\otimes$ &\cr
& $\backslash$oplus     && $\oplus$ 
&& $\backslash$oslash   && $\oslash$ 
&& $\backslash$cap      && $\cap$ &\cr
& $\backslash$cup       && $\cup$ 
&& $\backslash$supset   && $\supset$ 
&& $\backslash$supseteq && $\supseteq$ &\cr
& $\backslash$subset    && $\subset$ 
&& $\backslash$subseteq && $\subseteq$ 
&& $\backslash$in       && $\in$ &\cr
& $\backslash$notin     && $\notin$
&& $\backslash$angle    && $\angle$
&& $\backslash$bigtriangledown && $\bigtriangledown$ &\cr
& $\backslash$langle    && $\langle$ 
&& $\backslash$rangle   && $\rangle$ 
&& $\backslash$nabla    && $\nabla$    &\cr
& $\backslash$prod      && $\prod$
&& $\backslash$surd     && $\surd$ 
&& $\backslash$cdot     && $\cdot$     &\cr
& $\backslash$neg       && $\neg$ 
&& $\backslash$wedge    && $\wedge$ 
&& $\backslash$vee      && $\vee$      &\cr
& $\backslash$Leftrightarrow && $\Leftrightarrow$
&& $\backslash$Leftarrow     && $\Leftarrow$
&& $\backslash$Uparrow       && $\Uparrow$           &\cr
& $\backslash$Rightarrow     && $\Rightarrow$
&& $\backslash$Downarrow     && $\Downarrow$
&& $\backslash$diamond  && $\diamond$  &\cr
& $\backslash$copyright && $\copyright$ 
&& $\backslash$rfloor   && $\rfloor$ 
&& $\backslash$lceil    && $\lceil$    &\cr
& $\backslash$lfloor    && $\lfloor$ 
&& $\backslash$rceil    && $\rceil$ 
&& $\backslash$int      && $\int$      &\cr
\noalign{\hrule height 0.6pt}
}}\hfill}}
@end tex
@end iftex
@ifnottex
@multitable @columnfractions .125 .25 .25 .25 .125
@item @tab  \forall     @tab  \exists     @tab  \ni      @tab
@item @tab  \cong       @tab  \Delta      @tab  \Phi     @tab
@item @tab  \Gamma      @tab  \vartheta   @tab  \Lambda  @tab
@item @tab  \Pi         @tab  \Theta      @tab  \Sigma   @tab
@item @tab  \varsigma   @tab  \Omega      @tab  \Xi      @tab
@item @tab  \Psi        @tab  \perp       @tab  \alpha   @tab
@item @tab  \beta       @tab  \chi        @tab  \delta   @tab  
@item @tab  \epsilon    @tab  \phi        @tab  \gamma   @tab
@item @tab  \eta        @tab  \iota       @tab  \varphi  @tab
@item @tab  \kappa      @tab  \lambda     @tab  \mu      @tab 
@item @tab  \nu         @tab  \o          @tab  \pi      @tab
@item @tab  \theta      @tab  \rho        @tab  \sigma   @tab 
@item @tab  \tau        @tab  \upsilon    @tab  \varpi   @tab
@item @tab  \omega      @tab  \xi         @tab  \psi     @tab 
@item @tab  \zeta       @tab  \sim        @tab  \Upsilon @tab
@item @tab  \prime      @tab  \leq        @tab  \infty   @tab
@item @tab  \clubsuit   @tab  \diamondsuit    @tab  \heartsuit  @tab
@item @tab  \spadesuit  @tab  \leftrightarrow @tab  \leftarrow  @tab 
@item @tab  \uparrow    @tab  \rightarrow @tab  \downarrow @tab 
@item @tab  \circ       @tab \pm          @tab  \geq     @tab 
@item @tab  \times      @tab  \propto     @tab  \partial @tab
@item @tab  \bullet     @tab \div         @tab  \neq     @tab 
@item @tab  \equiv      @tab  \approx     @tab  \ldots   @tab 
@item @tab  \mid        @tab  \aleph      @tab  \Im      @tab 
@item @tab  \Re         @tab \wp          @tab  \otimes  @tab
@item @tab  \oplus      @tab \oslash      @tab  \cap     @tab 
@item @tab  \cup        @tab   \supset    @tab  \supseteq @tab 
@item @tab  \subset     @tab \subseteq    @tab  \in      @tab 
@item @tab  \notin      @tab \angle       @tab  \bigrightriangledown @tab
@item @tab  \langle     @tab  \rangle     @tab  \nabla   @tab
@item @tab  \prod       @tab \surd        @tab  \cdot    @tab 
@item @tab  \neg        @tab  \wedge      @tab \vee      @tab 
@item @tab  \Leftrightarrow @tab \Leftarrow @tab \Uparrow @tab
@item @tab  \Rightarrow @tab \Downarrow   @tab \diamond  @tab
@item @tab  \copyright  @tab  \lfloor     @tab  \lceil   @tab 
@item @tab  \rfloor     @tab  \rceil      @tab  \int     @tab 
@end multitable
@end ifnottex
@caption{Available special characters in @sc{TeX} mode}
@end float

A complete example showing the capabilities of the extended text is

@example
@group
x = 0:0.01:3;
plot(x,erf(x));
hold on;
plot(x,x,"r");
axis([0, 3, 0, 1]);
text(0.65, 0.6175, strcat('\leftarrow x = @{2/\surd\pi',
' @{\fontsize@{16@}\int_@{\fontsize@{8@}0@}^@{\fontsize@{8@}x@}@}',
' e^@{-t^2@} dt@} = 0.6175'))
@end group
@end example

@ifnotinfo
@noindent
The result of which can be seen in @ref{fig:extendedtext}

@float Figure,fig:extendedtext
@image{extended,8cm}
@caption{Example of inclusion of text with the @sc{TeX} interpreter}
@end float
@end ifnotinfo

@node Image Properties
@subsubsection Image Properties
@cindex image properties

@table @code
@item cdata
The data for the image.  Each pixel of the image corresponds to an
element of @code{cdata}.  The value of an element of @code{cdata}
specifies the row-index into the colormap of the axes object containing
the image.  The color value found in the color map for the given index
determines the color of the pixel.

@item xdata
@itemx ydata
Two-element vectors specifying the range of the x- and y- coordinates for
the image.
@end table

@node Patch Properties
@subsubsection Patch Properties
@cindex patch properties

@table @code
@item cdata
@itemx xdata
@itemx ydata
@itemx zdata
Data defining the patch object.

@item facecolor
The fill color of the patch.  @xref{Colors}.

@item facealpha
A number in the range [0, 1] indicating the transparency of the patch.

@item edgecolor
The color of the line defining the patch.  @xref{Colors}.

@item linestyle
@itemx linewidth
@xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
@xref{Marker Styles}.
@end table

@node Surface Properties
@subsubsection Surface Properties
@cindex surface properties

@table @code
@item xdata
@itemx ydata
@itemx zdata
The data determining the surface.  The @code{xdata} and @code{ydata}
elements are vectors and @code{zdata} must be a matrix.

@item keylabel
The text of the legend entry corresponding to this surface.  Note that
this property is not compatible with @sc{Matlab} and may be removed in a
future version of Octave.
@end table

@node Searching Properties
@subsubsection Searching Properties

@DOCSTRING(findobj)

@DOCSTRING(findall)


@node Managing Default Properties
@subsection Managing Default Properties
@cindex default graphics properties
@cindex graphics properties, default

Object properties have two classes of default values, @dfn{factory
defaults} (the initial values) and @dfn{user-defined defaults}, which
may override the factory defaults.

Although default values may be set for any object, they are set in
parent objects and apply to child objects.  For example,

@example
set (0, "defaultlinecolor", "green");
@end example

@noindent
sets the default line color for all objects.  The rule for constructing
the property name to set a default value is

@example
default + @var{object-type} + @var{property-name}
@end example

This rule can lead to some strange looking names, for example
@code{defaultlinelinewidth"} specifies the default @code{linewidth}
property for @code{line} objects.

The example above used the root figure object, 0, so the default
property value will apply to all line objects.  However, default values
are hierarchical, so defaults set in a figure objects override those
set in the root figure object.  Likewise, defaults set in axes objects
override those set in figure or root figure objects.  For example,

@example
@group
subplot (2, 1, 1);
set (0, "defaultlinecolor", "red");
set (1, "defaultlinecolor", "green");
set (gca (), "defaultlinecolor", "blue");
line (1:10, rand (1, 10));
subplot (2, 1, 2);
line (1:10, rand (1, 10));
figure (2)
line (1:10, rand (1, 10));
@end group
@end example

@noindent
produces two figures.  The line in first subplot window of the first
figure is blue because it inherits its color from its parent axes
object.  The line in the second subplot window of the first figure is
green because it inherits its color from its parent figure object.  The
line in the second figure window is red because it inherits its color
from the global root figure parent object.

To remove a user-defined default setting, set the default property to
the value @code{"remove"}.  For example,

@example
set (gca (), "defaultlinecolor", "remove");
@end example

@noindent
removes the user-defined default line color setting from the current axes
object.

Getting the @code{"default"} property of an object returns a list of
user-defined defaults set for the object.  For example,

@example
get (gca (), "default");
@end example

@noindent
returns a list of user-defined default values for the current axes
object.

Factory default values are stored in the root figure object.  The
command

@example
get (0, "factory");
@end example

@noindent
returns a list of factory defaults.

@node Colors
@subsection Colors
@cindex graphics colors
@cindex colors, graphics

Colors may be specified as RGB triplets with values ranging from zero to
one, or by name.  Recognized color names include @code{"blue"},
@code{"black"}, @code{"cyan"}, @code{"green"}, @code{"magenta"},
@code{"red"}, @code{"white"}, and @code{"yellow"}.

@node Line Styles
@subsection Line Styles
@cindex line styles, graphics
@cindex graphics line styles

Line styles are specified by the following properties:

@table @code
@item linestyle
May be one of
@table @code
@item "-"
Solid lines.
@item "--"
Dashed lines.
@item ":"
Points.
@item "-."
A dash-dot line.
@end table

@item linewidth
A number specifying the width of the line.  The default is 1.  A value
of 2 is twice as wide as the default, etc.
@end table

@node Marker Styles
@subsection Marker Styles
@cindex graphics marker styles
@cindex marker styles, graphics

Marker styles are specified by the following properties:
@table @code
@item marker
A character indicating a plot marker to be place at each data point, or
@code{"none"}, meaning no markers should be displayed.

@itemx markeredgecolor
The color of the edge around the marker, or @code{"auto"}, meaning that
the edge color is the same as the face color.  @xref{Colors}.

@itemx markerfacecolor
The color of the marker, or @code{"none"} to indicate that the marker
should not be filled.  @xref{Colors}.

@itemx markersize
A number specifying the size of the marker.  The default is 1.  A value
of 2 is twice as large as the default, etc.
@end table

@node Callbacks
@subsection Callbacks
@cindex callbacks

Callback functions can be associated with graphics objects and triggered
after certain events occur. The basic structure of all callback function
is 

@example
@group
function mycallback (src, data)
@dots{}
endfunction
@end group
@end example

where @code{src} gives a handle to the source of the callback, and
@code{code} gives some event specific data. This can then be associated
with an object either at the objects creation or later with the
@code{set} function. For example

@example
plot (x, "DeleteFcn", @@(s, e) disp("Window Deleted"))
@end example

@noindent
where at the moment that the plot is deleted, the message "Window
Deleted" will be displayed.

Additional user arguments can be passed to callback functions, and will
be passed after the 2 default arguments. For example

@example
plot (x, "DeleteFcn", @{@@mycallback, "1"@})
@dots{}
function mycallback (src, data, a1)
  fprintf ("Closing plot %d\n", a1);
endfunction
@end example

The basic callback functions that are available for all graphics objects
are

@itemize @bullet
@item CreateFcn
This is the callback that is called at the moment of the objects
creation. It is not called if the object is altered in any way, and so
it only makes sense to define this callback in the function call that
defines the object. Callbacks that are added to @code{CreateFcn} later with
the @code{set} function will never be executed.

@item DeleteFcn
This is the callback that is called at the moment an object is deleted.

@item ButtonDownFcn
This is the callback that is called if a mouse button is pressed while
the pointer is over this object. Note, that the gnuplot interface does
not respect this callback.
@end itemize

The object and figure that the event occurred in that resulted in the
callback being called can be found with the @code{gcbo} and @code{gcbf}
functions.

@DOCSTRING(gcbo)

@DOCSTRING(gcbf)

Callbacks can equally be added to properties with the @code{addlistener}
function described below.

@node Object Groups
@subsection Object Groups
@cindex object groups

A number of Octave high level plot functions return groups of other
graphics objects or they return graphics objects that are have their
properties linked in such a way that changes to one of the properties
results in changes in the others. A graphic object that groups other
objects is an @code{hggroup}

@DOCSTRING(hggroup)

For example a simple use of a @code{hggroup} might be

@example
@group
x = 0:0.1:10;
hg = hggroup ();
plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
hold on
plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
set (hg, "visible", "off");
@end group
@end example

@noindent
which groups the two plots into a single object and contols their
visiblity directly. The default properties of an @code{hggroup} are
the same as the set of common properties for the other graphics
objects. Additional properties can be added with the @code{addproperty}
function. 

@DOCSTRING(addproperty)

Once a property in added to an @code{hggroup}, it is not linked to any
other property of either the children of the group, or any other
graphics object. Add so to control the way in which this newly added
property is used, the @code{addlistener} function is used to define a
callback function that is executed when the property is altered.

@DOCSTRING(addlistener)

@DOCSTRING(dellistener)

An example of the use of these two functions might be

@example
@group
x = 0:0.1:10;
hg = hggroup ();
h = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
addlistener (hg, "linestyle", @@update_props);
hold on
plot (x, cos (x), "color", [0, 1, 0], "parent", hg);

function update_props (h, d)
  set (get (h, "children"), "linestyle", get (h, "linestyle"));
endfunction
@end group
@end example

@noindent
that adds a @code{linestyle} property to the @code{hggroup} and
propagating any changes its its value to the children of the group. The
@code{linkprop} function can be used to simplify the above to be

@example
@group
x = 0:0.1:10;
hg = hggroup ();
h1 = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
hold on
h2 = plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
hlink = linkprop ([hg, h1, h2], "color"); 
@end group
@end example

@DOCSTRING(linkprop)

These capabilities are used in a number of basic graphics objects. 
The @code{hggroup} objects created by the functions of Octave contain
one or more graphics object and are used to:

@itemize @bullet
@item group together multiple graphics objects,
@item create linked properties between different graphics objects, and
@item to hide the nominal user data, from the actual data of the objects.
@end itemize

@noindent
For example the @code{stem} function creates a stem series where each
@code{hggroup} of the stem series contains two line objects representing
the body and head of the stem. The @code{ydata} property of the
@code{hggroup} of the stem series represents the head of the stem,
whereas the body of the stem is between the baseline and this value. For
example

@example
@group
h = stem (1:4)
get (h, "xdata")
@result{} [  1   2   3   4]'
get (get (h, "children")(1), "xdata")
@result{} [  1   1 NaN   2   2 NaN   3   3 NaN   4   4 NaN]'
@end group
@end example

@noindent
shows the the difference between the @code{xdata} of the @code{hggroup}
of a stem series object and the underlying line.

The basic properties of such group objects is that they consist of one 
or more linked @code{hggroup}, and that changes in certain properties of
these groups are propagated to other members of the group. Whereas,
certain properties of the members of the group only apply to the current
member.

In addition the members of the group can also be linked to other
graphics objects through callback functions. For example the baseline of
the @code{bar} or @code{stem} functions is a line object, whose length
and position are automatically adjusted, based on changes to the
corresponding hggroup elements.

@menu
* Data sources in object groups::
* Area series::
* Bar series::
* Contour groups::
* Error bar series::
* Line series::
* Quiver group::
* Scatter group::
* Stair group::
* Stem Series::
* Surface group::
@end menu

@node Data sources in object groups
@subsubsection Data sources in object groups
@cindex data sources in object groups

All of the group objects contain data source parameters. There are
string parameters that contain an expression that is evaluated to update
the relevant data property of the group when the @code{refreshdata}
function is called. 

@DOCSTRING(refreshdata)

@anchor{doc-linkdata}
@c add the description of the linkdata function here when it is written
@c remove the explicit anchor when you add the corresponding @DOCSTRING
@c command

@node Area series
@subsubsection Area series
@cindex series objects
@cindex area series

Area series objects are created by the @code{area} function. Each of the
@code{hggroup} elements contains a single patch object. The properties
of the area series are

@table @code
@item basevalue
The value where the base of the area plot is drawn.

@item linewidth
@itemx linestyle
The line width and style of the edge of the patch objects making up the
areas. @xref{Line Styles}.

@item edgecolor
@itemx facecolor
The line and fill color of the patch objects making up the areas. @xref{Colors}.

@item xdata
@itemx ydata
The x and y coordinates of the original columns of the data passed to
@code{area} prior to the cumulative summation used in the @code{area}
function. 

@item xdatasource
@itemx ydatasource
Data source variables.
@end table

@node Bar series
@subsubsection Bar series
@cindex series objects
@cindex bar series

Bar series objects are created by the @code{bar} or @code{barh}
functions. Each @code{hgrroup} element contains a single patch object. 
The properties of the bar series are

@table @code
@item showbaseline
@itemx baseline
@itemx basevalue
The property @code{showbaseline} flags whether the baseline of the bar
series is displayed (default is "on"). The handle of the graphics object
representing the baseline is given by the @code{baseline} property and
the y-value of the baseline by the @code{basevalue} property. 

Changes to any of these property are propagated to the other members of
the bar series and to the baseline itself. Equally changes in the
properties of the base line itself are propagated to the members of the
corresponding bar series.

@item barwidth
@itemx barlayout
@itemx horizontal
The property @code{barwidth} is the width of the bar corresponding to
the @var{width} variable passed to @code{bar} or @var{barh}. Whether the
bar series is "grouped" or "stacked" is determined by the
@code{barlayout} property and whether the bars are horizontal or
vertical by the @code{horizontal} property.

Changes to any of these property are propagated to the other members of
the bar series.

@item linewidth
@itemx linestyle
The line width and style of the edge of the patch objects making up the
bars. @xref{Line Styles}.

@item edgecolor
@itemx facecolor
The line and fill color of the patch objects making up the bars. @xref{Colors}.

@item xdata
The nominal x positions of the bars. Changes in this property and
propagated to the other members of the bar series. 

@item ydata
The y value of the bars in the @code{hggroup}.

@item xdatasource
@itemx ydatasource
Data source variables.
@end table

@node Contour groups
@subsubsection Contour groups
@cindex series objects
@cindex contour series

Contour group objects are created by the @code{contour}, @code{contourf}
and @code{contour3} functions. The are equally one of the handles returned
by the @code{surfc} and @code{meshc} functions. The properties of the contour
group are

@table @code
@item contourmatrix
A read only property that contains the data return by @code{contourc} used to
create the contours of the plot.

@item fill
A radio property that can have the values "on" or "off" that flags whether the
contours to plot are to be filled.

@item zlevelmode
@itemx zlevel
The radio property @code{zlevelmode} can have the values "none", "auto" or 
"manual". When its value is "none" there is no z component to the plotted
contours. When its value is "auto" the z value of the plotted contours is 
at the same value as the contour itself. If the value is "manual", then the
z value at which to plot the contour is determined by the @code{zlevel}
property.

@item levellistmode
@itemx levellist
@itemx levelstepmode
@itemx levelstep
If @code{levellistmode} is "manual", then the levels at whch to plot the 
contours is determined by @code{levellist}. If @code{levellistmode} is
set to "auto", then the distance between contours is determined by 
@code{levelstep}. If both @code{levellistmode} and @code{levelstepmode}
are set to "auto", then there are assumed to be 10 equal spaced contours.

@item textlistmode
@itemx textlist
@itemx textstepmode
@itemx textstep
If @code{textlistmode} is "manual", then the labelled contours 
is determined by @code{textlist}. If @code{textlistmode} is set to 
"auto", then the distance between labelled contours is determined by 
@code{textstep}. If both @code{textlistmode} and @code{textstepmode}
are set to "auto", then there are assumed to be 10 equal spaced 
labelled contours.

@item showtext
Flag whether the contour labels are shown or not.

@item labelspacing
The distance between labels on a single contour in points.

@item linewidth
@item linestyle
@item linecolor
The properties of the contour lines. The properties @code{linewidth} and
@code{linestyle} are similar to the correponding properties for lines. The
property @code{linecolor} is a color property (@pxref{Colors}), that can also
have the values of "none" or "auto". If @code{linecolor} is "none", then no
contour line is drawn. If @code{linecolor} is "auto" then the line color is
determined by the colormap.

@item xdata
@itemx ydata
@itemx zdata
The original x, y, and z data of the contour lines.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
Data source variables.
@end table

@node Error bar series
@subsubsection Error bar series
@cindex series objects
@cindex error bar series

Error bar series are created by the @code{errorbar} function. Each 
@code{hgrroup} element contains two line objects represnting the data and
the errorbars separately. The properties of the error bar series are

@table @code
@item color
The RGB color or color name of the line objects of the error bars. @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects of the error bars. @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers on the error bars. @xref{Colors}.

@item xdata
@itemx ydata
@itemx ldata
@itemx udata
@itemx xldata
@itemx xudata
The original x, y, l, u, xl, xu data of the error bars.

@item xdatasource
@itemx ydatasource
@itemx ldatasource
@itemx udatasource
@itemx xldatasource
@itemx xudatasource
Data source variables.
@end table

@node Line series
@subsubsection Line series
@cindex series objects
@cindex line series

Line series objects are created by the @code{plot}  and @code{plot3}
functions and are of the type @code{line}. The properties of the
line series with the ability to add data sources.

@table @code
@item color
The RGB color or color name of the line objects. @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects. @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers. @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
The original x, y and z data.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
Data source variables.
@end table

@node Quiver group
@subsubsection Quiver group
@cindex group objects
@cindex quiver group

Quiver series objects are created by the @code{quiver} or @code{quiver3}
functions. Each @code{hggroup} element of the series contains three line
objects as children representing the body and head of the arrow,
together with a marker as the point of original of the arrows. The 
properties of the quiver series are

@table @code
@item autoscale
@itemx autoscalefactor
Flag whether the length of the arrows is scaled or defined directly from
the @var{u}, @var{v} and @var{w} data. If the arrow length is falgged
as being scaled by the @code{autoscale} property, then the length of the
autoscaled arrow is controlled by the @code{autoscalefactor}. 

@item maxheadsize
This property controls the size of the head of the arrows in the quiver
series. The default value is 0.2.

@item showarrowhead
Flag whether the arrow heads are displayed in the quiver plot.

@item color
The RGB color or color name of the line objects of the quiver. @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects of the quiver. @xref{Line Styles}.

@item marker
@itemx markerfacecolor
@itemx markersize
The line and fill color of the marker objects at the original of the
arrows. @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
The origins of the values of the vector field.

@item udata
@itemx vdata
@itemx wdata
The values of the vector field to plot.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
@itemx udatasource
@itemx vdatasource
@itemx wdatasource
Data source variables.
@end table

@node Scatter group
@subsubsection Scatter group
@cindex group objects
@cindex scatter group

Scatter series objects are created by the @code{scatter} or @code{scatter3}
functions. A single hggroup element contains as many children as there are
points in the scatter plot, with each child representing one of the points.
The properties of the stem series are

@table @code
@item linewidth
The line width of the line objects of the points. @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
The line and fill color of the markers of the points. @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
The original x, y and z data of the stems.

@item cdata
The color data for the points of the plot. Each point can have a separate
color, or a unique color can be specified.

@item sizedata
The size data for the points of the plot. Each point can its own size or a 
unique size can be specified.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
@itemx cdatasource
@itemx sizedatasource
Data source variables.
@end table

@node Stair group
@subsubsection Stair group
@cindex group objects
@cindex stair group

Stair series objects are created by the @code{stair} function. Each
@code{hggroup} element of the series contains a single line object as a
child representing the stair. The properties of the stair series are

@table @code
@item color
The RGB color or color name of the line objects of the stairs. @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects of the stairs. @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers on the stairs. @xref{Colors}.

@item xdata
@itemx ydata
The original x and y data of the stairs.

@item xdatasource
@itemx ydatasource
Data source variables.
@end table

@node Stem Series
@subsubsection Stem Series
@cindex series objects
@cindex stem series

Stem series objects are created by the @code{stem} or @code{stem3}
functions. Each @code{hgrroup} element contains a single line object
as a child respresenting the stems. The properties of the stem series
are

@table @code
@item showbaseline
@itemx baseline
@itemx basevalue
The property @code{showbaseline} flags whether the baseline of the
stem series is displayed (default is "on"). The handle of the graphics
object representing the baseline is given by the @code{baseline}
property and the y-value (or z-value for @code{stem3}) of the baseline
by the @code{basevalue} property.

Changes to any of these property are propagated to the other members of
the stem series and to the baseline itself. Equally changes in the
properties of the base line itself are propagated to the members of the
corresponding stem series.

@item color
The RGB color or color name of the line objects of the stems. @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the line objects of the stems. @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers on the stems. @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
The original x, y and z data of the stems.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
Data source variables.
@end table

@node Surface group
@subsubsection Surface group
@cindex group objects
@cindex surface group

Surface group objects are created by the @code{surf} or @code{mesh}
functions, but are equally one of the handles returned by the @code{surfc}
or @code{meshc} functions. The surface group is of the type @code{surface}.

The properties of the surface group are

@table @code
@item edgecolor
@item facecolor
The RGB color or color name of the edges or faces of the surface. @xref{Colors}.

@item linewidth
@itemx linestyle
The line width and style of the lines on the surface. @xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
The line and fill color of the markers on the surface. @xref{Colors}.

@item xdata
@itemx ydata
@itemx zdata
@item cdata
The original x, y, z and c data.

@item xdatasource
@itemx ydatasource
@itemx zdatasource
@itemx cdatasource
Data source variables.
@end table

@node Graphics backends
@subsection Graphics backends
@cindex graphics backends
@cindex backends, graphics

@DOCSTRING(backend)

@DOCSTRING(available_backends)

@menu
* Interaction with gnuplot::
@end menu

@node Interaction with gnuplot
@subsubsection Interaction with @code{gnuplot}
@cindex gnuplot interaction

@DOCSTRING(gnuplot_binary)