This is octave.info, produced by makeinfo version 6.8 from octave.texi.

INFO-DIR-SECTION Math
START-INFO-DIR-ENTRY
* Octave: (octave).             Interactive language for numerical computations.
END-INFO-DIR-ENTRY

Copyright © 1996-2022 The Octave Project Developers

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave.info,  Node: Aspect Ratio,  Next: Three-dimensional Function Plotting,  Up: Three-Dimensional Plots

15.2.2.1 Aspect Ratio
.....................

For three-dimensional plots the aspect ratio can be set for data with
‘daspect’ and for the plot box with ‘pbaspect’.  *Note Axis
Configuration::, for controlling the x-, y-, and z-limits for plotting.

 -- : DATA_ASPECT_RATIO = daspect ()
 -- : daspect (DATA_ASPECT_RATIO)
 -- : daspect (MODE)
 -- : DATA_ASPECT_RATIO_MODE = daspect ("mode")
 -- : daspect (HAX, ...)
     Query or set the data aspect ratio of the current axes.

     The aspect ratio is a normalized 3-element vector representing the
     span of the x, y, and z-axis limits.

     ‘daspect (MODE)’

     Set the data aspect ratio mode of the current axes.  MODE is either
     "auto" or "manual".

     ‘daspect ("mode")’

     Return the data aspect ratio mode of the current axes.

     ‘daspect (HAX, ...)’

     Operate on the axes in handle HAX instead of the current axes.

     See also: *note axis: XREFaxis, *note pbaspect: XREFpbaspect, *note
     xlim: XREFxlim, *note ylim: XREFylim, *note zlim: XREFzlim.

 -- : PLOT_BOX_ASPECT_RATIO = pbaspect ( )
 -- : pbaspect (PLOT_BOX_ASPECT_RATIO)
 -- : pbaspect (MODE)
 -- : PLOT_BOX_ASPECT_RATIO_MODE = pbaspect ("mode")
 -- : pbaspect (HAX, ...)

     Query or set the plot box aspect ratio of the current axes.

     The aspect ratio is a normalized 3-element vector representing the
     rendered lengths of the x, y, and z axes.

     ‘pbaspect(MODE)’

     Set the plot box aspect ratio mode of the current axes.  MODE is
     either "auto" or "manual".

     ‘pbaspect ("mode")’

     Return the plot box aspect ratio mode of the current axes.

     ‘pbaspect (HAX, ...)’

     Operate on the axes in handle HAX instead of the current axes.

     See also: *note axis: XREFaxis, *note daspect: XREFdaspect, *note
     xlim: XREFxlim, *note ylim: XREFylim, *note zlim: XREFzlim.


File: octave.info,  Node: Three-dimensional Function Plotting,  Next: Three-dimensional Geometric Shapes,  Prev: Aspect Ratio,  Up: Three-Dimensional Plots

15.2.2.2 Three-dimensional Function Plotting
............................................

 -- : ezplot3 (FX, FY, FZ)
 -- : ezplot3 (..., DOM)
 -- : ezplot3 (..., N)
 -- : ezplot3 (..., "animate")
 -- : ezplot3 (HAX, ...)
 -- : H = ezplot3 (...)

     Plot a parametrically defined curve in three dimensions.

     FX, FY, and FZ are strings, inline functions, or function handles
     with one argument defining the function.  By default the plot is
     over the domain ‘0 <= T <= 2*pi’ with 500 points.

     If DOM is a two element vector, it represents the minimum and
     maximum values of T.

     N is a scalar defining the number of points to use in plotting the
     function.

     If the "animate" option is given then the plotting is animated in
     the style of ‘comet3’.

     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
     plot.

          fx = @(t) cos (t);
          fy = @(t) sin (t);
          fz = @(t) t;
          ezplot3 (fx, fy, fz, [0, 10*pi], 100);

     See also: *note plot3: XREFplot3, *note comet3: XREFcomet3, *note
     ezplot: XREFezplot, *note ezmesh: XREFezmesh, *note ezsurf:
     XREFezsurf.

 -- : ezmesh (F)
 -- : ezmesh (FX, FY, FZ)
 -- : ezmesh (..., DOM)
 -- : ezmesh (..., N)
 -- : ezmesh (..., "circ")
 -- : ezmesh (HAX, ...)
 -- : H = ezmesh (...)

     Plot the mesh defined by a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If three functions are passed, then plot the parametrically defined
     function ‘[FX(S, T), FY(S, T), FZ(S, T)]’.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the argument "circ" is given, then the function is plotted over
     a disk centered on the middle of the domain DOM.

     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.

     Example 1: 2-argument function

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezmesh (f, [-3, 3]);

     Example 2: parametrically defined function

          fx = @(s,t) cos (s) .* cos (t);
          fy = @(s,t) sin (s) .* cos (t);
          fz = @(s,t) sin (t);
          ezmesh (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);

     See also: *note mesh: XREFmesh, *note ezmeshc: XREFezmeshc, *note
     ezplot: XREFezplot, *note ezsurf: XREFezsurf, *note ezsurfc:
     XREFezsurfc, *note hidden: XREFhidden.

 -- : ezmeshc (F)
 -- : ezmeshc (FX, FY, FZ)
 -- : ezmeshc (..., DOM)
 -- : ezmeshc (..., N)
 -- : ezmeshc (..., "circ")
 -- : ezmeshc (HAX, ...)
 -- : H = ezmeshc (...)

     Plot the mesh and contour lines defined by a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If three functions are passed, then plot the parametrically defined
     function ‘[FX(S, T), FY(S, T), FZ(S, T)]’.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the argument "circ" is given, then the function is plotted over
     a disk centered on the middle of the domain DOM.

     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 2-element vector with a graphics
     handle for the created mesh plot and a second handle for the
     created contour plot.

     Example: 2-argument function

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezmeshc (f, [-3, 3]);

     See also: *note meshc: XREFmeshc, *note ezmesh: XREFezmesh, *note
     ezplot: XREFezplot, *note ezsurf: XREFezsurf, *note ezsurfc:
     XREFezsurfc, *note hidden: XREFhidden.

 -- : ezsurf (F)
 -- : ezsurf (FX, FY, FZ)
 -- : ezsurf (..., DOM)
 -- : ezsurf (..., N)
 -- : ezsurf (..., "circ")
 -- : ezsurf (HAX, ...)
 -- : H = ezsurf (...)

     Plot the surface defined by a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If three functions are passed, then plot the parametrically defined
     function ‘[FX(S, T), FY(S, T), FZ(S, T)]’.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the argument "circ" is given, then the function is plotted over
     a disk centered on the middle of the domain DOM.

     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.

     Example 1: 2-argument function

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezsurf (f, [-3, 3]);

     Example 2: parametrically defined function

          fx = @(s,t) cos (s) .* cos (t);
          fy = @(s,t) sin (s) .* cos (t);
          fz = @(s,t) sin (t);
          ezsurf (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);

     See also: *note surf: XREFsurf, *note ezsurfc: XREFezsurfc, *note
     ezplot: XREFezplot, *note ezmesh: XREFezmesh, *note ezmeshc:
     XREFezmeshc, *note shading: XREFshading.

 -- : ezsurfc (F)
 -- : ezsurfc (FX, FY, FZ)
 -- : ezsurfc (..., DOM)
 -- : ezsurfc (..., N)
 -- : ezsurfc (..., "circ")
 -- : ezsurfc (HAX, ...)
 -- : H = ezsurfc (...)

     Plot the surface and contour lines defined by a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If three functions are passed, then plot the parametrically defined
     function ‘[FX(S, T), FY(S, T), FZ(S, T)]’.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the argument "circ" is given, then the function is plotted over
     a disk centered on the middle of the domain DOM.

     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 2-element vector with a graphics
     handle for the created surface plot and a second handle for the
     created contour plot.

     Example:

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezsurfc (f, [-3, 3]);

     See also: *note surfc: XREFsurfc, *note ezsurf: XREFezsurf, *note
     ezplot: XREFezplot, *note ezmesh: XREFezmesh, *note ezmeshc:
     XREFezmeshc, *note shading: XREFshading.


File: octave.info,  Node: Three-dimensional Geometric Shapes,  Prev: Three-dimensional Function Plotting,  Up: Three-Dimensional Plots

15.2.2.3 Three-dimensional Geometric Shapes
...........................................

 -- : cylinder
 -- : cylinder (R)
 -- : cylinder (R, N)
 -- : cylinder (HAX, ...)
 -- : [X, Y, Z] = cylinder (...)
     Plot a 3-D unit cylinder.

     The optional input R is a vector specifying the radius along the
     unit z-axis.  The default is [1 1] indicating radius 1 at ‘Z == 0’
     and at ‘Z == 1’.

     The optional input N determines the number of faces around the
     circumference of the cylinder.  The default value is 20.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     If outputs are requested ‘cylinder’ returns three matrices in
     ‘meshgrid’ format, such that ‘surf (X, Y, Z)’ generates a unit
     cylinder.

     Example:

          [x, y, z] = cylinder (10:-1:0, 50);
          surf (x, y, z);
          title ("a cone");

     See also: *note ellipsoid: XREFellipsoid, *note rectangle:
     XREFrectangle, *note sphere: XREFsphere.

 -- : sphere ()
 -- : sphere (N)
 -- : sphere (HAX, ...)
 -- : [X, Y, Z] = sphere (...)
     Plot a 3-D unit sphere.

     The optional input N determines the number of faces around the
     circumference of the sphere.  The default value is 20.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     If outputs are requested ‘sphere’ returns three matrices in
     ‘meshgrid’ format such that ‘surf (X, Y, Z)’ generates a unit
     sphere.

     Example:

          [x, y, z] = sphere (40);
          surf (3*x, 3*y, 3*z);
          axis equal;
          title ("sphere of radius 3");

     See also: *note cylinder: XREFcylinder, *note ellipsoid:
     XREFellipsoid, *note rectangle: XREFrectangle.

 -- : ellipsoid (XC, YC, ZC, XR, YR, ZR, N)
 -- : ellipsoid (..., N)
 -- : ellipsoid (HAX, ...)
 -- : [X, Y, Z] = ellipsoid (...)
     Plot a 3-D ellipsoid.

     The inputs XC, YC, ZC specify the center of the ellipsoid.  The
     inputs XR, YR, ZR specify the semi-major axis lengths.

     The optional input N determines the number of faces around the
     circumference of the cylinder.  The default value is 20.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     If outputs are requested ‘ellipsoid’ returns three matrices in
     ‘meshgrid’ format, such that ‘surf (X, Y, Z)’ generates the
     ellipsoid.

     See also: *note cylinder: XREFcylinder, *note rectangle:
     XREFrectangle, *note sphere: XREFsphere.


File: octave.info,  Node: Plot Annotations,  Next: Multiple Plots on One Page,  Prev: Three-Dimensional Plots,  Up: High-Level Plotting

15.2.3 Plot Annotations
-----------------------

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

     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)");

   The functions ‘grid’ and ‘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.

   Finally, arrows, text and rectangular or elliptic boxes can be added
to highlight parts of a plot using the ‘annotation’ function.  Those
objects are drawn in an invisible axes, on top of every other axes.

 -- : title (STRING)
 -- : title (STRING, PROP, VAL, ...)
 -- : title (HAX, ...)
 -- : H = title (...)
     Specify the string used as a title for the current axis.

     An optional list of PROPERTY/VALUE pairs can be used to change the
     appearance of the created title text object.

     If the first argument HAX is an axes or legend handle, then add a
     title to this object, rather than the current axes returned by
     ‘gca’.

     The optional return value H is a graphics handle to the created
     text object.

     See also: *note xlabel: XREFxlabel, *note ylabel: XREFylabel, *note
     zlabel: XREFzlabel, *note text: XREFtext.

 -- : legend ()
 -- : legend COMMAND
 -- : legend (STR1, STR2, ...)
 -- : legend (CHARMAT)
 -- : legend ({CELLSTR})
 -- : legend (..., PROPERTY, VALUE, ...)
 -- : legend (HOBJS, ...)
 -- : legend ("COMMAND")
 -- : legend (HAX, ...)
 -- : legend (HLEG, ...)
 -- : HLEG, HPLT = legend (...)

     Display a legend for the current axes using the specified strings
     as labels.

     Legend entries may be specified as individual character string
     arguments, a character array, or a cell array of character strings.
     When label names might be confused with legend properties, or
     COMMAND arguments, the labels should be protected by specifying
     them as a cell array of strings.

     If the first argument HAX is an axes handle, then add a legend to
     this axes, rather than the current axes returned by ‘gca’.

     If the first argument HLEG is a legend handle, then operate on this
     legend rather than the legend of the current axes.

     Legend labels are associated with the axes’ children; The first
     label is assigned to the first object that was plotted in the axes,
     the second label to the next object plotted, etc.  To label
     specific data objects, without labeling all objects, provide their
     graphic handles in the input HOBJS.

     The following customizations are available using COMMAND:

     "show"
          Show legend on the plot

     "hide"
          Hide legend on the plot

     "toggle"
          Toggle between "hide" and "show"

     "boxon"
          Show a box around legend (default)

     "boxoff"
          Hide the box around legend

     "right"
          Place label text to the right of the keys (default)

     "left"
          Place label text to the left of the keys

     "off"
          Delete the legend object

     The ‘legend’ function creates a graphics object which has various
     properties that can be manipulated with ‘get’/‘set’.
     Alternatively, properties can be set directly when calling ‘legend’
     by including PROPERTY/VALUE pairs.  If using this calling form, the
     labels must be specified as a cell array of strings.  Graphics
     object properties are documented in detail at *note Graphics Object
     Properties::.

     Following is a subset of supported legend properties:

     ‘autoupdate’: "off" | {"on"}
          Control whether the number of legend items is updated
          automatically when objects are added to (or deleted from) the
          peer axes.  For example:

               ## Create a single plot with its legend.
               figure ();
               plot (1:10);
               legend ("Slope 1");
               ## Add another plot and specify its displayname so that
               ## the legend is correctly updated.
               hold on;
               plot ((1:10) * 2, "displayname", "Slope 2");
               ## Stop automatic updates for further plots.
               legend ("autoupdate", "off");
               plot ((1:10) * 3);

     ‘box’: "off" | {"on"}
          Control whether the legend has a surrounding box.

     ‘location’: "best" | "bestoutside" |
          "east" | "eastoutside" | "none" | "north" | {"northeast"} |
          "northeastoutside" | "northoutside" | "northwest"|
          "northwestoutside" | "south" | "southeast" |
          "southeastoutside" | "southoutside" | "southwest" |
          "southwestoutside" | "west" | "westoutside" Control the
          location of the legend.

     ‘numcolumns’: scalar interger, def. ‘1’
          Control the number of columns used in the layout of the legend
          items.  For example:

               figure ();
               plot (rand (30));
               legend ("numcolumns", 3);

          Setting ‘numcolumns’ also forces the ‘numcolumnsmode’ property
          to be set to "manual".

     ‘orientation’: "horizontal" | {"vertical"}
          Control whether the legend items are arranged vertically
          (column-wise) or horizontally (row-wise).

     ‘string’: string | cell array of strings
          List of labels for the legend items.  For example:

               figure ();
               plot (rand (20));
               ## Let legend choose names automatically
               hl = legend ();
               ## Selectively change some names
               str = get (hl, "string");
               str(1:5:end) = "Garbage";
               set (hl, "string", str);

     ‘textcolor’: colorspec, def. ‘[0 0 0]’
          Control the color of the text strings for legend item.

     The full list of supported legend specific properties can be found
     at *note Legend Properties: Legend Properties.

     A legend is implemented as an additional axes object with the ‘tag’
     property set to "legend".  Properties of the legend object may be
     manipulated directly by using ‘set’.

     The optional output value HLEG is a handle to the legend object.

     Implementation Note: The legend label text is either provided in
     the call to ‘legend’ or is taken from the ‘DisplayName’ property of
     the graphics objects.  Only data objects, such as line, patch, and
     surface, have this property whereas axes, figures, etc. do not so
     they are never present in a legend.  If no labels or ‘DisplayName’
     properties are available, then the label text is simply "data1",
     "data2", ..., "dataN".

     The legend ‘FontSize’ property is initially set to 90% of the axes
     ‘FontSize’ to which it is attached.  Use ‘set’ to override this if
     necessary.

 -- : text (X, Y, STRING)
 -- : text (X, Y, Z, STRING)
 -- : text (..., PROP, VAL, ...)
 -- : text (HAX, ...)
 -- : H = text (...)
     Create a text object with text STRING at position X, Y, (Z) on the
     current axes.

     Multiple locations can be specified if X, Y, (Z) are vectors.
     Multiple strings can be specified with a character matrix or a cell
     array of strings.

     Optional property/value pairs may be used to control the appearance
     of the text.

     If the first argument HAX is an axes handle, then add text to this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a vector of graphics handles to the
     created text objects.

     Example 1 : multi-line text via 3 different methods

          text (0.5, 0.8, {"Line 1", "Line 2"})
          text (0.5, 0.6, ["Line 1"; "Line 2"])
          text (0.5, 0.4, "Line 1\nLine 2")

     Example 2 : text at multiple locations

          text ([0.2, 0.2], [0.8, 0.6], "Same text at two locations")
          text ([0.4, 0.4], [0.8, 0.6], {"Point 1 Text", "Point 2 text"})
          text ([0.6, 0.6], [0.8, 0.6], {{"Point 1 Line 1", "Point 1 Line 2},
                                         "Point 2 text"})

     Example 2 : adjust appearance using text properties

          ht = text (0.5, 0.5, "Hello World", "fontsize", 20);
          set (ht, "color", "red");

     Programming Notes: The full list of properties is documented at
     *note Text Properties::.

     Any numeric entries in a cell array will be converted to text using
     ‘sprintf ("%g")’.  For more precise control of the appearance
     convert any numeric entries to strings using ‘num2str’, ‘sprintf’,
     etc., before calling ‘text’.

     See also: *note gtext: XREFgtext, *note title: XREFtitle, *note
     xlabel: XREFxlabel, *note ylabel: XREFylabel, *note zlabel:
     XREFzlabel.

 -- : xlabel (STRING)
 -- : xlabel (STRING, PROPERTY, VAL, ...)
 -- : xlabel (HAX, ...)
 -- : H = xlabel (...)
     Specify the string used to label the x-axis of the current axis.

     An optional list of PROPERTY/VALUE pairs can be used to change the
     properties of the created text label.

     The full list of text object properties is documented at *note Text
     Properties::.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     text object.

     See also: *note ylabel: XREFylabel, *note zlabel: XREFzlabel, *note
     datetick: XREFdatetick, *note title: XREFtitle, *note text:
     XREFtext.

 -- : clabel (C, H)
 -- : clabel (C, H, V)
 -- : clabel (C, H, "manual")
 -- : clabel (C)
 -- : clabel (..., PROP, VAL, ...)
 -- : H = clabel (...)
     Add labels to the contours of a contour plot.

     The contour levels are specified by the contour matrix C which is
     returned by ‘contour’, ‘contourc’, ‘contourf’, and ‘contour3’.
     Contour labels are rotated to match the local line orientation and
     centered on the line.  The position of labels along the contour
     line is chosen randomly.

     If the argument H is a handle to a contour group object, then label
     this plot rather than the one in the current axes returned by
     ‘gca’.

     By default, all contours are labeled.  However, the contours to
     label can be specified by the vector V.  If the "manual" argument
     is given then the contours to label can be selected with the mouse.

     Additional property/value pairs that are valid properties of text
     objects can be given and are passed to the underlying text objects.
     Moreover, the contour group property "LabelSpacing" is available
     which determines the spacing between labels on a contour to be
     specified.  The default is 144 points, or 2 inches.

     The optional return value H is a vector of graphics handles to the
     text objects representing each label.  The "userdata" property of
     the text objects contains the numerical value of the contour label.

     The full list of text object properties is documented at *note Text
     Properties::.

          [c, h] = contour (peaks (), -4 : 6);
          clabel (c, h, -4:2:6, "fontsize", 12);

     See also: *note contour: XREFcontour, *note contourf: XREFcontourf,
     *note contour3: XREFcontour3, *note meshc: XREFmeshc, *note surfc:
     XREFsurfc, *note text: XREFtext.

 -- : box
 -- : box on
 -- : box off
 -- : box (HAX, ...)
     Control display of the axes border.

     The argument may be either "on" or "off".  If it is omitted, the
     current box state is toggled.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     See also: *note axis: XREFaxis, *note grid: XREFgrid.

 -- : grid
 -- : grid on
 -- : grid off
 -- : grid minor
 -- : grid minor on
 -- : grid minor off
 -- : grid (HAX, ...)
     Control the display of plot grid lines.

     The function state input may be either "on" or "off".  If it is
     omitted, the current grid state is toggled.

     When the first argument is "minor" all subsequent commands modify
     the minor grid rather than the major grid.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     To control the grid lines for an individual axes use the ‘set’
     function.  For example:

          set (gca, "ygrid", "on");

     See also: *note axis: XREFaxis, *note box: XREFbox.

 -- : colorbar
 -- : colorbar (..., LOC)
 -- : colorbar (DELETE_OPTION)
 -- : colorbar (HCB, ...)
 -- : colorbar (HAX, ...)
 -- : colorbar (..., "peer", HAX, ...)
 -- : colorbar (..., "location", LOC, ...)
 -- : colorbar (..., PROP, VAL, ...)
 -- : H = colorbar (...)
     Add a colorbar to the current axes.

     A colorbar displays the current colormap along with numerical
     rulings so that the color scale can be interpreted.

     The optional input LOC determines the location of the colorbar.  If
     present, it must be the last argument to ‘colorbar’.  Valid values
     for LOC are

     "EastOutside"
          Place the colorbar outside the plot to the right.  This is the
          default.

     "East"
          Place the colorbar inside the plot to the right.

     "WestOutside"
          Place the colorbar outside the plot to the left.

     "West"
          Place the colorbar inside the plot to the left.

     "NorthOutside"
          Place the colorbar above the plot.

     "North"
          Place the colorbar at the top of the plot.

     "SouthOutside"
          Place the colorbar under the plot.

     "South"
          Place the colorbar at the bottom of the plot.

     To remove a colorbar from a plot use any one of the following
     keywords for the DELETE_OPTION: "off", "delete", "hide".

     If the first argument HAX is an axes handle, then the colorbar is
     added to this axes, rather than the current axes returned by ‘gca’.
     Alternatively, If the argument "peer" is given, then the following
     argument is treated as the axes handle in which to add the
     colorbar.  The "peer" calling syntax may be removed in the future
     and is not recommended.

     If the first argument HCB is a handle to a colorbar object, then
     operate on this colorbar directly.

     Additional property/value pairs are passed directly to the
     underlying axes object.  The full list of properties is documented
     at *note Axes Properties::.

     The optional return value H is a graphics handle to the created
     colorbar object.

     Implementation Note: A colorbar is created as an additional axes
     object with the "tag" property set to "colorbar".  The created
     object has the extra property "location" which controls the
     positioning of the colorbar.

     See also: *note colormap: XREFcolormap.

 -- : annotation (TYPE)
 -- : annotation ("line", X, Y)
 -- : annotation ("arrow", X, Y)
 -- : annotation ("doublearrow", X, Y)
 -- : annotation ("textarrow", X, Y)
 -- : annotation ("textbox", POS)
 -- : annotation ("rectangle", POS)
 -- : annotation ("ellipse", POS)
 -- : annotation (..., PROP, VAL)
 -- : annotation (HF, ...)
 -- : H = annotation (...)
     Draw annotations to emphasize parts of a figure.

     You may build a default annotation by specifying only the TYPE of
     the annotation.

     Otherwise you can select the type of annotation and then set its
     position using either X and Y coordinates for line-based
     annotations or a position vector POS for others.  In either case,
     coordinates are interpreted using the "units" property of the
     annotation object.  The default is "normalized", which means the
     lower left hand corner of the figure has coordinates ‘[0 0]’ and
     the upper right hand corner ‘[1 1]’.

     If the first argument HF is a figure handle, then plot into this
     figure, rather than the current figure returned by ‘gcf’.

     Further arguments can be provided in the form of PROP/VAL pairs to
     customize the annotation appearance.

     The optional return value H is a graphics handle to the created
     annotation object.  This can be used with the ‘set’ function to
     customize an existing annotation object.

     All annotation objects share two properties:

        • "units": the units in which coordinates are interpreted.
          Its value may be one of "centimeters" | "characters" |
          "inches" | "{normalized}" | "pixels" | "points".

        • "position": a four-element vector [x0 y0 width height].
          The vector specifies the coordinates (x0,y0) of the origin of
          the annotation object, its width, and its height.  The width
          and height may be negative, depending on the orientation of
          the object.

     Valid annotation types and their specific properties are described
     below:

     "line"
          Constructs a line.  X and Y must be two-element vectors
          specifying the x and y coordinates of the two ends of the
          line.

          The line can be customized using "linewidth", "linestyle", and
          "color" properties the same way as for ‘line’ objects.

     "arrow"
          Construct an arrow.  The second point in vectors X and Y
          specifies the arrowhead coordinates.

          Besides line properties, the arrowhead can be customized using
          "headlength", "headwidth", and "headstyle" properties.
          Supported values for "headstyle" property are: ["diamond" |
          "ellipse" | "plain" | "rectangle" | "vback1" | "{vback2}" |
          "vback3"]

     "doublearrow"
          Construct a double arrow.  Vectors X and Y specify the
          arrowhead coordinates.

          The line and the arrowhead can be customized as for arrow
          annotations, but some property names are duplicated:
          "head1length"/"head2length", "head1width"/"head2width", etc.
          The index 1 marks the properties of the arrowhead at the first
          point in X and Y coordinates.

     "textarrow"
          Construct an arrow with a text label at the opposite end from
          the arrowhead.

          Use the "string" property to change the text string.  The line
          and the arrowhead can be customized as for arrow annotations,
          and the text can be customized using the same properties as
          ‘text’ graphics objects.  Note, however, that some text
          property names are prefixed with "text" to distinguish them
          from arrow properties: "textbackgroundcolor", "textcolor",
          "textedgecolor", "textlinewidth", "textmargin",
          "textrotation".

     "textbox"
          Construct a box with text inside.  POS specifies the
          "position" property of the annotation.

          Use the "string" property to change the text string.  You may
          use "backgroundcolor", "edgecolor", "linestyle", and
          "linewidth" properties to customize the box background color
          and edge appearance.  A limited set of ‘text’ objects
          properties are also available; Besides "font..." properties,
          you may also use "horizontalalignment" and "verticalalignment"
          to position the text inside the box.

          Finally, the "fitboxtotext" property controls the actual
          extent of the box.  If "on" (the default) the box limits are
          fitted to the text extent.

     "rectangle"
          Construct a rectangle.  POS specifies the "position" property
          of the annotation.

          You may use "facecolor", "color", "linestyle", and "linewidth"
          properties to customize the rectangle background color and
          edge appearance.

     "ellipse"
          Construct an ellipse.  POS specifies the "position" property
          of the annotation.

          See "rectangle" annotations for customization.

     See also: *note xlabel: XREFxlabel, *note ylabel: XREFylabel, *note
     zlabel: XREFzlabel, *note title: XREFtitle, *note text: XREFtext,
     *note gtext: XREFgtext, *note legend: XREFlegend, *note colorbar:
     XREFcolorbar.


File: octave.info,  Node: Multiple Plots on One Page,  Next: Multiple Plot Windows,  Prev: Plot Annotations,  Up: High-Level Plotting

15.2.4 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 ‘subplot’ function to divide the plot area
into a series of subplot windows that are indexed by an integer.  For
example,

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

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 ‘subplot’ is
numbered in row-major order (left to right, top to bottom).  After
plotting a sine wave, the next call to subplot activates the second
subplot area, but does not re-partition the figure.

 -- : subplot (ROWS, COLS, INDEX)
 -- : subplot (ROWS, COLS, INDEX, HAX)
 -- : subplot (RCN)
 -- : subplot (HAX)
 -- : subplot (..., "align")
 -- : subplot (..., "replace")
 -- : subplot ("position", POS)
 -- : subplot (..., PROP, VAL, ...)
 -- : HAX = subplot (...)
     Set up a plot grid with ROWS by COLS subwindows and set the current
     axes for plotting (‘gca’) to the location given by INDEX.

     If an axes handle HAX is provided after the (ROWS, COLS, INDEX)
     arguments, the corresponding axes is turned into a subplot.

     If only one numeric argument is supplied, then it must be a three
     digit value specifying the number of rows in digit 1, the number of
     columns in digit 2, and the plot index in digit 3.

     The plot index runs row-wise; First, all columns in a row are
     numbered and then the next row is filled.

     For example, a plot with 2x3 grid will have plot indices running as
     follows:

          +-----+-----+-----+
          |  1  |  2  |  3  |
          +-----+-----+-----+
          |  4  |  5  |  6  |
          +-----+-----+-----+

     INDEX may also be a vector.  In this case, the new axes will
     enclose the grid locations specified.  The first demo illustrates
     this:

          demo ("subplot", 1)

     The index of the subplot to make active may also be specified by
     its axes handle, HAX, returned from a previous ‘subplot’ command.

     If the option "align" is given then the plot boxes of the
     subwindows will align, but this may leave no room for axes tick
     marks or labels.

     If the option "replace" is given then the subplot axes will be
     reset, rather than just switching the current axes for plotting to
     the requested subplot.

     The "position" property can be used to exactly position the subplot
     axes within the current figure.  The option POS is a 4-element
     vector [x, y, width, height] that determines the location and size
     of the axes.  The values in POS are normalized in the range [0,1].

     Any property/value pairs are passed directly to the underlying axes
     object.  The full list of properties is documented at *note Axes
     Properties::.

     Any previously existing axes that would be (partly) covered by the
     newly created axes are deleted.

     If the output HAX is requested, subplot returns the axes handle for
     the subplot.  This is useful for modifying the properties of a
     subplot using ‘set’.

     Under some circumstances, ‘subplot’ might not be able to identify
     axes that it could re-use and might replace them.  If ‘subplot’
     axes should be referenced repeatedly, consider creating and storing
     their axes handles beforehand instead of calling ‘subplot’
     repeatedly for the same position.

     Example:

          x = 1:10;
          y = rand (16, 10);
          for i_plot = 1:4
            hax(i_plot) = subplot (2, 2, i_plot);
            hold (hax(i_plot), "on");
            grid (hax(i_plot), "on");
          endfor
          for i_loop = 1:2
            for i_plot = 1:4
              iy = (i_loop - 1)*4 + i_plot;
              plotyy (hax(i_plot), x,y(iy,:), x,y(iy+1,:));
            endfor
           endfor

     See also: *note axes: XREFaxes, *note plot: XREFplot, *note gca:
     XREFgca, *note set: XREFset.


File: octave.info,  Node: Multiple Plot Windows,  Next: Manipulation of Plot Objects,  Prev: Multiple Plots on One Page,  Up: High-Level Plotting

15.2.5 Multiple Plot Windows
----------------------------

You can open multiple plot windows using the ‘figure’ function.  For
example,

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

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

 -- : figure
 -- : figure N
 -- : figure (N)
 -- : figure (..., "PROPERTY", VALUE, ...)
 -- : H = figure (...)
     Create a new figure window for plotting.

     If no arguments are specified, a new figure with the next available
     number is created.

     If called with an integer N, and no such numbered figure exists,
     then a new figure with the specified number is created.  If the
     figure already exists then it is made visible and becomes the
     current figure for plotting.

     Multiple property-value pairs may be specified for the figure
     object, but they must appear in pairs.

     The optional return value H is a graphics handle to the created
     figure object.

     Programming Note: The full list of properties is documented at
     *note Figure Properties::.

     See also: *note axes: XREFaxes, *note gcf: XREFgcf, *note shg:
     XREFshg, *note clf: XREFclf, *note close: XREFclose.


File: octave.info,  Node: Manipulation of Plot Objects,  Next: Manipulation of Plot Windows,  Prev: Multiple Plot Windows,  Up: High-Level Plotting

15.2.6 Manipulation of Plot Objects
-----------------------------------

 -- : pan
 -- : pan on
 -- : pan off
 -- : pan xon
 -- : pan yon
 -- : pan (HFIG, OPTION)
     Control the interactive panning mode of a figure in the GUI.

     Given the option "on" or "off", set the interactive pan mode on or
     off.

     With no arguments, toggle the current pan mode on or off.

     Given the option "xon" or "yon", enable pan mode for the x or y
     axis only.

     If the first argument HFIG is a figure, then operate on the given
     figure rather than the current figure as returned by ‘gcf’.

     See also: *note rotate3d: XREFrotate3d, *note zoom: XREFzoom.

 -- : rotate (H, DIRECTION, ALPHA)
 -- : rotate (..., ORIGIN)
     Rotate the plot object H through ALPHA degrees around the line with
     direction DIRECTION and origin ORIGIN.

     The default value of ORIGIN is the center of the axes object that
     is the parent of H.

     If H is a vector of handles, they must all have the same parent
     axes object.

     Graphics objects that may be rotated are lines, surfaces, patches,
     and images.

 -- : rotate3d
 -- : rotate3d on
 -- : rotate3d off
 -- : rotate3d (HFIG, OPTION)
     Control the interactive 3-D rotation mode of a figure in the GUI.

     Given the option "on" or "off", set the interactive rotate mode on
     or off.

     With no arguments, toggle the current rotate mode on or off.

     If the first argument HFIG is a figure, then operate on the given
     figure rather than the current figure as returned by ‘gcf’.

     See also: *note pan: XREFpan, *note zoom: XREFzoom.

 -- : zoom
 -- : zoom (FACTOR)
 -- : zoom on
 -- : zoom off
 -- : zoom xon
 -- : zoom yon
 -- : zoom out
 -- : zoom reset
 -- : zoom (HFIG, OPTION)
     Zoom the current axes object or control the interactive zoom mode
     of a figure in the GUI.

     Given a numeric argument greater than zero, zoom by the given
     factor.  If the zoom factor is greater than one, zoom in on the
     plot.  If the factor is less than one, zoom out.  If the zoom
     factor is a two- or three-element vector, then the elements specify
     the zoom factors for the x, y, and z axes respectively.

     Given the option "on" or "off", set the interactive zoom mode on or
     off.

     With no arguments, toggle the current zoom mode on or off.

     Given the option "xon" or "yon", enable zoom mode for the x or
     y-axis only.

     Given the option "out", zoom to the initial zoom setting.

     Given the option "reset", store the current zoom setting so that
     ‘zoom out’ will return to this zoom level.

     If the first argument HFIG is a figure, then operate on the given
     figure rather than the current figure as returned by ‘gcf’.

     See also: *note pan: XREFpan, *note rotate3d: XREFrotate3d.


File: octave.info,  Node: Manipulation of Plot Windows,  Next: Use of the interpreter Property,  Prev: Manipulation of Plot Objects,  Up: High-Level Plotting

15.2.7 Manipulation of Plot Windows
-----------------------------------

By default, Octave refreshes the plot window when a prompt is printed,
or when waiting for input.  The ‘drawnow’ function is used to cause a
plot window to be updated.

 -- : drawnow ()
 -- : drawnow ("expose")
 -- : drawnow (TERM, FILE, DEBUG_FILE)
     Update figure windows and their children.

     The event queue is flushed and any callbacks generated are
     executed.

     With the optional argument "expose", only graphic objects are
     updated and no other events or callbacks are processed.

     The third calling form of ‘drawnow’ is for debugging and is
     undocumented.

     See also: *note refresh: XREFrefresh.

   Only figures that are modified will be updated.  The ‘refresh’
function can also be used to cause an update of the current figure, even
if it is not modified.

 -- : refresh ()
 -- : refresh (H)
     Refresh a figure, forcing it to be redrawn.

     When called without an argument the current figure is redrawn.
     Otherwise, the figure with graphic handle H is redrawn.

     See also: *note drawnow: XREFdrawnow.

   Normally, high-level plot functions like ‘plot’ or ‘mesh’ call
‘newplot’ to determine whether the state of the target axes should be
initialized (the default) or if subsequent plots should be drawn on top
of previous ones.  To have two plots drawn over one another, use the
‘hold’ function or manually change the axes *note nextplot:
XREFaxesnextplot. property.  For example,

     hold on;
     x = -10:0.1:10;
     plot (x, sin (x));
     plot (x, cos (x));
     hold off;

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.

 -- : newplot ()
 -- : newplot (HFIG)
 -- : newplot (HAX)
 -- : HAX = newplot (...)
     Prepare graphics engine to produce a new plot.

     This function is called at the beginning of all high-level plotting
     functions.  It is not normally required in user programs.
     ‘newplot’ queries the "NextPlot" field of the current figure and
     axes to determine what to do.

     Figure NextPlot    Action
     --------------------------------------------------------------------------
     "new"              Create a new figure and make it the current figure.
                        
     "add" (default)    Add new graphic objects to the current figure.
                        
     "replacechildren"  Delete child objects whose HandleVisibility is set
                        to "on".  Set NextPlot property to "add".  This
                        typically clears a figure, but leaves in place
                        hidden objects such as menubars.  This is equivalent
                        to ‘clf’.
                        
     "replace"          Delete all child objects of the figure and reset all
                        figure properties to their defaults.  However, the
                        following four properties are not reset: Position,
                        Units, PaperPosition, PaperUnits.  This is
                        equivalent to ‘clf reset’.

     Axes NextPlot      Action
     --------------------------------------------------------------------------
     "add"              Add new graphic objects to the current axes.  This
                        is equivalent to ‘hold on’.
                        
     "replacechildren"  Delete child objects whose HandleVisibility is set
                        to "on", but leave axes properties unmodified.  This
                        typically clears a plot, but preserves special
                        settings such as log scaling for axes.  This is
                        equivalent to ‘cla’.
                        
     "replace"          Delete all child objects of the axes and reset all
     (default)          axes properties to their defaults.  However, the
                        following properties are not reset: Position, Units.
                        This is equivalent to ‘cla reset’.

     If the optional input HFIG or HAX is given then prepare the
     specified figure or axes rather than the current figure and axes.

     The optional return value HAX is a graphics handle to the created
     axes object (not figure).

     *Caution:* Calling ‘newplot’ may change the current figure and
     current axes.

 -- : hold
 -- : hold on
 -- : hold off
 -- : hold (HAX, ...)
     Toggle or set the "hold" state of the plotting engine which
     determines whether new graphic objects are added to the plot or
     replace the existing objects.

     ‘hold on’
          Retain plot data and settings so that subsequent plot commands
          are displayed on a single graph.  Line color and line style
          are advanced for each new plot added.

     ‘hold all (deprecated)’
          Equivalent to ‘hold on’.

     ‘hold off’
          Restore default graphics settings which clear the graph and
          reset axes properties before each new plot command.
          (default).

     ‘hold’
          Toggle the current hold state.

     When given the additional argument HAX, the hold state is modified
     for this axes rather than the current axes returned by ‘gca’.

     To query the current hold state use the ‘ishold’ function.

     See also: *note ishold: XREFishold, *note cla: XREFcla, *note clf:
     XREFclf, *note newplot: XREFnewplot.

 -- : ishold
 -- : ishold (HAX)
 -- : ishold (HFIG)
     Return true if the next plot will be added to the current plot, or
     false if the plot device will be cleared before drawing the next
     plot.

     If the first argument is an axes handle HAX or figure handle HFIG
     then operate on this plot rather than the current one.

     See also: *note hold: XREFhold, *note newplot: XREFnewplot.

   To clear the current figure, call the ‘clf’ function.  To clear the
current axis, call the ‘cla’ function.  To bring the current figure to
the top of the window stack, call the ‘shg’ function.  To delete a
graphics object, call ‘delete’ on its index.  To close the figure
window, call the ‘close’ function.

 -- : clf
 -- : clf reset
 -- : clf (HFIG)
 -- : clf (HFIG, "reset")
 -- : H = clf (...)
     Clear the current figure window.

     ‘clf’ operates by deleting child graphics objects with visible
     handles (HandleVisibility = "on").

     If the optional argument "reset" is specified, delete all child
     objects including those with hidden handles and reset all figure
     properties to their defaults.  However, the following properties
     are not reset: Position, Units, PaperPosition, PaperUnits.

     If the first argument HFIG is a figure handle, then operate on this
     figure rather than the current figure returned by ‘gcf’.

     The optional return value H is the graphics handle of the figure
     window that was cleared.

     See also: *note cla: XREFcla, *note close: XREFclose, *note delete:
     XREFdelete, *note reset: XREFreset.

 -- : cla
 -- : cla reset
 -- : cla (HAX)
 -- : cla (HAX, "reset")
     Clear the current or specified (HAX) axes object.

     ‘cla’ operates by deleting child graphic objects with visible
     handles (‘HandleVisibility’ = "on").  This typically clears the
     axes of any visual objects, but leaves in place axes limits, tick
     marks and labels, camera view, etc.  In addition, the automatic
     coloring and styling of lines is reset by changing the axes
     properties ‘ColorOrderIndex’, ‘LinestyleOrderIndex’ to 1.

     If the optional argument "reset" is specified, delete all child
     objects, including those with hidden handles, and reset all axes
     properties to their defaults.  However, the following properties
     are not reset: ‘Position’, ‘Units’.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     See also: *note clf: XREFclf, *note delete: XREFdelete, *note
     reset: XREFreset.

 -- : shg
     Show the graph window.

     This function makes the current figure visible, and places it on
     top of of all other plot windows.

     Programming Note: ‘shg’ is equivalent to ‘figure (gcf)’ assuming
     that a current figure exists.

     See also: *note figure: XREFfigure, *note drawnow: XREFdrawnow,
     *note gcf: XREFgcf.

 -- : delete (FILE)
 -- : delete (FILE1, FILE2, ...)
 -- : delete (HANDLE)
     Delete the named file or graphics handle.

     FILE may contain globbing patterns such as ‘*’.  Multiple files to
     be deleted may be specified in the same function call.

     HANDLE may be a scalar or vector of graphic handles to delete.

     Programming Note: Deleting graphics objects is the proper way to
     remove features from a plot without clearing the entire figure.

     See also: *note clf: XREFclf, *note cla: XREFcla, *note unlink:
     XREFunlink, *note rmdir: XREFrmdir.

 -- : close
 -- : close (H)
 -- : close FIGNAME
 -- : close all
 -- : close all hidden
 -- : close all force
     Close figure window(s).

     When called with no arguments, close the current figure.  This is
     equivalent to ‘close (gcf)’.  If the input H is a graphic handle,
     or vector of graphics handles, then close each figure in H.  The
     figure to close may also be specified by name FIGNAME which is
     matched against the "Name" property of all figures.

     If the argument "all" is given then all figures with visible
     handles (HandleVisibility = "on") are closed.

     If the additional argument "hidden" is given then all figures,
     including hidden ones, are closed.

     If the additional argument "force" is given then figures are closed
     even when "closerequestfcn" has been altered to prevent closing the
     window.

     Implementation Note: ‘close’ operates by making the handle H the
     current figure, and then calling the function specified by the
     "closerequestfcn" property of the figure.  By default, the function
     ‘closereq’ is used.  It is possible that the function invoked will
     delay or abort removing the figure.  To remove a figure without
     executing any callback functions use ‘delete’.  When writing a
     callback function to close a window do not use ‘close’ to avoid
     recursion.

     See also: *note closereq: XREFclosereq, *note delete: XREFdelete.

 -- : closereq ()
     Close the current figure and delete all graphics objects associated
     with it.

     By default, the "closerequestfcn" property of a new plot figure
     points to this function.

     See also: *note close: XREFclose, *note delete: XREFdelete.


File: octave.info,  Node: Use of the interpreter Property,  Next: Printing and Saving Plots,  Prev: Manipulation of Plot Windows,  Up: High-Level Plotting

15.2.8 Use of the ‘interpreter’ Property
----------------------------------------

‘text’ (such as titles, labels, legend item) and ‘axes’ objects feature
a *note interpreter: XREFtextinterpreter. and *note
ticklabelinterpreter: XREFaxesticklabelinterpreter. property
respectively.  It determines the manner in which special control
sequences in the text are rendered.

   The interpreter property can take three values: "none", "tex",
"latex".

* Menu:

* none interpreter::
* tex interpreter::
* latex interpreter::


File: octave.info,  Node: none interpreter,  Next: tex interpreter,  Up: Use of the interpreter Property

15.2.8.1 ‘none’ interpreter
...........................

If the interpreter is set to "none" then no special rendering occurs—the
displayed text is a verbatim copy of the specified text.


File: octave.info,  Node: tex interpreter,  Next: latex interpreter,  Prev: none interpreter,  Up: Use of the interpreter Property

15.2.8.2 ‘tex’ interpreter
..........................

The "tex" interpreter implements a subset of TeX functionality when
rendering text.  This allows the insertion of special glyphs such as
Greek characters or mathematical symbols.  Special characters are
inserted by using a backslash (\) character followed by a code, as shown
in *note Table 15.1: tab:extended.

   Besides special glyphs, the formatting of the text can be changed
within the string by using the codes

               \bf            Bold font
               \it            Italic font
               \sl            Oblique Font
               \rm            Normal font

   These codes may be used in conjunction with the { and } characters to
limit the change to a part of the string.  For example,

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

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

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

        \fontname{FONTNAME}           Specify the font to use
        \fontsize{SIZE}               Specify the size of the font to use

   The color of the text may also be changed inline using either a
string (e.g., "red") or numerically with a Red-Green-Blue (RGB)
specification (e.g., [1 0 0], also red).

        \color{COLOR}                 Specify the color as a string
        \color[rgb]{R G B}            Specify the color numerically

   Finally, superscripting 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 superscripted or
subscripted.  Without the { } pair, only the character immediately
following the ’^’ or ’_’ is changed.

Greek Lowercase
Letters
                   \alpha             \beta              \gamma
                   \delta             \epsilon           \zeta
                   \eta               \theta             \vartheta
                   \iota              \kappa             \lambda
                   \mu                \nu                \xi
                   \o                 \pi                \varpi
                   \rho               \sigma             \varsigma
                   \tau               \upsilon           \phi
                   \chi               \psi               \omega
Greek Uppercase
Letters
                   \Gamma             \Delta             \Theta
                   \Lambda            \Xi                \Pi
                   \Sigma             \Upsilon           \Phi
                   \Psi               \Omega
Misc Symbols
Type Ord
                   \aleph             \wp                \Re
                   \Im                \partial           \infty
                   \prime             \nabla             \surd
                   \angle             \forall            \exists
                   \neg               \clubsuit          \diamondsuit
                   \heartsuit         \spadesuit
“Large”
Operators
                   \int
Binary Operators
                   \pm                \cdot              \times
                   \ast               \circ              \bullet
                   \div               \cap               \cup
                   \vee               \wedge             \oplus
                   \otimes            \oslash
Relations
                   \leq               \subset            \subseteq
                   \in                \geq               \supset
                   \supseteq          \ni                \mid
                   \equiv             \sim               \approx
                   \cong              \propto            \perp
Arrows
                   \leftarrow         \Leftarrow         \rightarrow
                   \Rightarrow        \leftrightarrow    \uparrow
                   \downarrow
Openings and
Closings
                   \lfloor            \langle            \lceil
                   \rfloor            \rangle            \rceil
Alternate Names
                   \neq
Other
                   \ldots             \0                 \copyright
                   \deg


Table 15.1: Available special characters in TeX mode

   *Caution: Degree Symbol*

   Conformance to both TeX and MATLAB with respect to the ‘\circ’ symbol
is impossible.  While TeX translates this symbol to Unicode 2218
(U+2218), MATLAB maps this to Unicode 00B0 (U+00B0) instead.  Octave has
chosen to follow the TeX specification, but has added the additional
symbol ‘\deg’ which maps to the degree symbol (U+00B0).


File: octave.info,  Node: latex interpreter,  Prev: tex interpreter,  Up: Use of the interpreter Property

15.2.8.3 ‘latex’ interpreter
............................

The "latex" interpreter only works if an external LaTeX tool chain is
present.  Three binaries are needed: ‘latex’, ‘dvipng’, and ‘dvisvgm’.
If those binaries are installed but not on the path, one can still
provide their respective path using the following environment variables:
‘OCTAVE_LATEX_BINARY’, ‘OCTAVE_DVIPNG_BINARY’, and
‘OCTAVE_DVISVG_BINARY’.

   Note that Octave does not parse or validate the text strings when in
"latex" mode—it is the responsibility of the programmer to generate
valid strings which may include wrapping sections that should appear in
Math mode with ’$’ characters.  See, for example,
<https://www.latex-project.org/help/documentation/> for documentation
about LaTeX typesetting.

   For debugging purpose, a convenience environment variable,
‘OCTAVE_LATEX_DEBUG_FLAG’, can be set to trigger more verbose output
when Octave fails to have a given text compiled by an external LaTeX
engine.  For example, "x^2" is not a valid LaTeX string and the
following example should fail

     setenv ("OCTAVE_LATEX_DEBUG_FLAG", "1")
     x = 1:10;
     plot (x, x.^2)
     title ("x^2", "interpreter", "latex")

   Searching the terminal output you should find some helpful info about
the origin of the failure:

     ...
     No file default.aux.
     ! Missing $ inserted.
     <inserted text>
                     $
     l.6 x^
           2
     ! Missing $ inserted.
     ...

   If no usable LaTeX tool chain is found at the first text rendering,
using the "latex" interpreter is equivalent to "none".


File: octave.info,  Node: Printing and Saving Plots,  Next: Interacting with Plots,  Prev: Use of the interpreter Property,  Up: High-Level Plotting

15.2.9 Printing and Saving Plots
--------------------------------

The ‘print’ command allows you to send plots to you printer and to save
plots in a variety of formats.  For example,

     print -dpsc

prints the current figure to a color PostScript printer.  And,

     print -deps foo.eps

saves the current figure to an encapsulated PostScript file called
‘foo.eps’.

   The current graphic toolkits produce very similar graphic displays,
but differ in their capability to display unusual text and in their
ability to print such text.  In general, the "tex" interpreter (default)
is the best all-around performer for both on-screen display and
printing.  However, for the reproduction of complicated text formulas
the "latex" interpreter is preferred.  When printing with the
‘-painters’ renderer, the default for all vector formats, two options
may be considered:

   • Use the ‘-svgconvert’ option to allow for rendering LaTeX formulas.
     Note that the glyph are rendered as path and the original textual
     info are lost.

   • Use one of the ‘-d*latex*’ devices to produce a .tex file (plus
     supporting .eps or .pdf files) to be further processed by an
     external LaTeX engine.  Note that the ‘print’ function will first
     set the interpreter of all strings to "latex", which means all
     strings must be valid LaTeX strings.

   A complete example showing the capabilities of text printing using
the ‘-dpdflatexstandalone’ option is:

     x = 0:0.01:3;
     hf = figure ();
     plot (x, erf (x));
     hold on;
     plot (x, x, "r");
     axis ([0, 3, 0, 1]);
     text (0.65, 0.6175, ...
           ['$\displaystyle\leftarrow x = {2 \over \sqrt{\pi}}' ...
            '\int_{0}^{x} e^{-t^2} dt = 0.6175$'],
           "interpreter", "latex");
     xlabel ("x");
     ylabel ("erf (x)");
     title ("erf (x) with text annotation");
     print (hf, "plot15_7", "-dpdflatexstandalone");
     system ("pdflatex plot15_7");
     open plot15_7.pdf

 -- : print ()
 -- : print (OPTIONS)
 -- : print (FILENAME, OPTIONS)
 -- : print (HFIG, ...)
 -- : RGB = print ("-RGBImage", ...)
     Format a figure for printing and either save it to a file, send it
     to a printer, or return an RGB image.

     FILENAME defines the name of the output file.  If the filename has
     no suffix then one is inferred from the specified device and
     appended to the filename.  When neither a filename nor the
     "-RGBImage" option is present, the output is sent to the printer.
     The various options and filename arguments may be given in any
     order, except for the figure handle argument HFIG which must be
     first if it is present.

     Example: Print to a file using PDF and JPEG formats.

          figure (1);
          clf ();
          surf (peaks);
          print figure1.pdf    # The extension specifies the format
          print -djpg figure1  # Will produce "figure1.jpg" file

     If the first argument is a handle HFIG to a figure object then it
     specifies the figure to print.  By default, the current figure
     returned by ‘gcf’ is printed.

     For outputs to paged formats, for example, PostScript and PDF, the
     page size is specified by the figure’s ‘papersize’ property
     together with the ‘paperunits’ property.  The location and size of
     the plot on the page are specified by the figure’s ‘paperposition’
     property.  The orientation of the page is specified by the figure’s
     ‘paperorientation’ property.

     For non-page formats—for example, image formats like JPEG—the width
     and height of the output are specified by the figure’s
     ‘paperposition(3:4)’ property values.

     The ‘print’ command supports many OPTIONS:

     ‘-fH’
          Specify the handle, H, of the figure to be printed.

          Example: Print figure 1.

               figure (1);
               clf ();
               surf (peaks);
               figure (2);
               print -f1 figure1.pdf
               ## Equivalent functional form:
               print (1, "figure1.pdf")

     ‘-PPRINTER’
          Set the PRINTER name to which the plot is sent if no FILENAME
          is specified.

          Example: Print to printer named PS_printer using PostScript
          format.

               clf ();
               surf (peaks);
               print -dpswrite -PPS_printer

     ‘-RGBImage’
          Return an M-by-N-by-3 RGB image of the figure.  The size of
          the image depends on the formatting options.  This is similar
          to taking a screen capture of the plot, but formatting options
          may be changed such as the resolution or monochrome/color.

          Example: Get the pixels of a figure image.

               clf ();
               surf (peaks);
               RGB = print ("-RGBImage");

     ‘-opengl’
     ‘-painters’
          Specifies whether the opengl (pixel-based) or painters
          (vector-based) renderer is used.  This is equivalent to
          changing the figure’s "Renderer" property.  When the figure
          "RendererMode" property is "auto" (the default) Octave will
          use the "opengl" renderer for raster formats (e.g., JPEG) and
          "painters" for vector formats (e.g., PDF). Those options are
          only supported for the "qt" graphics toolkit.

     ‘-svgconvert’
          When using the ‘-painters’ renderer, this enables a different
          backend toolchain with enhanced characteristics:

          Font handling:
               For interpreters "none" and "tex", the actual font is
               embedded in the output file which allows for printing
               arbitrary characters and fonts in all vector formats.

               Strings using the "latex" interpreter, are rendered using
               path objects.  This looks good but note that textual info
               (font, characters...) are lost.

          Output Simplification:
               By default, the option ‘-painters’ renders patch and
               surface objects using assemblies of triangles.  This may
               lead to anti-aliasing artifacts when viewing the file.
               The ‘-svgconvert’ option reconstructs polygons in order
               to avoid those artifacts (particularly for 2-D figures).

          Transparency:
               Allows for printing transparent graphics objects in PDF
               format.  For PostScript formats the presence of any
               transparent object will cause the output to be
               rasterized.

          Caution: ‘-svgconvert’ may lead to inaccurate rendering of
          image objects.

     ‘-portrait’
     ‘-landscape’
          Specify the orientation of the plot for printed output.  For
          non-printed output the aspect ratio of the output corresponds
          to the plot area defined by the "paperposition" property in
          the orientation specified.  This option is equivalent to
          changing the figure’s "paperorientation" property.

     ‘-fillpage’
     ‘-bestfit’
          When using a page-based format (PDF, PostScript, printer)
          ignore the "paperposition" property and have the plot occupy
          the entire page.  The option ‘-fillpage’ will stretch the plot
          to occupy the page with 0.25 inch margins all around.  The
          option ‘-bestfit’ will expand the plot to take up as much room
          as possible on the page *without* distorting the original
          aspect ratio of the plot.

     ‘-color’
     ‘-mono’
          Color or monochrome output.

     ‘-solid’
     ‘-dashed’
          Force all lines to be solid or dashed, respectively.

     ‘-noui’
          Don’t print uicontrol objects such as pushbuttons which may
          overlay the plot.  This is the default behavior and it is not
          possible to include uicontrol objects in the output without
          using an external screen capture tool.

     ‘-rNUM’
          Resolution of bitmaps in dots per inch (DPI). For both
          metafiles and SVG the default is the screen resolution; for
          other formats the default is 150 DPI.  To specify screen
          resolution, use "-r0".

          Example: high resolution raster output.

               clf ();
               surf (peaks (), "facelighting", "gouraud");
               light ();
               print ("-r600", "lit_peaks.png");

     ‘-SXSIZE,YSIZE’
          Plot size in pixels for raster formats including PNG, JPEG,
          PNG, and _unusually_ SVG.  For all vector formats, including
          PDF, PS, and EPS, the plot size is specified in points.  This
          option is equivalent to changing the width and height of the
          output by setting the figure property ‘paperposition(3:4)’.
          When using the command form of the print function you must
          quote the XSIZE,YSIZE option to prevent the Octave interpreter
          from recognizing the embedded comma (’,’).  For example, by
          writing "-S640,480".

     ‘-tight’
     ‘-loose’
          Force a tight or loose bounding box for EPS files.  The
          default is tight.

     ‘-PREVIEW’
          Add a preview to EPS files.  Supported formats are:

          ‘-interchange’
               Provide an interchange preview.

          ‘-metafile’
               Provide a metafile preview.

          ‘-pict’
               Provide a pict preview.

          ‘-tiff’
               Provide a TIFF preview.

     ‘-append’
          Append PostScript or PDF output to an existing file of the
          same type.

     ‘-FFONTNAME’
     ‘-FFONTNAME:SIZE’
     ‘-F:SIZE’
          Use FONTNAME and/or FONTSIZE for all text.  FONTNAME is
          ignored for some devices: fig, etc.

     ‘-dDEVICE’
          The available output format is specified by the option DEVICE,
          and is one of the following (devices marked with a ’*’ are
          only available with the Gnuplot toolkit):

          Vector Formats

          ‘svg’
               Scalable Vector Graphics.

          ‘pdf’
          ‘pdfcrop’
               Portable Document Format.  The ‘pdf’ device formats the
               figure for printing on paper.  The size of the
               surrounding page and the position of the figure inside
               the page are defined by the *note paper* figure
               properties: XREFfigurepaperorientation.

               Use ‘pdfcrop’ if you don’t want the surrounding page.

               By default, PDF inherits the same limitations as
               PostScript.  For an enhanced output with complete text
               support and basic transparency, use the ‘-svgconvert’
               option.

          ‘eps(2)’
          ‘epsc(2)’
               Encapsulated PostScript (level 1 and 2, mono and color).

               The OpenGL-based graphics toolkits always generate
               PostScript level 3.0.  They have limited support for text
               unless using the ‘-svgconvert’ option.  Limitations
               include using only ASCII characters (e.g., no Greek
               letters) and support for just three base PostScript
               fonts: Helvetica (the default), Times, or Courier.  Any
               other font will be replaced by Helvetica.

          ‘ps(2)’
          ‘psc(2)’
               Same as ‘eps’ except that the figure is formatted for
               printing on paper.  The size of the surrounding page and
               position of the figure inside the page are defined by the
               *note paper* figure properties:
               XREFfigurepaperorientation.

          ‘pslatex’
          ‘epslatex’
          ‘pdflatex’
          ‘pslatexstandalone’
          ‘epslatexstandalone’
          ‘pdflatexstandalone’
               Generate a LaTeX file ‘FILENAME.tex’ for the text
               portions of a plot and a file ‘FILENAME.(ps|eps|pdf)’ for
               the remaining graphics.  The graphics file suffix
               .ps|eps|pdf is determined by the specified device type.
               The LaTeX file produced by the ‘standalone’ option can be
               processed directly by LaTeX.  The file generated without
               the ‘standalone’ option is intended to be included from
               another LaTeX document.  In either case, the LaTeX file
               contains an ‘\includegraphics’ command so that the
               generated graphics file is automatically included when
               the LaTeX file is processed.  The text that is written to
               the LaTeX file contains the strings *exactly* as they
               were specified in the plot.  If any special characters of
               the TeX mode interpreter were used, the file must be
               edited before LaTeX processing.  Specifically, the
               special characters must be enclosed with dollar signs
               (‘$ ... $’), and other characters that are recognized by
               LaTeX may also need editing (e.g., braces).  The
               ‘pdflatex’ device, and any of the ‘standalone’ formats,
               are not available with the Gnuplot toolkit.

          ‘epscairo*’
          ‘pdfcairo*’
          ‘epscairolatex*’
          ‘pdfcairolatex*’
          ‘epscairolatexstandalone*’
          ‘pdfcairolatexstandalone*’
               Generate output with Cairo renderer.  The devices
               ‘epscairo’ and ‘pdfcairo’ are synonymous with the ‘epsc’
               device.  The LaTeX variants generate a LaTeX file,
               ‘FILENAME.tex’, for the text portions of a plot, and an
               image file, ‘FILENAME.(eps|pdf)’, for the graph portion
               of the plot.  The ‘standalone’ variants behave as
               described for ‘epslatexstandalone’ above.

          ‘canvas*’
               Javascript-based drawing on an HTML5 canvas viewable in a
               web browser.

          ‘emf’
          ‘meta’
               Microsoft Enhanced Metafile

          ‘fig’
               XFig.  For the Gnuplot graphics toolkit, the additional
               options ‘-textspecial’ or ‘-textnormal’ (default) can be
               used to control whether the special flag should be set
               for the text in the figure.

          ‘latex*’
          ‘eepic*’
               LaTeX picture environment and extended picture
               environment.

          ‘tikz’
          ‘tikzstandalone*’
               Generate a LaTeX file using PGF/TikZ format.  The
               OpenGL-based toolkits create a PGF file while Gnuplot
               creates a TikZ file.  The ‘tikzstandalone’ device
               produces a LaTeX document which includes the TikZ file.

          Raster Formats

          ‘png’
               Portable Network Graphics

          ‘jpg’
          ‘jpeg’
               JPEG image

          ‘tif’
          ‘tiff’
          ‘tiffn’
               TIFF image with LZW compression (tif, tiff) or
               uncompressed (tiffn).

          ‘gif’
               GIF image

          ‘pbm’
               PBMplus

          ‘dumb*’
               ASCII art

          If the device is omitted, it is inferred from the file
          extension, or if there is no filename then it is sent to the
          printer as PostScript.

     ‘-dGHOSTSCRIPT_DEVICE’
          Additional devices are supported by Ghostscript.  Some
          examples are:

          ‘ljet2p’
               HP LaserJet IIP

          ‘pcx24b’
               24-bit color PCX file format

          ‘ppm’
               Portable Pixel Map file format

          For a complete list of available formats and devices type
          ‘system ("gs -h")’.

          When Ghostscript output is sent to a printer the size is
          determined by the figure’s "papersize" property.  When the
          output is sent to a file the size is determined by the plot
          box defined by the figure’s "paperposition" property.

     ‘-GGHOSTSCRIPT_COMMAND’
          Specify the command for calling Ghostscript.  For Unix the
          default is "gs" and for Windows it is "gswin32c".

     ‘-TextAlphaBits=N’
     ‘-GraphicsAlphaBits=N’
          Octave is able to produce output for various printers,
          bitmaps, and vector formats by using Ghostscript.  For bitmap
          and printer output anti-aliasing is applied using
          Ghostscript’s TextAlphaBits and GraphicsAlphaBits options.
          The default number of bits are 4 and 1 respectively.  Allowed
          values for N are 1, 2, or 4.

     See also: *note saveas: XREFsaveas, *note getframe: XREFgetframe,
     *note savefig: XREFsavefig, *note hgsave: XREFhgsave, *note orient:
     XREForient, *note figure: XREFfigure.

 -- : saveas (H, FILENAME)
 -- : saveas (H, FILENAME, FMT)
     Save graphics object H to the file FILENAME in graphics format FMT.

     If H is the handle to a figure object, that figure object is saved.
     If H is the handle to a different graphics object, the figure
     containing that graphics object is saved.

     All device formats accepted by ‘print’ may be used.  Common formats
     are:

     ‘ofig’
          Octave figure file format (default)

     ‘mfig’
          Two files: Octave m-file ‘filename.m’ containing code to open
          Octave figure file ‘filename.ofig’

     ‘ps’
          PostScript

     ‘eps’
          Encapsulated PostScript

     ‘pdf’
          Portable Document Format

     ‘jpg’
          JPEG Image

     ‘png’
          Portable Network Graphics image

     ‘emf’
          Enhanced MetaFile

     ‘tif’
          TIFF Image, compressed

     If FMT is omitted it is extracted from the extension of FILENAME.
     The default format when there is no extension is "ofig".

          clf ();
          surf (peaks);
          saveas (1, "figure1.png");

     See also: *note print: XREFprint, *note savefig: XREFsavefig, *note
     hgsave: XREFhgsave, *note orient: XREForient.

 -- : orient (ORIENTATION)
 -- : orient (HFIG, ORIENTATION)
 -- : ORIENTATION = orient ()
 -- : ORIENTATION = orient (HFIG)
     Query or set the print orientation for figure HFIG.

     Valid values for ORIENTATION are "portrait", "landscape", and
     "tall".

     The "landscape" option changes the orientation so the plot width is
     larger than the plot height.  The "paperposition" is also modified
     so that the plot fills the page, while leaving a 0.25 inch border.

     The "tall" option sets the orientation to "portrait" and fills the
     page with the plot, while leaving a 0.25 inch border.

     The "portrait" option (default) changes the orientation so the plot
     height is larger than the plot width.  It also restores the default
     "paperposition" property.

     When called with no arguments, return the current print
     orientation.

     If the argument HFIG is omitted, then operate on the current figure
     returned by ‘gcf’.

     See also: *note print: XREFprint, *note saveas: XREFsaveas.

   ‘print’ and ‘saveas’ are used when work on a plot has finished and
the output must be in a publication-ready format.  During intermediate
stages it is often better to save the graphics object and all of its
associated information so that changes—to colors, axis limits, marker
styles, etc.—can be made easily from within Octave.  The
‘hgsave’/‘hgload’ commands can be used to save and re-create a graphics
object.

 -- : hgsave (FILENAME)
 -- : hgsave (H, FILENAME)
 -- : hgsave (H, FILENAME, FMT)
     Save the graphics handle(s) H to the file FILENAME in the format
     FMT.

     If unspecified, H is the current figure as returned by ‘gcf’.

     When FILENAME does not have an extension the default filename
     extension ‘.ofig’ will be appended.

     If present, FMT must be one of the following:

        • ‘-binary’, ‘-float-binary’

        • ‘-hdf5’, ‘-float-hdf5’

        • ‘-V7’, ‘-v7’, ‘-7’, ‘-mat7-binary’

        • ‘-V6’, ‘-v6’, ‘-6’, ‘-mat6-binary’

        • ‘-text’

        • ‘-zip’, ‘-z’

     The default format is ‘-binary’ to minimize storage.

     Programming Note: When producing graphics for final publication use
     ‘print’ or ‘saveas’.  When it is important to be able to continue
     to edit a figure as an Octave object, use ‘hgsave’/‘hgload’.

     See also: *note hgload: XREFhgload, *note hdl2struct:
     XREFhdl2struct, *note savefig: XREFsavefig, *note saveas:
     XREFsaveas, *note print: XREFprint.

 -- : H = hgload (FILENAME)
 -- : [H, OLD_PROP] = hgload (FILENAME, PROP_STRUCT)
     Load the graphics objects in FILENAME into a vector of graphics
     handles H.

     If FILENAME has no extension, Octave will try to find the file with
     and without the default extension ‘.ofig’.

     If provided, the elements of structure PROP_STRUCT will be used to
     override the properties of top-level objects stored in FILENAME,
     and the saved values from FILENAME will be stored in OLD_PROP.
     OLD_PROP is a cell array matching the size of H; each cell contains
     a structure of the existing property names and values before being
     overridden.

     See also: *note openfig: XREFopenfig, *note hgsave: XREFhgsave,
     *note struct2hdl: XREFstruct2hdl.

 -- : openfig
 -- : openfig (FILENAME)
 -- : openfig (..., COPIES)
 -- : openfig (..., VISIBILITY)
 -- : H = openfig (...)
     Read saved figure window(s) from FILENAME and return graphics
     handle(s) H.

     By default, FILENAME is "Untitled.fig".  If a full path is not
     specified, the file opened will be the first one encountered in the
     load path.  If FILENAME is not found and does not have an
     extension, a search will take place for the first file in the load
     path with extension ".fig" or ".ofig", in that order.

     COPIES is an optional input indicating whether a new figure should
     be created ("new") or whether an existing figure may be reused
     ("reuse").  An existing figure may be reused if the "FileName"
     property matches the specified input FILENAME.  When a figure is
     reused it becomes the active figure and is shown on top of other
     figures.  If the figure was offscreen, it is re-positioned to be
     onscreen.  The default value for COPIES is "new".

     VISIBILITY is an optional input indicating whether to show the
     figure ("visible") or not ("invisible").  When VISIBILITY is
     specified as an input to ‘openfig’ it overrides the visibility
     setting stored in FILENAME.

     See also: *note open: XREFopen, *note hgload: XREFhgload, *note
     savefig: XREFsavefig, *note struct2hdl: XREFstruct2hdl.

 -- : savefig ()
 -- : savefig (H)
 -- : savefig (FILENAME)
 -- : savefig (H, FILENAME)
 -- : savefig (H, FILENAME, "compact")
     Save figure windows specified by graphics handle(s) H to file
     FILENAME.

     If unspecified, H is the current figure returned by ‘gcf’.

     If unspecified, FILENAME is set to ‘"Untitled.fig"’.  If FILENAME
     does not have an extension then the default extension ‘".fig"’ will
     be added.

     If the optional third input "compact" is present then the data will
     be compressed to save more space.

     See also: *note hgsave: XREFhgsave, *note hdl2struct:
     XREFhdl2struct, *note openfig: XREFopenfig.


File: octave.info,  Node: Interacting with Plots,  Next: Test Plotting Functions,  Prev: Printing and Saving Plots,  Up: High-Level Plotting

15.2.10 Interacting with Plots
------------------------------

The user can select points on a plot with the ‘ginput’ function or
select the position at which to place text on the plot with the ‘gtext’
function using the mouse.

 -- : [X, Y, BUTTONS] = ginput (N)
 -- : [X, Y, BUTTONS] = ginput ()
     Return the position and type of mouse button clicks and/or key
     strokes in the current figure window.

     If N is defined, then capture N events before returning.  When N is
     not defined ‘ginput’ will loop until the return key <RET> is
     pressed.

     The return values X, Y are the coordinates where the mouse was
     clicked in the units of the current axes.  The return value BUTTON
     is 1, 2, or 3 for the left, middle, or right button.  If a key is
     pressed the ASCII value is returned in BUTTON.

     Implementation Note: ‘ginput’ is intenteded for 2-D plots.  For 3-D
     plots see the CURRENTPOINT property of the current axes which can
     be transformed with knowledge of the current ‘view’ into data
     units.

     See also: *note gtext: XREFgtext, *note waitforbuttonpress:
     XREFwaitforbuttonpress.

 -- : waitforbuttonpress ()
 -- : B = waitforbuttonpress ()
     Wait for mouse click or key press over the current figure window.

     The return value of B is 0 if a mouse button was pressed or 1 if a
     key was pressed.

     See also: *note waitfor: XREFwaitfor, *note ginput: XREFginput,
     *note kbhit: XREFkbhit.

 -- : gtext (S)
 -- : gtext ({S1, S2, ...})
 -- : gtext ({S1; S2; ...})
 -- : gtext (..., PROP, VAL, ...)
 -- : H = gtext (...)
     Place text on the current figure using the mouse.

     The string argument S may be a character array or a cell array of
     strings.  If S has more than one row, each row is used to create a
     separate text object after a mouse click.  For example:

     Place a single string after one mouse click

          gtext ("I clicked here")

     Place two strings after two mouse clicks

          gtext ({"I clicked here"; "and there"})

     Place two strings, each with two lines, after two mouse clicks

          gtext ({"I clicked", "here"; "and", "there"})

     Optional PROPERTY/VALUE pairs are passed directly to the underlying
     text objects.

     The full list of text object properties is documented at *note Text
     Properties::.

     The optional return value H holds the graphics handle(s) to the
     created text object(s).

     See also: *note ginput: XREFginput, *note text: XREFtext.

   More sophisticated user interaction mechanisms can be obtained using
the ui* family of functions, *note UI Elements::.


File: octave.info,  Node: Test Plotting Functions,  Prev: Interacting with Plots,  Up: High-Level Plotting

15.2.11 Test Plotting Functions
-------------------------------

The functions ‘sombrero’ and ‘peaks’ provide a way to check that
plotting is working.  Typing either ‘sombrero’ or ‘peaks’ at the Octave
prompt should display a three-dimensional plot.

 -- : sombrero ()
 -- : sombrero (N)
 -- : Z = sombrero (...)
 -- : [X, Y, Z] = sombrero (...)
     Plot the familiar 3-D sombrero function.

     The function plotted is

          z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))

     Called without a return argument, ‘sombrero’ plots the surface of
     the above function over the meshgrid [-8,8] using ‘surf’.

     If N is a scalar the plot is made with N grid lines.  The default
     value for N is 41.

     When called with output arguments, return the data for the function
     evaluated over the meshgrid.  This can subsequently be plotted with
     ‘surf (X, Y, Z)’.

     See also: *note peaks: XREFpeaks, *note meshgrid: XREFmeshgrid,
     *note mesh: XREFmesh, *note surf: XREFsurf.

 -- : peaks ()
 -- : peaks (N)
 -- : peaks (X, Y)
 -- : Z = peaks (...)
 -- : [X, Y, Z] = peaks (...)
     Plot a function with lots of local maxima and minima.

     The function has the form

     f(x,y) = 3*(1-x)^2*exp(-x^2 - (y+1)^2) ...
              - 10*(x/5 - x^3 - y^5)*exp(-x^2-y^2) ...
              - 1/3*exp(-(x+1)^2 - y^2)

     Called without a return argument, ‘peaks’ plots the surface of the
     above function using ‘surf’.

     If N is a scalar, ‘peaks’ plots the value of the above function on
     an N-by-N mesh over the range [-3,3].  The default value for N is
     49.

     If N is a vector, then it represents the grid values over which to
     calculate the function.  If X and Y are specified then the function
     value is calculated over the specified grid of vertices.

     When called with output arguments, return the data for the function
     evaluated over the meshgrid.  This can subsequently be plotted with
     ‘surf (X, Y, Z)’.

     See also: *note sombrero: XREFsombrero, *note meshgrid:
     XREFmeshgrid, *note mesh: XREFmesh, *note surf: XREFsurf.


File: octave.info,  Node: Graphics Data Structures,  Next: Advanced Plotting,  Prev: High-Level Plotting,  Up: Plotting

15.3 Graphics Data Structures
=============================

* Menu:

* Introduction to Graphics Structures::
* Graphics Objects::
* Graphics Object Properties::
* Searching Properties::
* Managing Default Properties::


File: octave.info,  Node: Introduction to Graphics Structures,  Next: Graphics Objects,  Up: Graphics Data Structures

15.3.1 Introduction to Graphics Structures
------------------------------------------

The graphics functions use pointers, which are of class graphics_handle,
in order to address the data structures which control visual display.  A
graphics handle may point to any one of a number of different base
object types.  These objects are the graphics data structures
themselves.  The primitive graphic object types are: ‘figure’, ‘axes’,
‘line’, ‘text’, ‘patch’, ‘scatter’, ‘surface’, ‘text’, ‘image’, and
‘light’.

   Each of these objects has a function by the same name, and each of
these functions returns a graphics handle pointing to an object of the
corresponding type.

   In addition, there are several functions which operate on properties
of the graphics objects and which also return handles.  This includes
but is not limited to the following functions: The functions ‘plot’ and
‘plot3’ return a handle pointing to an object of type ‘line’.  The
function ‘subplot’ returns a handle pointing to an object of type
‘axes’.  The functions ‘fill’, ‘fill3’, ‘trimesh’, and ‘trisurf’ return
a handle pointing to an object of type patch.  The function ‘scatter3’
returns a handle to an object of type scatter.  The functions ‘slice’,
‘surf’, ‘surfl’, ‘mesh’, ‘meshz’, ‘pcolor’, and ‘waterfall’ each return
a handle of type surface.  The function ‘camlight’ returns a handle to
an object of type light.  The functions ‘area’, ‘bar’, ‘barh’,
‘contour’, ‘contourf’, ‘contour3’, ‘surfc’, ‘meshc’, ‘errorbar’,
‘quiver’, ‘quiver3’, ‘stair’, ‘stem’, ‘stem3’ each return a handle to a
complex data structure as documented in *note Data Sources:
XREFdatasources.

   The graphics objects are arranged in a hierarchy:

   1.  The root object is returned by ‘groot’ (historically, equivalent
to the handle 0).  In other words, ‘get (groot)’ returns the properties
of the root object.

   2.  Below the root are ‘figure’ objects.

   3.  Below the ‘figure’ objects are ‘axes’ or ‘hggroup’ objects.

   4.  Below the ‘axes’ or ‘hggroup’ objects are ‘line’, ‘text’,
‘patch’, ‘scatter’, ‘surface’, ‘image’, and ‘light’ objects.

   It is possible to walk this hierarchical tree by querying the
"parent" and "children" properties of the graphics objects.

   Graphics handles may be distinguished from function handles (*note
Function Handles::) by means of the function ‘ishghandle’.  ‘ishghandle’
returns true if its argument is a handle of a graphics object.  In
addition, a figure or axes object may be tested using ‘isfigure’ or
‘isaxes’ respectively.  To test for a specific type of graphics handle,
such as a patch or line object, use ‘isgraphics’.  The more specific
test functions return true only if the argument is both a graphics
handle and of the correct type (figure, axes, specified object type).

   The ‘get’ and ‘set’ commands are used to obtain and set the values of
properties of graphics objects.  In addition, the ‘get’ command may be
used to obtain property names.

   For example, the property "type" of the graphics object pointed to by
the graphics handle h may be displayed by:

     get (h, "type")

   The properties and their current values may be obtained in the form
of a structure using ‘s = get (h)’, where ‘h’ is the handle of a
graphics object.  If only the names of the properties and the allowed
values (for radio properties only) are wanted, one may use ‘set (h)’.

   Thus, for example:

     h = figure ();
     get (h, "type")
     ⇒ ans = figure
     set (h)
     ⇒
             alphamap:
             beingdeleted:  [ {off} | on ]
             busyaction:  [ cancel | {queue} ]
             buttondownfcn:
             clipping:  [ off | {on} ]
             closerequestfcn:
             color:
             colormap:
             createfcn:
             currentaxes:
             deletefcn:
             dockcontrols:  [ {off} | on ]
             filename:
             graphicssmoothing:  [ off | {on} ]
             handlevisibility:  [ callback | off | {on} ]
             ...

   The uses of ‘get’ and ‘set’ are further explained in *note get:
XREFget, *note set: XREFset.

 -- : RES = isprop (OBJ, "PROP")
     Return true if PROP is a property of the object OBJ.

     OBJ may also be an array of objects in which case RES will be a
     logical array indicating whether each handle has the property PROP.

     For plotting, OBJ is a handle to a graphics object.  Otherwise, OBJ
     should be an instance of a class.  ‘isprop’ reports whether the
     class defines a property, but ‘Access’ permissions or visibility
     restrictions (‘Hidden = true’) may prevent use by the programmer.

     See also: *note get: XREFget, *note set: XREFset, *note properties:
     XREFproperties, *note ismethod: XREFismethod, *note isobject:
     XREFisobject.


File: octave.info,  Node: Graphics Objects,  Next: Graphics Object Properties,  Prev: Introduction to Graphics Structures,  Up: Graphics Data Structures

15.3.2 Graphics Objects
-----------------------

The hierarchy of graphics objects was explained above.  *Note
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”.

root
     The top level of the hierarchy and the parent of all figure
     objects.  Use ‘groot’ to obtain the handle of the root graphics
     object.

figure
     A figure window.

axes
     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.

line
     A line in two or three dimensions.

text
     Text annotations.

image
     A bitmap image.

patch
     A filled polygon, currently limited to two dimensions.

surface
     A three-dimensional surface.

light
     A light object used for lighting effects on patches and surfaces.

15.3.2.1 Creating Graphics Objects
..................................

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’ or ‘fill3’ instead of ‘patch’.

 -- : axes ()
 -- : axes (PROPERTY, VALUE, ...)
 -- : axes (HPAR, PROPERTY, VALUE, ...)
 -- : axes (HAX)
 -- : H = axes (...)
     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
     *note Axes Properties::.

     See also: *note gca: XREFgca, *note set: XREFset, *note get:
     XREFget.

 -- : line ()
 -- : line (X, Y)
 -- : line (X, Y, Z)
 -- : line ("xdata", X, "ydata", Y)
 -- : line ("xdata", X, "ydata", Y, "zdata", Z)
 -- : line (..., PROPERTY, VALUE)
 -- : line (HAX, ...)
 -- : H = line (...)
     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
     *note Line Properties::.

     The function ‘line’ differs from ‘plot’ in that line objects are
     inserted in to the current axes without first clearing the plot.

     See also: *note image: XREFimage, *note patch: XREFpatch, *note
     rectangle: XREFrectangle, *note surface: XREFsurface, *note text:
     XREFtext.

 -- : patch ()
 -- : patch (X, Y, C)
 -- : patch (X, Y, Z, C)
 -- : patch ("Faces", FACES, "Vertices", VERTS, ...)
 -- : patch (..., PROP, VAL, ...)
 -- : patch (..., PROPSTRUCT, ...)
 -- : patch (HAX, ...)
 -- : H = patch (...)
     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
     *note Patch Properties::.  Useful patch properties include:
     "cdata", "edgecolor", "facecolor", "faces", and "facevertexcdata".

     See also: *note fill: XREFfill, *note get: XREFget, *note set:
     XREFset.

 -- : surface (X, Y, Z, C)
 -- : surface (X, Y, Z)
 -- : surface (Z, C)
 -- : surface (Z)
 -- : surface (..., PROP, VAL, ...)
 -- : surface (HAX, ...)
 -- : H = surface (...)
     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
     *note Surface Properties::.

     See also: *note surf: XREFsurf, *note mesh: XREFmesh, *note patch:
     XREFpatch, *note line: XREFline.

 -- : light ()
 -- : light (..., "PROP", VAL, ...)
 -- : light (HAX, ...)
 -- : H = light (...)
     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 an
          RGB-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 a
          1x3-vector.  The default direction is ‘[1 0 1]’.

     "Style": This string defines whether the light emanates from a
          light 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
     *note Light Properties::.

     See also: *note lighting: XREFlighting, *note material:
     XREFmaterial, *note patch: XREFpatch, *note surface: XREFsurface.

15.3.2.2 Handle Functions
.........................

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’.

 -- : ishghandle (H)
     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: *note isgraphics: XREFisgraphics, *note isaxes:
     XREFisaxes, *note isfigure: XREFisfigure, *note ishandle:
     XREFishandle.

 -- : isgraphics (H)
 -- : isgraphics (H, TYPE)
     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: *note ishghandle: XREFishghandle, *note ishandle:
     XREFishandle, *note isaxes: XREFisaxes, *note isfigure:
     XREFisfigure.

 -- : ishandle (H)
     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: *note ishghandle: XREFishghandle, *note isgraphics:
     XREFisgraphics, *note isjava: XREFisjava.

 -- : isaxes (H)
     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: *note isfigure: XREFisfigure, *note ishghandle:
     XREFishghandle, *note isgraphics: XREFisgraphics.

 -- : isfigure (H)
     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: *note isaxes: XREFisaxes, *note ishghandle:
     XREFishghandle, *note isgraphics: XREFisgraphics.

   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.

 -- : H = groot ()
     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.

     See also: *note gcf: XREFgcf, *note gca: XREFgca, *note get:
     XREFget, *note set: XREFset.

 -- : H = gcf ()
     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");

     See also: *note gca: XREFgca, *note gco: XREFgco, *note gcbf:
     XREFgcbf, *note gcbo: XREFgcbo, *note get: XREFget, *note set:
     XREFset.

 -- : H = gca ()
     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");

     See also: *note gcf: XREFgcf, *note gco: XREFgco, *note gcbf:
     XREFgcbf, *note gcbo: XREFgcbo, *note get: XREFget, *note set:
     XREFset.

 -- : H = gco ()
 -- : H = gco (FIG)
     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.

     See also: *note gcbo: XREFgcbo, *note gca: XREFgca, *note gcf:
     XREFgcf, *note gcbf: XREFgcbf, *note get: XREFget, *note set:
     XREFset.

   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.

 -- : VAL = get (H)
 -- : VAL = get (H, P)
     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: *note set: XREFset.

 -- : set (H, PROPERTY, VALUE, ...)
 -- : set (H, PROPERTIES, VALUES)
 -- : set (H, PV)
 -- : VALUE_LIST = set (H, PROPERTY)
 -- : ALL_VALUE_LIST = set (H)
     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:

        • as a comma separated list of PROPERTY, VALUE pairs

          Here, each PROPERTY is a string containing the property name,
          each VALUE is a value of the appropriate type for the
          property.

        • as a cell array of strings PROPERTIES containing property
          names and a cell array VALUES containing property values.

          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.

        • as a structure array PV

          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: *note get: XREFget.

 -- : PARENT = ancestor (H, TYPE)
 -- : PARENT = ancestor (H, TYPE, "toplevel")
     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.

     See also: *note findobj: XREFfindobj, *note findall: XREFfindall,
     *note allchild: XREFallchild.

 -- : H = allchild (HANDLES)
     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.

     See also: *note findall: XREFfindall, *note findobj: XREFfindobj,
     *note get: XREFget, *note set: XREFset.

 -- : findfigs ()
     Find all visible figures that are currently off the screen and move
     them onto the screen.

     See also: *note allchild: XREFallchild, *note figure: XREFfigure,
     *note get: XREFget, *note set: XREFset.

   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);

 -- : S = hdl2struct (H)
     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: *note struct2hdl: XREFstruct2hdl, *note hgsave:
     XREFhgsave, *note findobj: XREFfindobj.

 -- : H = struct2hdl (S)
 -- : H = struct2hdl (S, P)
 -- : H = struct2hdl (S, P, HILEV)
     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: *note hdl2struct: XREFhdl2struct, *note hgload:
     XREFhgload, *note findobj: XREFfindobj.

 -- : HNEW = copyobj (HORIG)
 -- : HNEW = copyobj (HORIG, HPARENT)
     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: *note struct2hdl: XREFstruct2hdl, *note hdl2struct:
     XREFhdl2struct, *note findobj: XREFfindobj.


File: octave.info,  Node: Graphics Object Properties,  Next: Searching Properties,  Prev: Graphics Objects,  Up: Graphics Data Structures

15.3.3 Graphics Object Properties
---------------------------------

* Menu:

* Root Properties::
* Figure Properties::
* Axes Properties::
* Legend Properties::
* Line Properties::
* Text Properties::
* Image Properties::
* Patch Properties::
* Scatter Properties::
* Surface Properties::
* Light Properties::
* Uimenu Properties::
* Uibuttongroup Properties::
* Uicontextmenu Properties::
* Uipanel Properties::
* Uicontrol Properties::
* Uitable Properties::
* Uitoolbar Properties::
* Uipushtool Properties::
* Uitoggletool Properties::

In this section the graphics object properties are discussed in detail,
starting with the root properties and continuing through the object
hierarchy.  The documentation about a specific graphics object can be
displayed using ‘doc’ function, e.g., ‘doc ("axes properties")’ will
show *note Axes Properties::.

   The allowed values for radio (string) properties can be retrieved
programmatically or displayed using the one or two argument calling form
of the ‘set’ function.  *Note set: XREFset.

   In the following documentation default values are enclosed in { }.


File: octave.info,  Node: Root Properties,  Next: Figure Properties,  Up: Graphics Object Properties

15.3.3.1 Root Properties
........................

Properties of the root graphics object:

‘beingdeleted’: {"off"} | "on"
     ‘beingdeleted’ is unused.

‘busyaction’: "cancel" | {"queue"}
     ‘busyaction’ is unused.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘callbackobject’ (read-only): graphics handle, def. ‘[](0x0)’
     Graphics handle of the current object whose callback is executing.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the root’s children.

‘clipping’: "off" | {"on"}
     ‘clipping’ is unused.

‘commandwindowsize’ (read-only): def. ‘[0 0]’

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this root object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     ‘createfcn’ is unused.

‘currentfigure’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the current figure.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     ‘deletefcn’ is unused.

‘fixedwidthfontname’: string, def. "Courier"

‘handlevisibility’: "callback" | "off" | {"on"}
     ‘handlevisibility’ is unused.

‘hittest’: "off" | {"on"}
     ‘hittest’ is unused.

‘interruptible’: "off" | {"on"}
     ‘interruptible’ is unused.

‘monitorpositions’ (read-only):
     ‘monitorpositions’ is unused.

‘parent’: graphics handle, def. ‘[](0x0)’
     Root object has no parent graphics object.  ‘parent’ is always
     empty.

‘pickableparts’: "all" | "none" | {"visible"}
     ‘pickableparts’ is unused.

‘pointerlocation’: two-element vector, def. ‘[0 0]’
     ‘pointerlocation’ is unused.

‘pointerwindow’ (read-only): graphics handle, def. ‘0’
     ‘pointerwindow’ is unused.

‘screendepth’ (read-only): double

‘screenpixelsperinch’ (read-only): double

‘screensize’ (read-only): four-element vector

‘selected’: {"off"} | "on"
     ‘selected’ is unused.

‘selectionhighlight’: "off" | {"on"}
     ‘selectionhighlight’ is unused.

‘showhiddenhandles’: {"off"} | "on"
     If ‘showhiddenhandles’ is "on", all graphics objects handles are
     visible in their parents’ children list, regardless of the value of
     their ‘handlevisibility’ property.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "root"

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     ‘visible’ is unused.


File: octave.info,  Node: Figure Properties,  Next: Axes Properties,  Prev: Root Properties,  Up: Graphics Object Properties

15.3.3.2 Figure Properties
..........................

Properties of ‘figure’ objects (*note figure: XREFfigure.):

‘alphamap’: def. 64-by-1 double
     Transparency is not yet implemented for figure objects.  ‘alphamap’
     is unused.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the figure’s children.

‘clipping’: "off" | {"on"}
     ‘clipping’ is unused.

‘closerequestfcn’: string | function handle, def. "closereq"
     Function that is executed when a figure is deleted.  *Note closereq
     function: XREFclosereq.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the figure background.  *Note colorspec: Colors.

‘colormap’: N-by-3 matrix, def. 64-by-3 double
     A matrix containing the RGB color map for the current axes.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this figure object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after figure has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultfigurecreatefcn", 'disp ("figure
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘currentaxes’: graphics handle, def. ‘[](0x0)’
     Handle to the graphics object of the current axes.

‘currentcharacter’ (read-only): def. ""
     ‘currentcharacter’ is unused.

‘currentobject’ (read-only): graphics handle, def. ‘[](0x0)’

‘currentpoint’ (read-only): two-element vector, def. ‘[0; 0]’
     A 1-by-2 matrix which holds the coordinates of the point over which
     the mouse pointer was when a mouse event occurred.  The X and Y
     coordinates are in units defined by the figure’s ‘units’ property
     and their origin is the lower left corner of the plotting area.

     Events which set ‘currentpoint’ are
     A mouse button was pressed
          always
     A mouse button was released
          only if the figure’s callback ‘windowbuttonupfcn’ is defined
     The pointer was moved while pressing the mouse button (drag)
          only if the figure’s callback ‘windowbuttonmotionfcn’ is
          defined

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before figure is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘dockcontrols’: {"off"} | "on"
     ‘dockcontrols’ is unused.

‘filename’: string, def. ""
     The filename used when saving the plot figure.

‘graphicssmoothing’: "off" | {"on"}
     Use smoothing techniques to reduce the appearance of jagged lines.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the figure’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether figure processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFfigurepickableparts.

‘integerhandle’: "off" | {"on"}
     Assign the next lowest unused integer as the Figure number.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘inverthardcopy’: "off" | {"on"}
     Replace the figure and axes background color with white when
     printing.

‘keypressfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed when a keystroke event happens while the
     figure has focus.  The actual key that was pressed can be retrieved
     using the second argument ’evt’ of the function.  For information
     on how to write graphics listener functions see *note
     Callbacks section: Callbacks.

‘keyreleasefcn’: string | function handle, def. ‘[](0x0)’
     With ‘keypressfcn’, the keyboard callback functions.  These
     callback functions are called when a key is pressed/released
     respectively.  The functions are called with two input arguments.
     The first argument holds the handle of the calling figure.  The
     second argument holds an event structure which has the following
     members:
     ‘Character:’
          The ASCII value of the key
     ‘Key:’
          Lowercase value of the key
     ‘Modifier:’
          A cell array containing strings representing the modifiers
          pressed with the key.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘menubar’: {"figure"} | "none"
     Control the display of the figure menu bar at the top of the
     figure.

‘name’: string, def. ""
     Name to be displayed in the figure title bar.  The name is
     displayed to the right of any title determined by the ‘numbertitle’
     property.

‘nextplot’: {"add"} | "new" | "replace" | "replacechildren"
     ‘nextplot’ is used by high level plotting functions to decide what
     to do with axes already present in the figure.  *Note
     newplot function: XREFnewplot.

‘number’ (read-only):

‘numbertitle’: "off" | {"on"}
     Display "Figure" followed by the numerical figure handle value in
     the figure title bar.

‘outerposition’: four-element vector, def. ‘[-1 -1 -1 -1]’
     Specify the position and size of the figure including the top
     menubar and the bottom status bar.  The four elements of the vector
     are the coordinates of the lower left corner and width and height
     of the figure.  *Note units property: XREFfigureunits.

‘paperorientation’: "landscape" | {"portrait"}
     The value for the ‘papersize’, and ‘paperposition’ properties
     depends upon ‘paperorientation’.  The horizontal and vertical
     values for ‘papersize’ and ‘paperposition’ reverse order when
     ‘paperorientation’ is switched between ‘"portrait"’ and
     ‘"landscape"’.

‘paperposition’: four-element vector, def. ‘[1.3422 3.3191 5.8156 4.3617]’
     Vector ‘[left bottom width height]’ defining the position and size
     of the figure (in ‘paperunits’ units) on the printed page.  The
     position ‘[left bottom]’ defines the lower left corner of the
     figure on the page, and the size is defined by ‘[width height]’.
     For output formats not implicitly rendered on paper, ‘width’ and
     ‘height’ define the size of the image and the position information
     is ignored.  Setting ‘paperposition’ also forces the
     ‘paperpositionmode’ property to be set to "manual".

‘paperpositionmode’: {"auto"} | "manual"
     If ‘paperpositionmode’ is set to "auto", the ‘paperposition’
     property is automatically computed: the printed figure will have
     the same size as the on-screen figure and will be centered on the
     output page.  Setting the ‘paperpositionmode’ to ‘"auto"’ does not
     modify the value of the ‘paperposition’ property.

‘papersize’: two-element vector, def. ‘[8.5000 11.0000]’
     Vector ‘[width height]’ defining the size of the paper for
     printing.  Setting the ‘papersize’ property to a value, not
     associated with one of the defined ‘papertypes’ and consistent with
     the setting for ‘paperorientation’, forces the ‘papertype’ property
     to the value "<custom>".  If ‘papersize’ is set to a value
     associated with a supported ‘papertype’ and consistent with the
     ‘paperorientation’, the ‘papertype’ value is modified to the
     associated value.

‘papertype’: "<custom>" | "a" | "a0" | "a1" | "a2" | "a3" | "a4" | "a5" | "arch-a" | "arch-b" | "arch-c" | "arch-d" | "arch-e" | "b" | "b0" | "b1" | "b2" | "b3" | "b4" | "b5" | "c" | "d" | "e" | "tabloid" | "uslegal" | {"usletter"}
     Name of the paper used for printed output.  Setting ‘papertype’
     also changes ‘papersize’, while maintaining consistency with the
     ‘paperorientation’ property.

‘paperunits’: "centimeters" | {"inches"} | "normalized" | "points"
     The unit used to compute the ‘paperposition’ property.  The
     conversion from physical units (e.g., ‘"inches"’) is dependent on
     the ‘screenpixelsperinch’ property of the root object.

‘parent’: graphics handle, def. ‘0’
     Handle of the parent graphics object.

‘pickableparts’ (read-only): "all" | "none" | {"visible"}
     ‘pickableparts’ is unused.

‘pointer’: {"arrow"} | "botl" | "botr" | "bottom" | "circle" | "cross" | "crosshair" | "custom" | "fleur" | "hand" | "ibeam" | "left" | "right" | "top" | "topl" | "topr" | "watch"
     Name of the mouse pointer shape associated with the canvas of the
     figure.  When ‘pointer’ is "custom", the shape is determined by the
     ‘pointershapecdata’ property.

     ‘pointer’ has no effect when the figure is in zoom, pan, or rotate
     mode.  In this case, Octave automatically uses a pointer shape
     appropriate to the mode.

‘pointershapecdata’: 16-by-16 or 32-by-32 Matrix, def. 16-by-16 double
     m-by-m matrix defining a custom pointer.  Each element defines a
     pixel with the element (1,1) representing the top-left pixel.  A
     value of 1 is colored black, a value of 2 is colored white, and all
     other values are rendered as transparent.

‘pointershapehotspot’: two-element vector, def. ‘[1 1]’
     For custom pointers only ‘pointershapehotspot’ defines the row and
     column of the pixel in ‘pointershapecdata’ that is used as the
     pointer location.

‘position’: four-element vector, def. ‘[300 200 560 420]’
     Specify the position and size of the figure canvas.  The four
     elements of the vector are the coordinates of the lower left corner
     and width and height of the figure.  *Note units property:
     XREFfigureunits.

‘renderer’: {"opengl"} | "painters"
     Rendering engine used for printing when ‘renderermode’ is "manual".
     Setting ‘renderer’ also forces the ‘renderermode’ property to be
     set to "manual".

‘renderermode’: {"auto"} | "manual"
     Control whether the rendering engine used for printing is chosen
     automatically or specified by the ‘renderer’ property.  *Note
     print function: XREFprint.

‘resize’: "off" | {"on"}
     Control whether the figure can be resized by dragging the window
     borders and corners using a mouse.  When ‘resize’ is "off" mouse
     interactions are disabled but the figure can still be resized by
     changing its "position" property.

‘resizefcn’: string | function handle, def. ‘[](0x0)’
     ‘resizefcn’ is deprecated.  Use ‘sizechangedfcn’ instead.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘selectiontype’: "alt" | "extend" | {"normal"} | "open"
     Selection type of the latest mouse click.

     ‘selectiontype’ may take different values depending on the
     combination of mouse button and keyboard modifier that were used:
     ‘normal:’
          Left-click.
     ‘alt:’
          Right-click or Ctrl+Left-click.
     ‘extend:’
          Shitf+Left-click, Middle click, or combined Left-click and
          Right-click.
     ‘open:’
          Double Left-click.

‘sizechangedfcn’: string | function handle, def. ‘[](0x0)’
     Callback triggered when the figure window size is changed.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘toolbar’: {"auto"} | "figure" | "none"
     Control the display of the toolbar (along the bottom of the
     menubar) and the status bar.  When set to "auto", the display is
     based on the value of the ‘menubar’ property.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "figure"

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"
     The unit used to compute the ‘position’ and ‘outerposition’
     properties.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the figure is not rendered on screen.

‘windowbuttondownfcn’: string | function handle, def. ‘[](0x0)’
     *Note windowbuttonupfcn property: XREFfigurewindowbuttonupfcn.

‘windowbuttonmotionfcn’: string | function handle, def. ‘[](0x0)’
     *Note windowbuttonupfcn property: XREFfigurewindowbuttonupfcn.

‘windowbuttonupfcn’: string | function handle, def. ‘[](0x0)’
     With ‘windowbuttondownfcn’ and ‘windowbuttonmotionfcn’, the mouse
     callback functions.  These callback functions are called when a
     mouse button is pressed, dragged, or released respectively.  When
     these callback functions are executed, the ‘currentpoint’ property
     holds the current coordinates of the cursor.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘windowkeypressfcn’: string | function handle, def. ‘[](0x0)’
     Function that is executed when a key is pressed and the figure has
     focus.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘windowkeyreleasefcn’: string | function handle, def. ‘[](0x0)’
     Function that is executed when a key is released and the figure has
     focus.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘windowscrollwheelfcn’: string | function handle, def. ‘[](0x0)’
     Function that is executed when a user manipulates the mouse wheel
     over this figure.  The function is called with two input arguments.
     The first argument holds the handle of the calling figure.  The
     second argument holds an event structure which has the following
     members:
     ‘VerticalScrollCount:’
          The number of wheel steps, typically 1 when scrolling down and
          -1 when scrolling up.
     ‘VerticalScrollAmount:’
          The number of lines a wheel step should scroll.  This value is
          always 3.
     ‘EventName:’
          The event name which is "WindowScrollWheel".

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘windowstyle’: "docked" | "modal" | {"normal"}
     The window style of a figure.  One of the following values:
     ‘normal’
          Set the window style as non modal.
     ‘modal’
          Set the window as modal so that it will stay on top of all
          normal figures.
     ‘docked’
          Setting the window style as docked currently does not dock the
          window.

     Changing modes of a visible figure may cause the figure to close
     and reopen.


File: octave.info,  Node: Axes Properties,  Next: Legend Properties,  Prev: Figure Properties,  Up: Graphics Object Properties

15.3.3.3 Axes Properties
........................

Properties of ‘axes’ objects (*note axes: XREFaxes.):

‘alim’: def. ‘[0 1]’
     Transparency is not yet implemented for axes objects.  ‘alim’ is
     unused.

‘alimmode’: {"auto"} | "manual"

‘alphamap’: def. ‘[](0x0)’

‘alphascale’: {"linear"} | "log"

‘ambientlightcolor’: def. ‘[1 1 1]’
     ‘ambientlightcolor’ is unused.

‘beingdeleted’: {"off"} | "on"

‘box’: {"off"} | "on"
     Control whether the axes has a surrounding box.

‘boxstyle’: {"back"} | "full"
     For 3-D axes, control whether the "full" box is drawn or only the 3
     "back" axes

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘cameraposition’: three-element vector, def. ‘[0.5000 0.5000 9.1603]’

‘camerapositionmode’: {"auto"} | "manual"

‘cameratarget’: three-element vector, def. ‘[0.5000 0.5000 0.5000]’

‘cameratargetmode’: {"auto"} | "manual"

‘cameraupvector’: three-element vector, def. ‘[0 1 0]’

‘cameraupvectormode’: {"auto"} | "manual"

‘cameraviewangle’: scalar, def. ‘6.6086’

‘cameraviewanglemode’: {"auto"} | "manual"

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the axes’s children.

‘clim’: two-element vector, def. ‘[0 1]’
     Define the limits for the color axis of image children.  Setting
     ‘clim’ also forces the ‘climmode’ property to be set to "manual".
     *Note pcolor function: XREFpcolor.

‘climmode’: {"auto"} | "manual"

‘clipping’: "off" | {"on"}
     ‘clipping’ is unused.

‘clippingstyle’: {"3dbox"} | "rectangle"
     ‘clippingstyle’ is unused.

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the axes background.  *Note colorspec: Colors.

‘colormap’: def. 64-by-3 double

‘colororder’: N-by-3 RGB matrix, def. 7-by-3 double
     RGB values used by plot function for automatic line coloring.

‘colororderindex’: def. ‘1’
     ‘colororderindex’ is unused.

‘colorscale’: {"linear"} | "log"

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this axes object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after axes has been created.
     Function is set by using default property on root object, e.g.,
     ‘set (groot, "defaultaxescreatefcn", 'disp ("axes created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘currentpoint’: 2-by-3 matrix, def. 2-by-3 double
     Matrix ‘[xf, yf, zf; xb, yb, zb]’ which holds the coordinates (in
     axes data units) of the point over which the mouse pointer was when
     the mouse button was pressed.  If a mouse callback function is
     defined, ‘currentpoint’ holds the pointer coordinates at the time
     the mouse button was pressed.  For 3-D plots, the first row of the
     returned matrix specifies the point nearest to the current camera
     position and the second row the furthest point.  The two points
     forms a line which is perpendicular to the screen.

‘dataaspectratio’: three-element vector, def. ‘[1 1 1]’
     Specify the relative height and width of the data displayed in the
     axes.  Setting ‘dataaspectratio’ to ‘[1, 2]’ causes the length of
     one unit as displayed on the x-axis to be the same as the length of
     2 units on the y-axis.  *Note daspect function: XREFdaspect.
     Setting ‘dataaspectratio’ also forces the ‘dataaspectratiomode’
     property to be set to "manual".

‘dataaspectratiomode’: {"auto"} | "manual"

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before axes is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFaxesfontunits.

‘fontsizemode’: {"auto"} | "manual"

‘fontsmoothing’: "off" | {"on"}
     Control whether any text associated with axes is anti-aliased.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘gridalpha’: def. ‘0.1500’
     Transparency is not yet implemented for axes objects.  ‘gridalpha’
     is unused.

‘gridalphamode’: {"auto"} | "manual"
     ‘gridalphamode’ is unused.

‘gridcolor’: def. ‘[0.1500 0.1500 0.1500]’
     ‘gridcolor’ is unused.

‘gridcolormode’: {"auto"} | "manual"
     ‘gridcolormode’ is unused.

‘gridlinestyle’: {"-"} | "–" | "-." | ":" | "none"

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the axes’s handle is not visible in
     its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether axes processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFaxespickableparts.

‘innerposition’: four-element vector, def. ‘[0.1300 0.1100 0.7750 0.8150]’
     The "innerposition" property is the same as the *note
     "position" property: XREFaxesposition.

‘interactions’ (read-only): def. ‘[](0x0)’

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘labelfontsizemultiplier’: def. ‘1.1000’
     Ratio between the x/y/zlabel fontsize and the tick label fontsize

‘layer’: {"bottom"} | "top"
     Control whether the axes is drawn below child graphics objects
     (ticks, labels, etc. covered by plotted objects) or above.

‘layout’ (read-only): def. ‘[](0x0)’

‘legend’ (read-only): def. ‘[](0x0)’

‘linestyleorder’: def. "-"
     ‘linestyleorder’ is unused.

‘linestyleorderindex’: def. ‘1’
     ‘linestyleorderindex’ is unused.

‘linewidth’: def. ‘0.5000’
     Width of the main axes lines

‘minorgridalpha’: def. ‘0.2500’
     Transparency is not yet implemented for axes objects.
     ‘minorgridalpha’ is unused.

‘minorgridalphamode’: {"auto"} | "manual"
     ‘minorgridalphamode’ is unused.

‘minorgridcolor’: def. ‘[0.1000 0.1000 0.1000]’
     ‘minorgridcolor’ is unused.

‘minorgridcolormode’: {"auto"} | "manual"
     ‘minorgridcolormode’ is unused.

‘minorgridlinestyle’: "-" | "–" | "-." | {":"} | "none"

‘mousewheelzoom’: scalar in the range (0, 1), def. ‘0.5000’
     Fraction of axes limits to zoom for each wheel movement.

‘nextplot’: "add" | {"replace"} | "replacechildren"
     ‘nextplot’ is used by high level plotting functions to decide what
     to do with graphics objects already present in the axes.  *Note
     newplot function: XREFnewplot.  The state of ‘nextplot’ is
     typically controlled using the ‘hold’ function.  *Note
     hold function: XREFhold.

‘nextseriesindex’ (read-only): def. ‘1’

‘outerposition’: four-element vector, def. ‘[0 0 1 1]’
     Specify 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, ‘[0.2, 0.3, 0.4, 0.5]’ sets the lower left corner of the
     axes at (0.2, 0.3) and the width and height to be 0.4 and 0.5
     respectively.  *Note position property: XREFaxesposition.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether axes will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the axes or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFaxeshittest.

‘plotboxaspectratio’: def. ‘[1 1 1]’
     *Note pbaspect function: XREFpbaspect.  Setting
     ‘plotboxaspectratio’ also forces the ‘plotboxaspectratiomode’
     property to be set to "manual".

‘plotboxaspectratiomode’: {"auto"} | "manual"

‘position’: four-element vector, def. ‘[0.1300 0.1100 0.7750 0.8150]’
     Specify 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, ‘[0.2, 0.3, 0.4, 0.5]’ sets the lower left corner of the
     axes at (0.2, 0.3) and the width and height to be 0.4 and 0.5
     respectively.  *Note outerposition property: XREFaxesouterposition.

‘positionconstraint’: "innerposition" | {"outerposition"}
     Specify which of "innerposition" or "outerposition" properties
     takes precedence when axes annotations extent changes.  *Note
     "innerposition" property: XREFaxesinnerposition, and *note
     "outerposition" property: XREFaxesouterposition.

‘projection’: {"orthographic"} | "perspective"
     ‘projection’ is unused.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘sortmethod’: "childorder" | {"depth"}
     ‘sortmethod’ is unused.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tickdir’: {"in"} | "out"
     Control whether axes tick marks project "in" to the plot box or
     "out".  Setting ‘tickdir’ also forces the ‘tickdirmode’ property to
     be set to "manual".

‘tickdirmode’: {"auto"} | "manual"

‘ticklabelinterpreter’: "latex" | "none" | {"tex"}
     Control the way x/y/zticklabel properties are interpreted.  *Note
     Use of the interpreter property: XREFinterpreterusage.

‘ticklength’: two-element vector, def. ‘[0.010000 0.025000]’
     Two-element vector ‘[2Dlen 3Dlen]’ specifying the length of the
     tickmarks relative to the longest visible axis.

‘tightinset’ (read-only): four-element vector
     Size of the ‘[left bottom right top]’ margins around the axes that
     enclose labels and title annotations.

‘title’: graphics handle
     Graphics handle of the title text object.

‘titlefontsizemultiplier’: positive scalar, def. ‘1.1000’
     Ratio between the title fontsize and the tick label fontsize

‘titlefontweight’: {"bold"} | "normal"
     Control variant of base font used for the axes title.

‘toolbar’ (read-only): def. ‘[](0x0)’

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "axes"

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"
     Units used to interpret the "position", "outerposition", and
     "tightinset" properties.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘view’: two-element vector, def. ‘[0 90]’
     Two-element vector ‘[azimuth elevation]’ specifying the viewpoint
     for three-dimensional plots

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the axes is not rendered on screen.

‘xaxis’ (read-only): def. ‘[](0x0)’

‘xaxislocation’: {"bottom"} | "origin" | "top"
     Control the x axis location.

‘xcolor’: {colorspec} | "none", def. ‘[0.1500 0.1500 0.1500]’
     Color of the x-axis.  *Note colorspec: Colors.  Setting ‘xcolor’
     also forces the ‘xcolormode’ property to be set to "manual".

‘xcolormode’: {"auto"} | "manual"

‘xdir’: {"normal"} | "reverse"
     Direction of the x axis: "normal" is left to right.

‘xgrid’: {"off"} | "on"
     Control whether major x grid lines are displayed.

‘xlabel’: graphics handle
     Graphics handle of the x label text object.

‘xlim’: two-element vector, def. ‘[0 1]’
     Two-element vector ‘[xmin xmax]’ specifying the limits for the
     x-axis.  Setting ‘xlim’ also forces the ‘xlimmode’ property to be
     set to "manual".  *Note xlim function: XREFxlim.

‘xlimmode’: {"auto"} | "manual"

‘xminorgrid’: {"off"} | "on"
     Control whether minor x grid lines are displayed.

‘xminortick’: {"off"} | "on"

‘xscale’: {"linear"} | "log"

‘xtick’: vector
     Position of x tick marks.  Setting ‘xtick’ also forces the
     ‘xtickmode’ property to be set to "manual".

‘xticklabel’: string | cell array of strings, def. 1-by-6 cell
     Labels of x tick marks.  Setting ‘xticklabel’ also forces the
     ‘xticklabelmode’ property to be set to "manual".

‘xticklabelmode’: {"auto"} | "manual"

‘xticklabelrotation’: def. ‘0’
     ‘xticklabelrotation’ is unused.

‘xtickmode’: {"auto"} | "manual"

‘yaxis’ (read-only): def. ‘[](0x0)’

‘yaxislocation’: {"left"} | "origin" | "right"
     Control the y-axis location.

‘ycolor’: {colorspec} | "none", def. ‘[0.1500 0.1500 0.1500]’
     Color of the y-axis.  *Note colorspec: Colors.

‘ycolormode’: {"auto"} | "manual"

‘ydir’: {"normal"} | "reverse"
     Direction of the y-axis: "normal" is bottom to top.

‘ygrid’: {"off"} | "on"
     Control whether major y grid lines are displayed.

‘ylabel’: graphics handle
     Graphics handle of the y label text object.

‘ylim’: two-element vector, def. ‘[0 1]’
     Two-element vector ‘[ymin ymax]’ specifying the limits for the
     y-axis.  Setting ‘ylim’ also forces the ‘ylimmode’ property to be
     set to "manual".  *Note ylim function: XREFylim.

‘ylimmode’: {"auto"} | "manual"

‘yminorgrid’: {"off"} | "on"
     Control whether minor y grid lines are displayed.

‘yminortick’: {"off"} | "on"

‘yscale’: {"linear"} | "log"

‘ytick’: vector
     Position of y tick marks.  Setting ‘ytick’ also forces the
     ‘ytickmode’ property to be set to "manual".

‘yticklabel’: string | cell array of strings, def. 1-by-6 cell
     Labels of y tick marks.  Setting ‘yticklabel’ also forces the
     ‘yticklabelmode’ property to be set to "manual".

‘yticklabelmode’: {"auto"} | "manual"

‘yticklabelrotation’: def. ‘0’
     ‘yticklabelrotation’ is unused.

‘ytickmode’: {"auto"} | "manual"

‘zaxis’ (read-only): def. ‘[](0x0)’

‘zcolor’: {colorspec} | "none", def. ‘[0.1500 0.1500 0.1500]’
     Color of the z-axis.  *Note colorspec: Colors.

‘zcolormode’: {"auto"} | "manual"

‘zdir’: {"normal"} | "reverse"

‘zgrid’: {"off"} | "on"
     Control whether major z grid lines are displayed.

‘zlabel’: graphics handle
     Graphics handle of the z label text object.

‘zlim’: two-element vector, def. ‘[0 1]’
     Two-element vector ‘[zmin zmaz]’ specifying the limits for the
     z-axis.  Setting ‘zlim’ also forces the ‘zlimmode’ property to be
     set to "manual".  *Note zlim function: XREFzlim.

‘zlimmode’: {"auto"} | "manual"

‘zminorgrid’: {"off"} | "on"
     Control whether minor z grid lines are displayed.

‘zminortick’: {"off"} | "on"

‘zscale’: {"linear"} | "log"

‘ztick’: vector
     Position of z tick marks.  Setting ‘ztick’ also forces the
     ‘ztickmode’ property to be set to "manual".

‘zticklabel’: string | cell array of strings, def. 1-by-6 cell
     Labels of z tick marks.  Setting ‘zticklabel’ also forces the
     ‘zticklabelmode’ property to be set to "manual".

‘zticklabelmode’: {"auto"} | "manual"

‘zticklabelrotation’: def. ‘0’
     ‘zticklabelrotation’ is unused.

‘ztickmode’: {"auto"} | "manual"


File: octave.info,  Node: Legend Properties,  Next: Line Properties,  Prev: Axes Properties,  Up: Graphics Object Properties

15.3.3.4 Legend Properties
..........................

Properties of ‘legend’ objects (*note legend: XREFlegend.):

‘autoupdate’: "off" | {"on"}
     Control whether the number of legend items is updated automatically
     when objects are added to (or deleted from) the peer axes.  For
     example:
          ## Create a single plot with its legend.
          figure ();
          plot (1:10);
          legend ("Slope 1");
          ## Add another plot and specify its displayname so that
          ## the legend is correctly updated.
          hold on;
          plot ((1:10) * 2, "displayname", "Slope 2");
          ## Stop automatic updates for further plots.
          legend ("autoupdate", "off");
          plot ((1:10) * 3);

‘box’: "off" | {"on"}
     Control whether the legend has a surrounding box.

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the legend background.  *Note colorspec: Colors.

‘edgecolor’: colorspec, def. ‘[0.1500 0.1500 0.1500]’
     Control the color of the legend outline.

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘9’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFlegendfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘location’: "best" | "bestoutside" | "east" | "eastoutside" | "none" | "north" | {"northeast"} | "northeastoutside" | "northoutside" | "northwest" | "northwestoutside" | "south" | "southeast" | "southeastoutside" | "southoutside" | "southwest" | "southwestoutside" | "west" | "westoutside"
     Control the location of the legend.

‘numcolumns’: scalar interger, def. ‘1’
     Control the number of columns used in the layout of the legend
     items.  For example:
          figure ();
          plot (rand (30));
          legend ("numcolumns", 3);
     Setting ‘numcolumns’ also forces the ‘numcolumnsmode’ property to
     be set to "manual".

‘orientation’: "horizontal" | {"vertical"}
     Control whether the legend items are arranged vertically
     (column-wise) or horizontally (row-wise).

‘position’: four-element vector
     Specify the position of the legend excluding its title.  The four
     elements of the vector are the coordinates of the lower left corner
     and width and height of the legend.  Changing this property also
     switches the "location" to "none".

‘string’: string | cell array of strings
     List of labels for the legend items.  For example:
          figure ();
          plot (rand (20));
          ## Let legend choose names automatically
          hl = legend ();
          ## Selectively change some names
          str = get (hl, "string");
          str(1:5:end) = "Garbage";
          set (hl, "string", str);

‘textcolor’: colorspec, def. ‘[0 0 0]’
     Control the color of the text strings for legend items.

‘title’: graphics handle
     Graphics handle of the title text object.

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"
     Units used to interpret the "position", property.


File: octave.info,  Node: Line Properties,  Next: Text Properties,  Prev: Legend Properties,  Up: Graphics Object Properties

15.3.3.5 Line Properties
........................

Properties of ‘line’ objects (*note line: XREFline.):

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the line is clipped in its parent axes
     limits.

‘color’: colorspec, def. ‘[0 0 0]’
     Color of the line object.  *Note colorspec: Colors.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this line object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after line has been created.
     Function is set by using default property on root object, e.g.,
     ‘set (groot, "defaultlinecreatefcn", 'disp ("line created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before line is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘displayname’: string | cell array of strings, def. ""
     Text for the legend entry corresponding to this line.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the line’s handle is not visible in
     its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether line processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFlinepickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘linejoin’: "chamfer" | "miter" | {"round"}
     Control the shape of the junction of line segments.  This property
     currently only affects the printed output.

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"
     *Note Line Styles::.

‘linewidth’: def. ‘0.5000’
     Width of the line object measured in points.

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "_" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x" | "|"
     Shape of the marker for each data point.  *Note Marker Styles::.

‘markeredgecolor’: {"auto"} | "none"
     Color of the edge of the markers.  When set to "auto", the marker
     edges have the same color as the line.  If set to "none", no marker
     edges are displayed.  This property can also be set to any color.
     *Note colorspec: Colors.

‘markerfacecolor’: "auto" | {"none"}
     Color of the face of the markers.  When set to "auto", the marker
     faces have the same color as the line.  If set to "none", the
     marker faces are not displayed.  This property can also be set to
     any color.  *Note colorspec: Colors.

‘markersize’: scalar, def. ‘6’
     Size of the markers measured in points.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether line will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the line or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFlinehittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "line"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the line is not rendered on screen.

‘xdata’: vector, def. ‘[0 1]’
     Vector of x data to be plotted.

‘xdatasource’: string, def. ""
     Name of a vector in the current base workspace to use as x data.

‘ydata’: vector, def. ‘[0 1]’
     Vector of y data to be plotted.

‘ydatasource’: string, def. ""
     Name of a vector in the current base workspace to use as y data.

‘zdata’: vector, def. ‘[](0x0)’
     Vector of z data to be plotted.

‘zdatasource’: string, def. ""
     Name of a vector in the current base workspace to use as z data.


File: octave.info,  Node: Text Properties,  Next: Image Properties,  Prev: Line Properties,  Up: Graphics Object Properties

15.3.3.6 Text Properties
........................

Properties of ‘text’ objects (*note text: XREFtext.):

‘backgroundcolor’: colorspec, def. "none"
     Color of the background area.  *Note colorspec: Colors.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the text is clipped in its parent axes
     limits.

‘color’: colorspec, def. ‘[0 0 0]’
     Color of the text.  *Note colorspec: Colors.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this text object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after text has been created.
     Function is set by using default property on root object, e.g.,
     ‘set (groot, "defaulttextcreatefcn", 'disp ("text created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before text is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘edgecolor’: colorspec, def. "none"
     Color of the outline of the background area.  *Note colorspec:
     Colors.

‘editing’: {"off"} | "on"
     ‘editing’ is unused.

‘extent’ (read-only): four-element vector
     Vector ‘[x0 y0 width height]’ indicating the size and location of
     the text string.

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFtextfontunits.

‘fontsmoothing’: "off" | {"on"}
     Control whether anti-aliasing is used when rendering text.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the text’s handle is not visible in
     its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether text processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFtextpickableparts.

‘horizontalalignment’: "center" | {"left"} | "right"

‘interpreter’: "latex" | "none" | {"tex"}
     Control the way the "string" property is interpreted.  *Note
     Use of the interpreter property: XREFinterpreterusage.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"
     Style of the outline.  *Note Line Styles::.

‘linewidth’: scalar, def. ‘0.5000’
     Width of the outline.

‘margin’: scalar, def. ‘3’
     Margins between the borders of the background area and the texts.
     The value is currently interpreted as pixels, regardless of the
     "fontunits" property.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether text will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the text or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFtexthittest.

‘position’: three-element vector, def. ‘[0 0 0]’
     Vector ‘[X0 Y0 Z0]’ where X0, Y0, and Z0 indicate the position of
     the text anchor as defined by ‘verticalalignment’ and
     ‘horizontalalignment’.

‘rotation’: scalar, def. ‘0’
     The angle of rotation for the displayed text, measured in degrees.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘string’: string, def. ""
     The text object string content.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "text"

‘units’: "centimeters" | {"data"} | "inches" | "normalized" | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘verticalalignment’: "baseline" | "bottom" | "cap" | {"middle"} | "top"

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the text is not rendered on screen.


File: octave.info,  Node: Image Properties,  Next: Patch Properties,  Prev: Text Properties,  Up: Graphics Object Properties

15.3.3.7 Image Properties
.........................

Properties of ‘image’ objects (*note image: XREFimage.):

‘alphadata’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for image objects.  ‘alphadata’
     is unused.

‘alphadatamapping’: "direct" | {"none"} | "scaled"
     Transparency is not yet implemented for image objects.
     ‘alphadatamapping’ is unused.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘cdata’: matrix, def. 64-by-64 double

‘cdatamapping’: {"direct"} | "scaled"

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the image is clipped in its parent axes
     limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this image object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after image has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultimagecreatefcn", 'disp ("image
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before image is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the image’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether image processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFimagepickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether image will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the image or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFimagehittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "image"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the image is not rendered on screen.

‘xdata’: two-element vector, def. ‘[1 64]’
     Two-element vector ‘[xfirst xlast]’ specifying the x coordinates of
     the centers of the first and last columns of the image.

     Setting ‘xdata’ to the empty matrix ([]) will restore the default
     value of ‘[1 columns(image)]’.

‘ydata’: two-element vector, def. ‘[1 64]’
     Two-element vector ‘[yfirst ylast]’ specifying the y coordinates of
     the centers of the first and last rows of the image.

     Setting ‘ydata’ to the empty matrix ([]) will restore the default
     value of ‘[1 rows(image)]’.


File: octave.info,  Node: Patch Properties,  Next: Scatter Properties,  Prev: Image Properties,  Up: Graphics Object Properties

15.3.3.8 Patch Properties
.........................

Properties of ‘patch’ objects (*note patch: XREFpatch.):

‘alphadatamapping’: "direct" | "none" | {"scaled"}
     Transparency is not yet implemented for patch objects.
     ‘alphadatamapping’ is unused.

‘ambientstrength’: scalar, def. ‘0.3000’
     Strength of the ambient light.  Value between 0.0 and 1.0

‘backfacelighting’: "lit" | {"reverselit"} | "unlit"
     "lit": The normals are used as is for lighting.  "reverselit": The
     normals are always oriented towards the point of view.  "unlit":
     Faces with normals pointing away from the point of view are unlit.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘cdata’: scalar | matrix, def. ‘[](0x0)’
     Data defining the patch object color.  Patch color can be defined
     for faces or for vertices.

     If ‘cdata’ is a scalar index into the current colormap or a RGB
     triplet, it defines the color of all faces.

     If ‘cdata’ is an N-by-1 vector of indices or an N-by-3 (RGB)
     matrix, it defines the color of each one of the N faces.

     If ‘cdata’ is an N-by-M or an N-by-M-by-3 (RGB) matrix, it defines
     the color at each vertex.

‘cdatamapping’: "direct" | {"scaled"}

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the patch is clipped in its parent axes
     limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this patch object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after patch has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultpatchcreatefcn", 'disp ("patch
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before patch is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘diffusestrength’: scalar, def. ‘0.6000’
     Strength of the diffuse reflex.  Value between 0.0 (no diffuse
     reflex) and 1.0 (full diffuse reflex).

‘displayname’: def. ""
     Text of the legend entry corresponding to this patch.

‘edgealpha’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for patch objects.  ‘edgealpha’
     is unused.

‘edgecolor’: def. ‘[0 0 0]’

‘edgelighting’: "flat" | "gouraud" | {"none"} | "phong"
     When set to a value other than "none", the edges of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facealpha’: scalar | "flat" | "interp", def. ‘1’
     Transparency level of the faces of the patch object.  Only double
     values are supported at present where a value of 0 means complete
     transparency and a value of 1 means solid faces without
     transparency.  Setting the property to "flat" or "interp" causes
     the faces to not being rendered.  Additionally, the faces are not
     sorted from back to front which might lead to unexpected results
     when rendering layered transparent faces.

‘facecolor’: {colorspec} | "none" | "flat" | "interp", def. ‘[0 0 0]’

‘facelighting’: {"flat"} | "gouraud" | "none" | "phong"
     When set to a value other than "none", the faces of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facenormals’: def. ‘[](0x0)’
     Face normals are used for lighting the edges or faces if the
     ‘edgelighting’ or ‘facelighting’ properties are set to "flat".
     Setting ‘facenormals’ also forces the ‘facenormalsmode’ property to
     be set to "manual"

‘facenormalsmode’: {"auto"} | "manual"
     If this property is set to "auto", ‘facenormals’ are automatically
     calculated if the ‘edgelighting’ or ‘facelighting’ property are set
     to "flat" and at least one ‘light’ object is present and visible in
     the same axes.

‘faces’: vector | matrix, def. ‘[1 2 3]’

‘facevertexalphadata’: scalar | matrix, def. ‘[](0x0)’
     Transparency is not yet implemented for patch objects.
     ‘facevertexalphadata’ is unused.

‘facevertexcdata’: def. ‘[](0x0)’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the patch’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether patch processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFpatchpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"

‘linewidth’: def. ‘0.5000’

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "_" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x" | "|"
     *Note line marker property: XREFlinemarker.

‘markeredgecolor’: {"auto"} | "flat" | "none"
     *Note line markeredgecolor property: XREFlinemarkeredgecolor.

‘markerfacecolor’: "auto" | "flat" | {"none"}
     *Note line markerfacecolor property: XREFlinemarkerfacecolor.

‘markersize’: scalar, def. ‘6’
     *Note line markersize property: XREFlinemarkersize.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether patch will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the patch or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFpatchhittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘specularcolorreflectance’: scalar, def. ‘1’
     Reflectance for specular color.  Value between 0.0 (color of
     underlying face) and 1.0 (color of light source).

‘specularexponent’: scalar, def. ‘10’
     Exponent for the specular reflex.  The lower the value, the more
     the reflex is spread out.

‘specularstrength’: scalar, def. ‘0.9000’
     Strength of the specular reflex.  Value between 0.0 (no specular
     reflex) and 1.0 (full specular reflex).

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "patch"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘vertexnormals’: def. ‘[](0x0)’
     Vertex normals are used for lighting the edges or faces if the
     ‘edgelighting’ or ‘facelighting’ properties are set to "gouraud".
     Setting ‘vertexnormals’ also forces the ‘vertexnormalsmode’
     property to be set to "manual"

‘vertexnormalsmode’: {"auto"} | "manual"
     If this property is set to "auto", ‘vertexnormals’ are
     automatically calculated if the ‘edgelighting’ or ‘facelighting’
     property are set to "gouraud" and at least one ‘light’ object is
     present and visible in the same axes.

‘vertices’: vector | matrix, def. 3-by-2 double

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the patch is not rendered on screen.

‘xdata’: vector | matrix, def. ‘[0; 1; 0]’

‘ydata’: vector | matrix, def. ‘[1; 1; 0]’

‘zdata’: vector | matrix, def. ‘[](0x0)’


File: octave.info,  Node: Scatter Properties,  Next: Surface Properties,  Prev: Patch Properties,  Up: Graphics Object Properties

15.3.3.9 Scatter Properties
...........................

Properties of ‘scatter’ objects (*note scatter: XREFscatter.):

‘annotation’: def. ‘[](0x0)’

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘cdata’: scalar | matrix, def. ‘[0 0.4470 0.7410]’
     Data defining the scatter object color.

     If ‘cdata’ is a scalar index into the current colormap or a RGB
     triplet, it defines the color of all scatter markers.

     If ‘cdata’ is an N-by-1 vector of indices or an N-by-3 (RGB)
     matrix, it defines the color of each one of the N scatter markers.

‘cdatamode’: {"auto"} | "manual"
     If ‘cdatamode’ is "auto", ‘cdata’ is set to the color from the
     ‘colororder’ of the ancestor axes corresponding to the
     ‘seriesindex’.

‘cdatasource’: def. ""
     Data from workspace variables is not yet implemented for scatter
     objects.  ‘cdatasource’ is unused.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the scatter is clipped in its parent axes
     limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this scatter object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after scatter has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultscattercreatefcn", 'disp ("scatter
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘datatiptemplate’: def. ‘[](0x0)’

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before scatter is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘displayname’: def. ""
     Text of the legend entry corresponding to this scatter object.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the scatter’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether scatter processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFscatterpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘latitudedata’: def. ‘[](0x0)’

‘latitudedatasource’: def. ""

‘linewidth’: def. ‘0.5000’
     Line width of the edge of the markers.

‘longitudedata’: def. ‘[](0x0)’

‘longitudedatasource’: def. ""

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "_" | "d" | "diamond" | "h" | "hexagram" | "none" | {"o"} | "p" | "pentagram" | "s" | "square" | "v" | "x" | "|"
     *Note line marker property: XREFlinemarker.

‘markeredgealpha’: scalar, def. ‘1’
     Transparency level of the faces of the markers where a value of 0
     means complete transparency and a value of 1 means solid faces
     without transparency.  Note that the markers are not sorted from
     back to front which might lead to unexpected results when rendering
     layered transparent markers or in combination with other
     transparent objects.

‘markeredgecolor’: {"none"} | {"flat"} | colorspec
     Color of the edge of the markers.  "none" means that the edges are
     transparent and "flat" means that the value from ‘cdata’ is used.
     *Note line markeredgecolor property: XREFlinemarkeredgecolor.

‘markerfacealpha’: scalar, def. ‘1’
     Transparency level of the faces of the markers where a value of 0
     means complete transparency and a value of 1 means solid faces
     without transparency.  Note that the markers are not sorted from
     back to front which might lead to unexpected results when rendering
     layered transparent markers or in combination with other
     transparent objects.

‘markerfacecolor’: {{"none"}} | "flat" | "auto" | colorspec
     Color of the face of the markers.  "none" means that the faces are
     transparent, "flat" means that the value from ‘cdata’ is used, and
     "auto" uses the ‘color’ property of the ancestor axes.  *Note
     line markerfacecolor property: XREFlinemarkerfacecolor.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether scatter will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the scatter
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFscatterhittest.

‘rdata’: def. ‘[](0x0)’

‘rdatasource’: def. ""

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘seriesindex’: def. ‘1’
     Each scatter object in the same axes is asigned an incrementing
     integer.  This corresponds to the index into the ‘colororder’ of
     the ancestor axes that is used if ‘cdatamode’ is set to "auto".

‘sizedata’: [] | scalar | vector, def. ‘[](0x0)’
     Size of the area of the marker.  A scalar value applies to all
     markers.  If ‘cdata’ is an N-by-1 vector, it defines the color of
     each one of the N scatter markers.

‘sizedatasource’: def. ""
     Data from workspace variables is not yet implemented for scatter
     objects.  ‘sizedatasource’ is unused.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘thetadata’: def. ‘[](0x0)’

‘thetadatasource’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "scatter"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the scatter is not rendered on screen.

‘xdata’: vector, def. ‘[](0x0)’
     Vector with the x coordinates of the scatter object.

‘xdatasource’: def. ""
     Data from workspace variables is not yet implemented for scatter
     objects.  ‘xdatasource’ is unused.

‘ydata’: vector, def. ‘[](0x0)’
     Vector with the y coordinates of the scatter object.

‘ydatasource’: def. ""
     Data from workspace variables is not yet implemented for scatter
     objects.  ‘ydatasource’ is unused.

‘zdata’: [] | vector, def. ‘[](0x0)’
     For 3D data, vector with the y coordinates of the scatter object.

‘zdatasource’: def. ""
     Data from workspace variables is not yet implemented for scatter
     objects.  ‘zdatasource’ is unused.


File: octave.info,  Node: Surface Properties,  Next: Light Properties,  Prev: Scatter Properties,  Up: Graphics Object Properties

15.3.3.10 Surface Properties
............................

Properties of ‘surface’ objects (*note surface: XREFsurface.):

‘alphadata’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for surface objects.
     ‘alphadata’ is unused.

‘alphadatamapping’: "direct" | "none" | {"scaled"}
     Transparency is not yet implemented for surface objects.
     ‘alphadatamapping’ is unused.

‘ambientstrength’: scalar, def. ‘0.3000’
     Strength of the ambient light.  Value between 0.0 and 1.0

‘backfacelighting’: "lit" | {"reverselit"} | "unlit"
     "lit": The normals are used as is for lighting.  "reverselit": The
     normals are always oriented towards the point of view.  "unlit":
     Faces with normals pointing away from the point of view are unlit.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘cdata’: matrix, def. 3-by-3 double

‘cdatamapping’: "direct" | {"scaled"}

‘cdatasource’: def. ""

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the surface is clipped in its parent axes
     limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this surface object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after surface has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultsurfacecreatefcn", 'disp ("surface
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before surface is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘diffusestrength’: scalar, def. ‘0.6000’
     Strength of the diffuse reflex.  Value between 0.0 (no diffuse
     reflex) and 1.0 (full diffuse reflex).

‘displayname’: def. ""
     Text for the legend entry corresponding to this surface.

‘edgealpha’: scalar, def. ‘1’
     Transparency is not yet implemented for surface objects.
     ‘edgealpha’ is unused.

‘edgecolor’: def. ‘[0 0 0]’

‘edgelighting’: "flat" | "gouraud" | {"none"} | "phong"
     When set to a value other than "none", the edges of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facealpha’: scalar | "flat" | "interp" | "texturemap", def. ‘1’
     Transparency level of the faces of the surface object.  Only double
     values are supported at present where a value of 0 means complete
     transparency and a value of 1 means solid faces without
     transparency.  Setting the property to "flat", "interp" or
     "texturemap" causes the faces to not being rendered.  Additionally,
     the faces are not sorted from back to front which might lead to
     unexpected results when rendering layered transparent faces.

‘facecolor’: {"flat"} | "interp" | "none" | "texturemap"

‘facelighting’: {"flat"} | "gouraud" | "none" | "phong"
     When set to a value other than "none", the faces of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facenormals’: def. ‘[](0x0)’
     Face normals are used for lighting the edges or faces if the
     ‘edgelighting’ or ‘facelighting’ properties are set to "flat".
     Setting ‘facenormals’ also forces the ‘facenormalsmode’ property to
     be set to "manual"

‘facenormalsmode’: {"auto"} | "manual"
     If this property is set to "auto", ‘facenormals’ are automatically
     calculated if the ‘edgelighting’ or ‘facelighting’ property are set
     to "flat" and at least one ‘light’ object is present and visible in
     the same axes.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the surface’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether surface processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFsurfacepickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"
     *Note Line Styles::.

‘linewidth’: def. ‘0.5000’
     *Note line linewidth property: XREFlinelinewidth.

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "_" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x" | "|"
     *Note Marker Styles::.

‘markeredgecolor’: {"auto"} | "flat" | "none"
     *Note line markeredgecolor property: XREFlinemarkeredgecolor.

‘markerfacecolor’: "auto" | "flat" | {"none"}
     *Note line markerfacecolor property: XREFlinemarkerfacecolor.

‘markersize’: scalar, def. ‘6’
     *Note line markersize property: XREFlinemarkersize.

‘meshstyle’: {"both"} | "column" | "row"

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether surface will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the surface
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFsurfacehittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘specularcolorreflectance’: scalar, def. ‘1’
     Reflectance for specular color.  Value between 0.0 (color of
     underlying face) and 1.0 (color of light source).

‘specularexponent’: scalar, def. ‘10’
     Exponent for the specular reflex.  The lower the value, the more
     the reflex is spread out.

‘specularstrength’: scalar, def. ‘0.9000’
     Strength of the specular reflex.  Value between 0.0 (no specular
     reflex) and 1.0 (full specular reflex).

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "surface"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘vertexnormals’: def. ‘[](0x0)’
     Vertex normals are used for lighting the edges or faces if the
     ‘edgelighting’ or ‘facelighting’ properties are set to "gouraud".
     Setting ‘vertexnormals’ also forces the ‘vertexnormalsmode’
     property to be set to "manual"

‘vertexnormalsmode’: {"auto"} | "manual"
     If this property is set to "auto", ‘vertexnormals’ are
     automatically calculated if the ‘edgelighting’ or ‘facelighting’
     property are set to "gouraud" and at least one ‘light’ object is
     present and visible in the same axes.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the surface is not rendered on screen.

‘xdata’: matrix, def. ‘[1 2 3]’

‘xdatasource’: def. ""

‘ydata’: matrix, def. ‘[1; 2; 3]’

‘ydatasource’: def. ""

‘zdata’: matrix, def. 3-by-3 double

‘zdatasource’: def. ""


File: octave.info,  Node: Light Properties,  Next: Uimenu Properties,  Prev: Surface Properties,  Up: Graphics Object Properties

15.3.3.11 Light Properties
..........................

Properties of ‘light’ objects (*note light: XREFlight.):

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the light is clipped in its parent axes
     limits.

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the light source.  *Note colorspec: Colors.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this light object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after light has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultlightcreatefcn", 'disp ("light
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before light is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the light’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether light processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFlightpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether light will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the light or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFlighthittest.

‘position’: def. ‘[1 0 1]’
     Position of the light source.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘style’: {"infinite"} | "local"
     This string defines whether the light emanates from a light source
     at infinite distance ("infinite") or from a local point source
     ("local").

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "light"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the light is not rendered on screen.


File: octave.info,  Node: Uimenu Properties,  Next: Uibuttongroup Properties,  Prev: Light Properties,  Up: Graphics Object Properties

15.3.3.12 Uimenu Properties
...........................

Properties of ‘uimenu’ objects (*note uimenu: XREFuimenu.):

‘accelerator’: def. ""

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘callback’: def. ‘[](0x0)’

‘checked’: {"off"} | "on"

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uimenu’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uimenu is clipped in its parent axes
     limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uimenu object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uimenu has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuimenucreatefcn", 'disp ("uimenu
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uimenu is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘enable’: "off" | {"on"}

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uimenu’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uimenu processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuimenupickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘label’: def. ""

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uimenu will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the uimenu
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFuimenuhittest.

‘position’: def. ‘4’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘separator’: {"off"} | "on"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘text’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uimenu"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uimenu is not rendered on screen.


File: octave.info,  Node: Uibuttongroup Properties,  Next: Uicontextmenu Properties,  Prev: Uimenu Properties,  Up: Graphics Object Properties

15.3.3.13 Uibuttongroup Properties
..................................

Properties of ‘uibuttongroup’ objects (*note uibuttongroup:
XREFuibuttongroup.):

‘backgroundcolor’: def. ‘[0.9400 0.9400 0.9400]’

‘beingdeleted’: {"off"} | "on"

‘bordertype’: "beveledin" | "beveledout" | {"etchedin"} | "etchedout" | "line" | "none"

‘borderwidth’: def. ‘1’

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uibuttongroup’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uibuttongroup is clipped in its parent
     axes limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uibuttongroup object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uibuttongroup has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuibuttongroupcreatefcn", 'disp
     ("uibuttongroup created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uibuttongroup is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuibuttongroupfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uibuttongroup’s handle is not
     visible in its parent’s "children" property.

‘highlightcolor’: def. ‘[1 1 1]’

‘hittest’: "off" | {"on"}
     Specify whether uibuttongroup processes mouse events or passes them
     to ancestors of the object.  When enabled, the object may respond
     to mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuibuttongrouppickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uibuttongroup will accept mouse clicks.  By
     default, ‘pickableparts’ is "visible" and only visible parts of the
     uibuttongroup or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuibuttongrouphittest.

‘position’: def. ‘[0 0 1 1]’

‘resizefcn’: string | function handle, def. ‘[](0x0)’
     ‘resizefcn’ is deprecated.  Use ‘sizechangedfcn’ instead.

‘selected’: {"off"} | "on"

‘selectedobject’: def. ‘[](0x0)’

‘selectionchangedfcn’: def. ‘[](0x0)’

‘selectionhighlight’: "off" | {"on"}

‘shadowcolor’: def. ‘[0.7000 0.7000 0.7000]’

‘sizechangedfcn’: string | function handle, def. ‘[](0x0)’
     Callback triggered when the uibuttongroup size is changed.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘title’: def. ""

‘titleposition’: "centerbottom" | "centertop" | "leftbottom" | {"lefttop"} | "rightbottom" | "righttop"

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always
     "uibuttongroup"

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uibuttongroup is not rendered on screen.


File: octave.info,  Node: Uicontextmenu Properties,  Next: Uipanel Properties,  Prev: Uibuttongroup Properties,  Up: Graphics Object Properties

15.3.3.14 Uicontextmenu Properties
..................................

Properties of ‘uicontextmenu’ objects (*note uicontextmenu:
XREFuicontextmenu.):

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘callback’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uicontextmenu’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uicontextmenu is clipped in its parent
     axes limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uicontextmenu object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uicontextmenu has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuicontextmenucreatefcn", 'disp
     ("uicontextmenu created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uicontextmenu is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uicontextmenu’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uicontextmenu processes mouse events or passes them
     to ancestors of the object.  When enabled, the object may respond
     to mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuicontextmenupickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uicontextmenu will accept mouse clicks.  By
     default, ‘pickableparts’ is "visible" and only visible parts of the
     uicontextmenu or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuicontextmenuhittest.

‘position’: def. ‘[0 0]’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always
     "uicontextmenu"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uicontextmenu is not rendered on screen.


File: octave.info,  Node: Uipanel Properties,  Next: Uicontrol Properties,  Prev: Uicontextmenu Properties,  Up: Graphics Object Properties

15.3.3.15 Uipanel Properties
............................

Properties of ‘uipanel’ objects (*note uipanel: XREFuipanel.):

‘backgroundcolor’: def. ‘[0.9400 0.9400 0.9400]’

‘beingdeleted’: {"off"} | "on"

‘bordertype’: "beveledin" | "beveledout" | {"etchedin"} | "etchedout" | "line" | "none"

‘borderwidth’: def. ‘1’

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uipanel’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uipanel is clipped in its parent axes
     limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uipanel object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uipanel has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuipanelcreatefcn", 'disp ("uipanel
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uipanel is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuipanelfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uipanel’s handle is not visible
     in its parent’s "children" property.

‘highlightcolor’: def. ‘[1 1 1]’

‘hittest’: "off" | {"on"}
     Specify whether uipanel processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuipanelpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uipanel will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the uipanel
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFuipanelhittest.

‘position’: def. ‘[0 0 1 1]’

‘resizefcn’: string | function handle, def. ‘[](0x0)’
     ‘resizefcn’ is deprecated.  Use ‘sizechangedfcn’ instead.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘shadowcolor’: def. ‘[0.7000 0.7000 0.7000]’

‘sizechangedfcn’: string | function handle, def. ‘[](0x0)’
     Callback triggered when the uipanel size is changed.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘title’: def. ""

‘titleposition’: "centerbottom" | "centertop" | "leftbottom" | {"lefttop"} | "rightbottom" | "righttop"

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uipanel"

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uipanel is not rendered on screen.


File: octave.info,  Node: Uicontrol Properties,  Next: Uitable Properties,  Prev: Uipanel Properties,  Up: Graphics Object Properties

15.3.3.16 Uicontrol Properties
..............................

Properties of ‘uicontrol’ objects (*note uicontrol: XREFuicontrol.):

‘backgroundcolor’: def. ‘[0.9400 0.9400 0.9400]’

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘callback’: def. ‘[](0x0)’

‘cdata’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uicontrol’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uicontrol is clipped in its parent axes
     limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uicontrol object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uicontrol has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuicontrolcreatefcn", 'disp ("uicontrol
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uicontrol is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘enable’: "inactive" | "off" | {"on"}

‘extent’ (read-only): four-element vector
     Size of the text string associated to the uicontrol returned in the
     form ‘[0 0 width height]’ (the two first elements are always zero).

     For multi-line strings the returned ‘width’ and ‘height’ indicate
     the size of the rectangle enclosing all lines.

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuicontrolfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uicontrol’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uicontrol processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuicontrolpickableparts.

‘horizontalalignment’: {"center"} | "left" | "right"

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘keypressfcn’: def. ‘[](0x0)’

‘listboxtop’: def. ‘1’

‘max’: def. ‘1’

‘min’: def. ‘0’

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uicontrol will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uicontrol or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuicontrolhittest.

‘position’: def. ‘[0 0 80 30]’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘sliderstep’: def. ‘[0.010000 0.100000]’

‘string’: def. ""

‘style’: "checkbox" | "edit" | "frame" | "listbox" | "popupmenu" | {"pushbutton"} | "radiobutton" | "slider" | "text" | "togglebutton"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uicontrol"

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘value’: def. ‘0’

‘verticalalignment’: "bottom" | {"middle"} | "top"

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uicontrol is not rendered on screen.


File: octave.info,  Node: Uitable Properties,  Next: Uitoolbar Properties,  Prev: Uicontrol Properties,  Up: Graphics Object Properties

15.3.3.17 Uitable Properties
............................

Properties of ‘uitable’ objects (*note uitable: XREFuitable.):

‘backgroundcolor’: def. 2-by-3 double

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘celleditcallback’: def. ‘[](0x0)’

‘cellselectioncallback’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uitable’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitable is clipped in its parent axes
     limits.

‘columneditable’: def. ‘[](0x0)’

‘columnformat’: def. ‘{}(0x0)’

‘columnname’: def. "numbered"

‘columnwidth’: def. "auto"

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitable object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitable has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuitablecreatefcn", 'disp ("uitable
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘data’: def. ‘[](0x0)’

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitable is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘enable’: "off" | {"on"}

‘extent’ (read-only): four-element vector

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuitablefontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitable’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uitable processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuitablepickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘keypressfcn’: def. ‘[](0x0)’

‘keyreleasefcn’: def. ‘[](0x0)’

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uitable will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the uitable
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFuitablehittest.

‘position’: def. ‘[20 20 300 300]’

‘rearrangeablecolumns’: {"off"} | "on"

‘rowname’: def. "numbered"

‘rowstriping’: "off" | {"on"}

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uitable"

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitable is not rendered on screen.


File: octave.info,  Node: Uitoolbar Properties,  Next: Uipushtool Properties,  Prev: Uitable Properties,  Up: Graphics Object Properties

15.3.3.18 Uitoolbar Properties
..............................

Properties of ‘uitoolbar’ objects (*note uitoolbar: XREFuitoolbar.):

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uitoolbar’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitoolbar is clipped in its parent axes
     limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitoolbar object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitoolbar has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuitoolbarcreatefcn", 'disp ("uitoolbar
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitoolbar is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitoolbar’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uitoolbar processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuitoolbarpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uitoolbar will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uitoolbar or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuitoolbarhittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uitoolbar"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitoolbar is not rendered on screen.


File: octave.info,  Node: Uipushtool Properties,  Next: Uitoggletool Properties,  Prev: Uitoolbar Properties,  Up: Graphics Object Properties

15.3.3.19 Uipushtool Properties
...............................

Properties of ‘uipushtool’ objects (*note uipushtool: XREFuipushtool.):

‘__named_icon__’: def. ""

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘cdata’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uipushtool’s children.

‘clickedcallback’: def. ‘[](0x0)’

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uipushtool is clipped in its parent axes
     limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uipushtool object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uipushtool has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuipushtoolcreatefcn", 'disp ("uipushtool
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uipushtool is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘enable’: "off" | {"on"}

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uipushtool’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uipushtool processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuipushtoolpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uipushtool will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uipushtool or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuipushtoolhittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘separator’: {"off"} | "on"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uipushtool"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uipushtool is not rendered on screen.


File: octave.info,  Node: Uitoggletool Properties,  Prev: Uipushtool Properties,  Up: Graphics Object Properties

15.3.3.20 Uitoggletool Properties
.................................

Properties of ‘uitoggletool’ objects (*note uitoggletool:
XREFuitoggletool.):

‘__named_icon__’: def. ""

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object’s callback
     properties when it is unable to interrupt another object’s
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘cdata’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uitoggletool’s children.

‘clickedcallback’: def. ‘[](0x0)’

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitoggletool is clipped in its parent
     axes limits.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitoggletool object.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitoggletool has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuitoggletoolcreatefcn", 'disp
     ("uitoggletool created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitoggletool is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘enable’: "off" | {"on"}

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitoggletool’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}
     Specify whether uitoggletool processes mouse events or passes them
     to ancestors of the object.  When enabled, the object may respond
     to mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuitoggletoolpickableparts.

‘interruptible’: "off" | {"on"}
     Specify whether this object’s callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘offcallback’: def. ‘[](0x0)’

‘oncallback’: def. ‘[](0x0)’

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uitoggletool will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uitoggletool or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuitoggletoolhittest.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘separator’: {"off"} | "on"

‘state’: {"off"} | "on"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uitoggletool"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitoggletool is not rendered on screen.


File: octave.info,  Node: Searching Properties,  Next: Managing Default Properties,  Prev: Graphics Object Properties,  Up: Graphics Data Structures

15.3.4 Searching Properties
---------------------------

 -- : H = findobj ()
 -- : H = findobj (PROP_NAME, PROP_VALUE, ...)
 -- : H = findobj (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME,
          PROP_VALUE)
 -- : H = findobj ("-property", PROP_NAME)
 -- : H = findobj ("-regexp", PROP_NAME, PATTERN)
 -- : H = findobj (HLIST, ...)
 -- : H = findobj (HLIST, "flat", ...)
 -- : H = findobj (HLIST, "-depth", D, ...)
     Find graphics objects with specified properties.

     When called without arguments, return all graphic objects beginning
     with the root object (0) and including all of its descendants.

     The simplest form for narrowing the results is

          findobj (PROP_NAME, PROP_VALUE)

     which returns the handles of all objects which have a property
     named PROP_NAME that has the value PROP_VALUE.  If multiple
     property/value pairs are specified then only objects meeting all of
     the conditions (equivalent to ‘-and’) are returned.

     The search can be limited to a particular set of objects and their
     descendants, by passing a handle or set of handles HLIST as the
     first argument.

     The depth of the object hierarchy to search can be limited with the
     "-depth" argument.  An example of searching through only three
     generations of children is:

          findobj (HLIST, "-depth", 3, PROP_NAME, PROP_VALUE)

     Specifying a depth D of 0 limits the search to the set of objects
     passed in HLIST.  A depth of 0 is also equivalent to the "flat"
     argument.  The default depth value is ‘Inf’ which includes all
     descendants.

     A specified logical operator may be used between PROP_NAME,
     PROP_VALUE pairs.  The supported logical operators are: "-and",
     "-or", "-xor", "-not".  Example code to locate all figure and axes
     objects is

          findobj ("type", "figure", "-or", "type", "axes")

     Objects may also be matched by comparing a regular expression to
     the property values, where property values that match ‘regexp
     (PROP_VALUE, PATTERN)’ are returned.

     Finally, objects which have a property name can be found with the
     "-property" option.  For example, code to locate objects with a
     "meshstyle" property is

          findobj ("-property", "meshstyle")

     Implementation Note: The search only includes objects with visible
     handles (HandleVisibility = "on").  *Note ‘findall’: XREFfindall,
     to search for all objects including hidden ones.

     See also: *note findall: XREFfindall, *note allchild: XREFallchild,
     *note get: XREFget, *note set: XREFset.

 -- : H = findall ()
 -- : H = findall (PROP_NAME, PROP_VALUE, ...)
 -- : H = findall (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME,
          PROP_VALUE)
 -- : H = findall ("-property", PROP_NAME)
 -- : H = findall ("-regexp", PROP_NAME, PATTERN)
 -- : H = findall (HLIST, ...)
 -- : H = findall (HLIST, "flat", ...)
 -- : H = findall (HLIST, "-depth", D, ...)
     Find graphics object, including hidden ones, with specified
     properties.

     The return value H is a list of handles to the found graphic
     objects.

     ‘findall’ performs the same search as ‘findobj’, but it includes
     hidden objects (HandleVisibility = "off").  For full documentation,
     *note ‘findobj’: XREFfindobj.

     See also: *note findobj: XREFfindobj, *note allchild: XREFallchild,
     *note get: XREFget, *note set: XREFset.


File: octave.info,  Node: Managing Default Properties,  Prev: Searching Properties,  Up: Graphics Data Structures

15.3.5 Managing Default Properties
----------------------------------

Object properties have two classes of default values, “factory defaults”
(the initial values) and “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, of the specified object type.
For example, setting the default ‘color’ property of ‘line’ objects to
"green", for the ‘root’ object, will result in all ‘line’ objects
inheriting the ‘color’ "green" as the default value.

     set (groot, "defaultlinecolor", "green");

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

     default + OBJECT-TYPE + PROPERTY-NAME

   This rule can lead to some strange looking names, for example
‘defaultlinelinewidth"’ specifies the default ‘linewidth’ property for
‘line’ objects.

   The example above used the root object 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 object.  Likewise, defaults set in an axes object override
those set in figure or root objects.  For example,

     subplot (2, 1, 1);
     set (groot, "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));

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 object.

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

     set (gca (), "defaultlinecolor", "remove");

removes the user-defined default line color setting from the current
axes object.  To quickly remove all user-defined defaults use the
‘reset’ function.

   By default, high level plotting functions such as ‘plot’ reset and
redefine axes properties independently from the defaults.  An example of
such property is the axes ‘box’ property: it is set ‘on’ by high level
2-D graphics functions regardless of the property "defaultaxesbox".  Use
the ‘hold’ function to prevent this behavior:

     set (groot, "defaultaxesbox", "off");
     subplot (2, 1, 1);
     plot (1:10)
     title ("Box is on anyway")
     subplot (2, 1, 2);
     hold on
     plot (1:10)
     title ("Box is off")

 -- : reset (H)
     Reset the properties of the graphic object H to their default
     values.

     For figures, the properties "position", "units", "windowstyle", and
     "paperunits" are not affected.  For axes, the properties "position"
     and "units" are not affected.

     The input H may also be a vector of graphic handles in which case
     each individual object will be reset.

     See also: *note cla: XREFcla, *note clf: XREFclf, *note newplot:
     XREFnewplot.

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

     get (gca (), "default");

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

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

     get (groot, "factory");

returns a list of factory defaults.


File: octave.info,  Node: Advanced Plotting,  Prev: Graphics Data Structures,  Up: Plotting

15.4 Advanced Plotting
======================

* Menu:

* Colors::
* Line Styles::
* Marker Styles::
* Callbacks::
* Application-defined Data::
* Object Groups::
* Transform Groups::
* Graphics Toolkits::


File: octave.info,  Node: Colors,  Next: Line Styles,  Up: Advanced Plotting

15.4.1 Colors
-------------

Colors may be specified in three ways: 1) RGB triplets, 2) by name, or
3) by HTML notation.

RGB triplet

     An RGB triplet is a 1x3 vector where each value is between 0 and 1
     inclusive.  The first value represents the percentage of Red, the
     second value the percentage of Green, and the third value the
     percentage of Blue.  For example, ‘[1, 0, 1]’ represents full Red
     and Blue channels resulting in the color magenta.

short or long name

     Eight colors can be specified directly by name or by a single
     character short name.

     Name            Color
     --------------------------------------------------------------------------
     ‘k’, "black"    blacK
     ‘r’, "red"      Red
     ‘g’, "green"    Green
     ‘b’, "blue"     Blue
     ‘y’, "yellow"   Yellow
     ‘m’,            Magenta
     "magenta"
     ‘c’, "cyan"     Cyan
     ‘w’, "white"    White

HTML notation

     HTML notation is a string that begins with the character ‘#’ and is
     followed by either 3 or 6 hexadecimal digits.  As with RGB
     triplets, each hexadecimal number represents the fraction of the
     Red, Green, and Blue channels present in the specified color.  For
     example, "#FF00FF" represents the color magenta.


File: octave.info,  Node: Line Styles,  Next: Marker Styles,  Prev: Colors,  Up: Advanced Plotting

15.4.2 Line Styles
------------------

Line styles are specified by the following properties:

‘linestyle’
     May be one of

     "-"
          Solid line.  [default]

     "--"
          Dashed line.

     ":"
          Dotted line.

     "-."
          A dash-dot line.

     "none"
          No line.  Points will still be marked using the current Marker
          Style.

‘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.


File: octave.info,  Node: Marker Styles,  Next: Callbacks,  Prev: Line Styles,  Up: Advanced Plotting

15.4.3 Marker Styles
--------------------

Marker styles are specified by the following properties:

‘marker’
     A character indicating a plot marker to be place at each data
     point, or "none", meaning no markers should be displayed.

‘markeredgecolor’
     The color of the edge around the marker, or "auto", meaning that
     the edge color is the same as the face color.  *Note Colors::.

‘markerfacecolor’
     The color of the marker, or "none" to indicate that the marker
     should not be filled.  *Note Colors::.

‘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.

   The ‘colstyle’ function will parse a ‘plot’-style specification and
will return the color, line, and marker values that would result.

 -- : [STYLE, COLOR, MARKER, MSG] = colstyle (STYLE)
     Parse the line specification STYLE and return the line style,
     color, and markers given.

     In the case of an error, the string MSG will return the text of the
     error.


File: octave.info,  Node: Callbacks,  Next: Application-defined Data,  Prev: Marker Styles,  Up: Advanced Plotting

15.4.4 Callbacks
----------------

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

     function mycallback (hsrc, evt)
       ...
     endfunction

where ‘hsrc’ is a handle to the source of the callback, and ‘evt’ gives
some event specific data.

   The function can be provided as a function handle to a plain Octave
function, as an anonymous function, or as a string representing an
Octave command.  The latter syntax is not recommended since syntax
errors will only occur when the string is evaluated.  *Note Function
Handles section: Function Handles and Anonymous Functions.

   This can then be associated with an object either at the object’s
creation, or later with the ‘set’ function.  For example,

     plot (x, "DeleteFcn", @(h, e) disp ("Window Deleted"))

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 two default arguments.  For example:

     plot (x, "DeleteFcn", {@mycallback, "1"})
     ...
     function mycallback (h, evt, arg1)
       fprintf ("Closing plot %d\n", arg1);
     endfunction

   *Caution:* The second argument in callback functions—‘evt’—is only
partially implemented in the Qt graphics toolkit:

   • Mouse click events: ‘evt’ is a class ‘double’ value: 1 for left, 2
     for middle, and 3 for right click.

   • Key press events: ‘evt’ is a structure with fields ‘Key’ (string),
     ‘Character’ (string), and ‘Modifier’ (cell array of strings).

   • Other events: ‘evt’ is a class ‘double’ empty matrix.

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

   • CreateFcn: 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 ‘CreateFcn’ later with the
     ‘set’ function will never be executed.

   • DeleteFcn: called at the moment an object is deleted.

   • ButtonDownFcn: called if a mouse button is pressed while the
     pointer is over this object.  Note, that the gnuplot interface does
     not implement this callback.

   By default callback functions are queued (they are executed one after
the other in the event queue) unless the ‘drawnow’, ‘figure’, ‘waitfor’,
‘getframe’, or ‘pause’ functions are used.  If an executing callback
invokes one of those functions, it causes Octave to flush the event
queue, which results in the executing callback being interrupted.

   It is possible to specify that an object’s callbacks should not be
interrupted by setting the object’s ‘interruptible’ property to "off".
In this case, Octave decides what to do based on the ‘busyaction’
property of the *interrupting* callback object:

‘queue’ (the default)
     The interrupting callback is executed after the executing callback
     has returned.

‘cancel’
     The interrupting callback is discarded.

   The ‘interruptible’ property has no effect when the interrupting
callback is a ‘deletefcn’, or a figure ‘resizefcn’ or ‘closerequestfcn’.
Those callbacks always interrupt the executing callback.

   The handle to the object that holds the callback being executed can
be obtained with the ‘gcbo’ function.  The handle to the ancestor figure
of this object may be obtained using the ‘gcbf’ function.

 -- : H = gcbo ()
 -- : [H, FIG] = gcbo ()
     Return a handle to the object whose callback is currently
     executing.

     If no callback is executing, this function returns the empty
     matrix.  This handle is obtained from the root object property
     "CallbackObject".

     When called with a second output argument, return the handle of the
     figure containing the object whose callback is currently executing.
     If no callback is executing the second output is also set to the
     empty matrix.

     See also: *note gcbf: XREFgcbf, *note gco: XREFgco, *note gca:
     XREFgca, *note gcf: XREFgcf, *note get: XREFget, *note set:
     XREFset.

 -- : FIG = gcbf ()
     Return a handle to the figure containing the object whose callback
     is currently executing.

     If no callback is executing, this function returns the empty
     matrix.  The handle returned by this function is the same as the
     second output argument of ‘gcbo’.

     See also: *note gcbo: XREFgcbo, *note gcf: XREFgcf, *note gco:
     XREFgco, *note gca: XREFgca, *note get: XREFget, *note set:
     XREFset.

   Callbacks can equally be added to properties with the ‘addlistener’
function described below.


File: octave.info,  Node: Application-defined Data,  Next: Object Groups,  Prev: Callbacks,  Up: Advanced Plotting

15.4.5 Application-defined Data
-------------------------------

Octave has a provision for attaching application-defined data to a
graphics handle.  The data can be anything which is meaningful to the
application, and will be completely ignored by Octave.

 -- : setappdata (H, NAME, VALUE)
 -- : setappdata (H, NAME1, VALUE1, NAME2, VALUE3, ...)
 -- : setappdata (H, {NAME1, NAME2, ...}, {VALUE1, VALUE2, ...})
     Set the application data NAME to VALUE for the graphics object with
     handle H.

     H may also be a vector of graphics handles.  If the application
     data with the specified NAME does not exist, it is created.

     Multiple NAME/VALUE pairs can be specified.  Alternatively, a cell
     array of NAMES and a corresponding cell array of VALUES can be
     specified.  For details on obtaining a list of valid application
     data properties, *note ‘getappdata’: XREFgetappdata.

     See also: *note getappdata: XREFgetappdata, *note isappdata:
     XREFisappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.

 -- : VALUE = getappdata (H, NAME)
 -- : APPDATA = getappdata (H)
     Return the VALUE of the application data NAME for the graphics
     object with handle H.

     H may also be a vector of graphics handles.  If no second argument
     NAME is given then ‘getappdata’ returns a structure, APPDATA, whose
     fields correspond to the appdata properties.

     See also: *note setappdata: XREFsetappdata, *note isappdata:
     XREFisappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.

 -- : rmappdata (H, NAME)
 -- : rmappdata (H, NAME1, NAME2, ...)
     Delete the application data NAME from the graphics object with
     handle H.

     H may also be a vector of graphics handles.  Multiple application
     data names may be supplied to delete several properties at once.

     See also: *note setappdata: XREFsetappdata, *note getappdata:
     XREFgetappdata, *note isappdata: XREFisappdata.

 -- : VALID = isappdata (H, NAME)
     Return true if the named application data, NAME, exists for the
     graphics object with handle H.

     H may also be a vector of graphics handles.

     See also: *note getappdata: XREFgetappdata, *note setappdata:
     XREFsetappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.

