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

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

Copyright © 1996-2020 John W. Eaton.

   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: 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
----------------------------------------

All text objects—such as titles, labels, legends, and text—include the
property "interpreter" that determines the manner in which special
control sequences in the text are rendered.

   The interpreter property can take three values: "none", "tex",
"latex".  If the interpreter is set to "none" then no special rendering
occurs—the displayed text is a verbatim copy of the specified text.
Currently, the "latex" interpreter is not implemented for on-screen
display and is equivalent to "none".  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.

   The "tex" option 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

15.2.8.1 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: 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.  The "latex" interpreter will not
display symbols on-screen, but the printed output will be correct.  When
printing, use one of the ‘standalone’ options which provide full access
to LaTeX commands.

   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:
               The actual font is embedded in the output file which
               allows for printing arbitrary characters and fonts in all
               vector formats.

          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 graphic object H to the file FILENAME in graphic format FMT.

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

     ‘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 "pdf".

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

     See also: *note print: XREFprint, *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 and these objects are the graphics data structures
themselves.  The primitive graphic object types are: ‘figure’, ‘axes’,
‘line’, ‘text’, ‘patch’, ‘surface’, ‘text’, ‘image’, and ‘light’.

   Each of these objects has a function by the same name, and, each of
these functions returns a graphics handle pointing to an object of the
corresponding type.  In addition there are several functions which
operate on properties of the graphics objects and which also return
handles: the functions ‘plot’ and ‘plot3’ return a handle pointing to an
object of type line, the function ‘subplot’ returns a handle pointing to
an object of type axes, the function ‘fill’ returns a handle pointing to
an object of type patch, the functions ‘area’, ‘bar’, ‘barh’, ‘contour’,
‘contourf’, ‘contour3’, ‘surf’, ‘mesh’, ‘surfc’, ‘meshc’, ‘errorbar’,
‘quiver’, ‘quiver3’, ‘scatter’, ‘scatter3’, ‘stair’, ‘stem’, ‘stem3’
each return a handle to a complex data structure as documented in *note
Data Sources: 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’ objects are ‘line’, ‘text’, ‘patch’, ‘surface’,
‘image’, and ‘light’ objects.

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

   The ‘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.

     Programming Note: There is no support in Octave versions 6.X.X for
     OBJ to be an instance of a class (i.e., a classdef object).  This
     functionality has already been added on the development branch
     which will become Octave 7.1.0.

     See also: *note get: XREFget, *note set: XREFset, *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’ 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::
* 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]’

‘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"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     ‘uicontextmenu’ is unused.

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

‘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"

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

‘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.):

‘activepositionproperty’: {"outerposition"} | "position"
     Specify which of "position" or "outerposition" properties takes
     precedence when axes annotations extent changes.  *Note
     position property: XREFaxesposition, and *note
     outerposition property: XREFaxesposition.

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

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

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

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

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

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

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

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

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

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

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

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

‘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"

‘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"

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

‘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"

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

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

‘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"} | "oblique"
     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"

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

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

‘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"

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

‘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: Surface 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.

‘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"

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

‘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: Surface Properties,  Next: Light Properties,  Prev: Patch Properties,  Up: Graphics Object Properties

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

‘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"

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

‘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.10 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.

‘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"

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

‘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.11 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.

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

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

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

‘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.12 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.

‘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"} | "oblique"
     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"

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

‘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.13 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.

‘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"

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

‘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.14 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.

‘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"} | "oblique"
     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"

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

‘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.15 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.

‘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"} | "oblique"
     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"

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

‘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.16 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"

‘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"} | "oblique"
     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"

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

‘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.17 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.

‘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"

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

‘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.18 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.

‘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"

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

‘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.19 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.

‘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"

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

‘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 as RGB triplets with values ranging from zero to
one, or by name.  Recognized color names include "blue", "black",
"cyan", "green", "magenta", "red", "white", and "yellow".


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.  Details on obtaining a list of valid application data
     properties can be found in *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.


File: octave.info,  Node: Object Groups,  Next: Transform Groups,  Prev: Application-defined Data,  Up: Advanced Plotting

15.4.6 Object Groups
--------------------

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

 -- : hggroup ()
 -- : hggroup (HAX)
 -- : hggroup (..., PROPERTY, VALUE, ...)
 -- : H = hggroup (...)
     Create handle graphics group object with axes parent HAX.

     If no parent is specified, the group is created in the current
     axes.

     Multiple property/value pairs may be specified for the hggroup, but
     they must appear in pairs.  The full list of properties is
     documented at *note Axes Properties::.

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

     Programming Note: An hggroup is a way to group base graphics
     objects such as line objects or patch objects into a single unit
     which can react appropriately.  For example, the individual lines
     of a contour plot are collected into a single hggroup so that they
     can be made visible/invisible with a single command, ‘set
     (hg_handle, "visible", "off")’.

     See also: *note addproperty: XREFaddproperty, *note addlistener:
     XREFaddlistener.

   For example a simple use of a ‘hggroup’ might be

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

which groups the two plots into a single object and controls their
visibility directly.  The default properties of an ‘hggroup’ are the
same as the set of common properties for the other graphics objects.
Additional properties can be added with the ‘addproperty’ function.

 -- : addproperty (NAME, H, TYPE)
 -- : addproperty (NAME, H, TYPE, ARG, ...)
     Create a new property named NAME in graphics object H.

     TYPE determines the type of the property to create.  ARGS usually
     contains the default value of the property, but additional
     arguments might be given, depending on the type of the property.

     The supported property types are:

     ‘string’
          A string property.  ARG contains the default string value.

     ‘any’
          An un-typed property.  This kind of property can hold any
          octave value.  ARGS contains the default value.

     ‘radio’
          A string property with a limited set of accepted values.  The
          first argument must be a string with all accepted values
          separated by a vertical bar (’|’).  The default value can be
          marked by enclosing it with a ’{’ ’}’ pair.  The default value
          may also be given as an optional second string argument.

     ‘boolean’
          A boolean property.  This property type is equivalent to a
          radio property with "on|off" as accepted values.  ARG contains
          the default property value.

     ‘double’
          A scalar double property.  ARG contains the default value.

     ‘handle’
          A handle property.  This kind of property holds the handle of
          a graphics object.  ARG contains the default handle value.
          When no default value is given, the property is initialized to
          the empty matrix.

     ‘data’
          A data (matrix) property.  ARG contains the default data
          value.  When no default value is given, the data is
          initialized to the empty matrix.

     ‘color’
          A color property.  ARG contains the default color value.  When
          no default color is given, the property is set to black.  An
          optional second string argument may be given to specify an
          additional set of accepted string values (like a radio
          property).

     TYPE may also be the concatenation of a core object type and a
     valid property name for that object type.  The property created
     then has the same characteristics as the referenced property (type,
     possible values, hidden state...).  This allows one to clone an
     existing property into the graphics object H.

     Examples:

          addproperty ("my_property", gcf, "string", "a string value");
          addproperty ("my_radio", gcf, "radio", "val_1|val_2|{val_3}");
          addproperty ("my_style", gcf, "linelinestyle", "--");

     See also: *note addlistener: XREFaddlistener, *note hggroup:
     XREFhggroup.

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

 -- : addlistener (H, PROP, FCN)
     Register FCN as listener for the property PROP of the graphics
     object H.

     Property listeners are executed (in order of registration) when the
     property is set.  The new value is already available when the
     listeners are executed.

     PROP must be a string naming a valid property in H.

     FCN can be a function handle, a string or a cell array whose first
     element is a function handle.  If FCN is a function handle, the
     corresponding function should accept at least 2 arguments, that
     will be set to the object handle and the empty matrix respectively.
     If FCN is a string, it must be any valid octave expression.  If FCN
     is a cell array, the first element must be a function handle with
     the same signature as described above.  The next elements of the
     cell array are passed as additional arguments to the function.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          addlistener (gcf, "position", {@my_listener, "my string"})

     See also: *note dellistener: XREFdellistener, *note addproperty:
     XREFaddproperty, *note hggroup: XREFhggroup.

 -- : dellistener (H, PROP, FCN)
     Remove the registration of FCN as a listener for the property PROP
     of the graphics object H.

     The function FCN must be the same variable (not just the same
     value), as was passed to the original call to ‘addlistener’.

     If FCN is not defined then all listener functions of PROP are
     removed.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          c = {@my_listener, "my string"};
          addlistener (gcf, "position", c);
          dellistener (gcf, "position", c);

     See also: *note addlistener: XREFaddlistener.

   An example of the use of these two functions might be

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

     function update_props (h, d)
       set (get (h, "children"), "linestyle", get (h, "linestyle"));
     endfunction

that adds a ‘linestyle’ property to the ‘hggroup’ and propagating any
changes its value to the children of the group.  The ‘linkprop’ function
can be used to simplify the above to be

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

 -- : HLINK = linkprop (H, "PROP")
 -- : HLINK = linkprop (H, {"PROP1", "PROP2", ...})
     Link graphic object properties, such that a change in one is
     propagated to the others.

     The input H is a vector of graphic handles to link.

     PROP may be a string when linking a single property, or a cell
     array of strings for multiple properties.  During the linking
     process all properties in PROP will initially be set to the values
     that exist on the first object in the list H.

     The function returns HLINK which is a special object describing the
     link.  As long as the reference HLINK exists, the link between
     graphic objects will be active.  This means that HLINK must be
     preserved in a workspace variable, a global variable, or otherwise
     stored using a function such as ‘setappdata’ or ‘guidata’.  To
     unlink properties, execute ‘clear HLINK’.

     An example of the use of ‘linkprop’ is

          x = 0:0.1:10;
          subplot (1,2,1);
          h1 = plot (x, sin (x));
          subplot (1,2,2);
          h2 = plot (x, cos (x));
          hlink = linkprop ([h1, h2], {"color","linestyle"});
          set (h1, "color", "green");
          set (h2, "linestyle", "--");

     See also: *note linkaxes: XREFlinkaxes, *note addlistener:
     XREFaddlistener.

 -- : linkaxes (HAX)
 -- : linkaxes (HAX, OPTSTR)
     Link the axis limits of 2-D plots such that a change in one is
     propagated to the others.

     The axes handles to be linked are passed as the first argument HAX.

     The optional second argument is a string which defines which axis
     limits will be linked.  The possible values for OPTSTR are:

     "x"
          Link x-axes

     "y"
          Link y-axes

     "xy" (default)
          Link both axes

     "off"
          Turn off linking

     If unspecified the default is to link both X and Y axes.

     When linking, the limits from the first axes in HAX are applied to
     the other axes in the list.  Subsequent changes to any one of the
     axes will be propagated to the others.

     See also: *note linkprop: XREFlinkprop, *note addproperty:
     XREFaddproperty.

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

   • group together multiple graphics objects,

   • create linked properties between different graphics objects, and

   • to hide the nominal user data, from the actual data of the objects.

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

     h = stem (1:4)
     get (h, "xdata")
     ⇒ [  1   2   3   4]'
     get (get (h, "children")(1), "xdata")
     ⇒ [  1   1 NaN   2   2 NaN   3   3 NaN   4   4 NaN]'

shows the difference between the ‘xdata’ of the ‘hggroup’ of a stem
series object and the underlying line.

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

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

* Menu:

* Data Sources in Object Groups::
* Area Series::
* Bar Series::
* Contour Groups::
* Error Bar Series::
* Line Series::
* Quiver Group::
* Scatter Group::
* Stair Group::
* Stem Series::
* Surface Group::


File: octave.info,  Node: Data Sources in Object Groups,  Next: Area Series,  Up: Object Groups

15.4.6.1 Data Sources in Object Groups
......................................

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

 -- : refreshdata ()
 -- : refreshdata (H)
 -- : refreshdata (H, WORKSPACE)
     Evaluate any ‘datasource’ properties of the current figure and
     update the plot if the corresponding data has changed.

     If the first argument H is a list of graphic handles, then operate
     on these objects rather than the current figure returned by ‘gcf’.

     The optional second argument WORKSPACE can take the following
     values:

     "base"
          Evaluate the datasource properties in the base workspace.
          (default).

     "caller"
          Evaluate the datasource properties in the workspace of the
          function that called ‘refreshdata’.

     An example of the use of ‘refreshdata’ is:

          x = 0:0.1:10;
          y = sin (x);
          plot (x, y, "ydatasource", "y");
          for i = 1 : 100
            pause (0.1);
            y = sin (x + 0.1*i);
            refreshdata ();
          endfor


File: octave.info,  Node: Area Series,  Next: Bar Series,  Prev: Data Sources in Object Groups,  Up: Object Groups

15.4.6.2 Area Series
....................

Area series objects are created by the ‘area’ function.  Each of the
‘hggroup’ elements contains a single patch object.  The properties of
the area series are

‘basevalue’
     The value where the base of the area plot is drawn.

‘linewidth’
‘linestyle’
     The line width and style of the edge of the patch objects making up
     the areas.  *Note Line Styles::.

‘edgecolor’
‘facecolor’
     The line and fill color of the patch objects making up the areas.
     *Note Colors::.

‘xdata’
‘ydata’
     The x and y coordinates of the original columns of the data passed
     to ‘area’ prior to the cumulative summation used in the ‘area’
     function.

‘xdatasource’
‘ydatasource’
     Data source variables.


File: octave.info,  Node: Bar Series,  Next: Contour Groups,  Prev: Area Series,  Up: Object Groups

15.4.6.3 Bar Series
...................

Bar series objects are created by the ‘bar’ or ‘barh’ functions.  Each
‘hggroup’ element contains a single patch object.  The properties of the
bar series are

‘showbaseline’
‘baseline’
‘basevalue’
     The property ‘showbaseline’ flags whether the baseline of the bar
     series is displayed (default is "on").  The handle of the graphics
     object representing the baseline is given by the ‘baseline’
     property and the y-value of the baseline by the ‘basevalue’
     property.

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

‘barwidth’
‘barlayout’
‘horizontal’
     The property ‘barwidth’ is the width of the bar corresponding to
     the WIDTH variable passed to ‘bar’ or BARH.  Whether the bar series
     is "grouped" or "stacked" is determined by the ‘barlayout’ property
     and whether the bars are horizontal or vertical by the ‘horizontal’
     property.

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

‘linewidth’
‘linestyle’
     The line width and style of the edge of the patch objects making up
     the bars.  *Note Line Styles::.

‘edgecolor’
‘facecolor’
     The line and fill color of the patch objects making up the bars.
     *Note Colors::.

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

‘ydata’
     The y value of the bars in the ‘hggroup’.

‘xdatasource’
‘ydatasource’
     Data source variables.


File: octave.info,  Node: Contour Groups,  Next: Error Bar Series,  Prev: Bar Series,  Up: Object Groups

15.4.6.4 Contour Groups
.......................

Contour group objects are created by the ‘contour’, ‘contourf’, and
‘contour3’ functions.  They are also one of the handles returned by the
‘surfc’ and ‘meshc’ functions.  The properties of the contour group are

‘contourmatrix’
     A read only property that contains the data return by ‘contourc’
     used to create the contours of the plot.

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

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

‘levellistmode’
‘levellist’
‘levelstepmode’
‘levelstep’
     If ‘levellistmode’ is "manual", then the levels at which to plot
     the contours is determined by ‘levellist’.  If ‘levellistmode’ is
     set to "auto", then the distance between contours is determined by
     ‘levelstep’.  If both ‘levellistmode’ and ‘levelstepmode’ are set
     to "auto", then there are assumed to be 10 equal spaced contours.

‘textlistmode’
‘textlist’
‘textstepmode’
‘textstep’
     If ‘textlistmode’ is "manual", then the labeled contours is
     determined by ‘textlist’.  If ‘textlistmode’ is set to "auto", then
     the distance between labeled contours is determined by ‘textstep’.
     If both ‘textlistmode’ and ‘textstepmode’ are set to "auto", then
     there are assumed to be 10 equal spaced labeled contours.

‘showtext’
     Flag whether the contour labels are shown or not.

‘labelspacing’
     The distance between labels on a single contour in points.

‘linewidth’

‘linestyle’

‘linecolor’
     The properties of the contour lines.  The properties ‘linewidth’
     and ‘linestyle’ are similar to the corresponding properties for
     lines.  The property ‘linecolor’ is a color property (*note
     Colors::), that can also have the values of "none" or "auto".  If
     ‘linecolor’ is "none", then no contour line is drawn.  If
     ‘linecolor’ is "auto" then the line color is determined by the
     colormap.

‘xdata’
‘ydata’
‘zdata’
     The original x, y, and z data of the contour lines.

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Error Bar Series,  Next: Line Series,  Prev: Contour Groups,  Up: Object Groups

15.4.6.5 Error Bar Series
.........................

Error bar series are created by the ‘errorbar’ function.  Each ‘hggroup’
element contains two line objects representing the data and the
errorbars separately.  The properties of the error bar series are

‘color’
     The RGB color or color name of the line objects of the error bars.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the error bars.
     *Note Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the error bars.  *Note
     Colors::.

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

‘xdatasource’
‘ydatasource’
‘ldatasource’
‘udatasource’
‘xldatasource’
‘xudatasource’
     Data source variables.


File: octave.info,  Node: Line Series,  Next: Quiver Group,  Prev: Error Bar Series,  Up: Object Groups

15.4.6.6 Line Series
....................

Line series objects are created by the ‘plot’ and ‘plot3’ functions and
are of the type ‘line’.  The properties of the line series with the
ability to add data sources.

‘color’
     The RGB color or color name of the line objects.  *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects.  *Note Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers.  *Note Colors::.

‘xdata’
‘ydata’
‘zdata’
     The original x, y and z data.

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Quiver Group,  Next: Scatter Group,  Prev: Line Series,  Up: Object Groups

15.4.6.7 Quiver Group
.....................

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

‘autoscale’
‘autoscalefactor’
     Flag whether the length of the arrows is scaled or defined directly
     from the U, V and W data.  If the arrow length is flagged as being
     scaled by the ‘autoscale’ property, then the length of the
     autoscaled arrow is controlled by the ‘autoscalefactor’.

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

‘showarrowhead’
     Flag whether the arrow heads are displayed in the quiver plot.

‘color’
     The RGB color or color name of the line objects of the quiver.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the quiver.  *Note
     Line Styles::.

‘marker’
‘markerfacecolor’
‘markersize’
     The line and fill color of the marker objects at the original of
     the arrows.  *Note Colors::.

‘xdata’
‘ydata’
‘zdata’
     The origins of the values of the vector field.

‘udata’
‘vdata’
‘wdata’
     The values of the vector field to plot.

‘xdatasource’
‘ydatasource’
‘zdatasource’
‘udatasource’
‘vdatasource’
‘wdatasource’
     Data source variables.


File: octave.info,  Node: Scatter Group,  Next: Stair Group,  Prev: Quiver Group,  Up: Object Groups

15.4.6.8 Scatter Group
......................

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

‘linewidth’
     The line width of the line objects of the points.  *Note Line
     Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
     The line and fill color of the markers of the points.  *Note
     Colors::.

‘xdata’
‘ydata’
‘zdata’
     The original x, y and z data of the stems.

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

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

‘xdatasource’
‘ydatasource’
‘zdatasource’
‘cdatasource’
‘sizedatasource’
     Data source variables.


File: octave.info,  Node: Stair Group,  Next: Stem Series,  Prev: Scatter Group,  Up: Object Groups

15.4.6.9 Stair Group
....................

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

‘color’
     The RGB color or color name of the line objects of the stairs.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the stairs.  *Note
     Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the stairs.  *Note
     Colors::.

‘xdata’
‘ydata’
     The original x and y data of the stairs.

‘xdatasource’
‘ydatasource’
     Data source variables.


File: octave.info,  Node: Stem Series,  Next: Surface Group,  Prev: Stair Group,  Up: Object Groups

15.4.6.10 Stem Series
.....................

Stem series objects are created by the ‘stem’ or ‘stem3’ functions.
Each ‘hggroup’ element contains a single line object as a child
representing the stems.  The properties of the stem series are

‘showbaseline’
‘baseline’
‘basevalue’
     The property ‘showbaseline’ flags whether the baseline of the stem
     series is displayed (default is "on").  The handle of the graphics
     object representing the baseline is given by the ‘baseline’
     property and the y-value (or z-value for ‘stem3’) of the baseline
     by the ‘basevalue’ property.

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

‘color’
     The RGB color or color name of the line objects of the stems.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the stems.  *Note
     Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the stems.  *Note
     Colors::.

‘xdata’
‘ydata’
‘zdata’
     The original x, y and z data of the stems.

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Surface Group,  Prev: Stem Series,  Up: Object Groups

15.4.6.11 Surface Group
.......................

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

   The properties of the surface group are

‘edgecolor’

‘facecolor’
     The RGB color or color name of the edges or faces of the surface.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the lines on the surface.  *Note Line
     Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the surface.  *Note
     Colors::.

‘xdata’
‘ydata’
‘zdata’
‘cdata’
     The original x, y, z and c data.

‘xdatasource’
‘ydatasource’
‘zdatasource’
‘cdatasource’
     Data source variables.


File: octave.info,  Node: Transform Groups,  Next: Graphics Toolkits,  Prev: Object Groups,  Up: Advanced Plotting

15.4.7 Transform Groups
-----------------------

 -- : H = hgtransform ()
 -- : H = hgtransform (PROPERTY, VALUE, ...)
 -- : H = hgtransform (HAX, ...)

     Create a graphics transform object.

     FIXME: Need to write documentation.  FIXME: Add <makehgtform> to
     seealso list when it is implemented.

     See also: *note hggroup: XREFhggroup.


File: octave.info,  Node: Graphics Toolkits,  Prev: Transform Groups,  Up: Advanced Plotting

15.4.8 Graphics Toolkits
------------------------

 -- : NAME = graphics_toolkit ()
 -- : NAME = graphics_toolkit (HLIST)
 -- : graphics_toolkit (NAME)
 -- : graphics_toolkit (HLIST, NAME)
     Query or set the default graphics toolkit which is assigned to new
     figures.

     With no inputs, return the current default graphics toolkit.  If
     the input is a list of figure graphic handles, HLIST, then return
     the name of the graphics toolkit in use for each figure.

     When called with a single input NAME set the default graphics
     toolkit to NAME.  If the toolkit is not already loaded, it is
     initialized by calling the function ‘__init_NAME__’.  If the first
     input is a list of figure handles, HLIST, then the graphics toolkit
     is set to NAME for these figures only.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

 -- : available_graphics_toolkits ()
     Return a cell array of registered graphics toolkits.

     See also: *note graphics_toolkit: XREFgraphics_toolkit, *note
     register_graphics_toolkit: XREFregister_graphics_toolkit.

 -- : loaded_graphics_toolkits ()
     Return a cell array of the currently loaded graphics toolkits.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

 -- : register_graphics_toolkit (TOOLKIT)
     List TOOLKIT as an available graphics toolkit.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

* Menu:

* Customizing Toolkit Behavior::
* Hardware vs. Software Rendering::
* Precision issues::


File: octave.info,  Node: Customizing Toolkit Behavior,  Next: Hardware vs. Software Rendering,  Up: Graphics Toolkits

15.4.8.1 Customizing Toolkit Behavior
.....................................

The specific behavior of the backend toolkit may be modified using the
following utility functions.  Note: Not all functions apply to every
graphics toolkit.

 -- : [PROG, ARGS] = gnuplot_binary ()
 -- : [OLD_PROG, OLD_ARGS] = gnuplot_binary (NEW_PROG)
 -- : [OLD_PROG, OLD_ARGS] = gnuplot_binary (NEW_PROG, ARG1, ...)
     Query or set the name of the program invoked by the plot command
     when the graphics toolkit is set to "gnuplot".

     Additional arguments to pass to the external plotting program may
     also be given.  The default value is "gnuplot" with no additional
     arguments.  *Note Installation::.

     See also: *note graphics_toolkit: XREFgraphics_toolkit.

   In addition, the gnuplot program usually provides a number of
different interfaces, known as terminals.  Octave normally chooses a
default terminal, but you can override this with the environment
variable ‘GNUTERM’.  This variable may be set in the shell before
starting Octave or from within Octave before plotting for the first
time.  For example:

     setenv ("GNUTERM", "wxt")
     graphics_toolkit ("gnuplot")
     plot (1:10)


File: octave.info,  Node: Hardware vs. Software Rendering,  Next: Precision issues,  Prev: Customizing Toolkit Behavior,  Up: Graphics Toolkits

15.4.8.2 Hardware vs. Software Rendering
........................................

On Windows platforms, Octave uses software rendering for the OpenGL
graphics toolkits ("qt" and "fltk") by default.  This is done to avoid
rendering and printing issues due to imperfect OpenGL driver
implementations for diverse graphic cards from different vendors.  As a
down-side, software rendering might be considerably slower than hardware
accelerated rendering.  To permanently switch back to hardware
accelerated rendering with your graphic card drivers, rename the
following file while Octave is closed:

   ‘OCTAVE-HOME\bin\opengl32.dll’
where OCTAVE-HOME is the directory in which Octave is installed (the
default is ‘C:\Octave\Octave-VERSION’).


File: octave.info,  Node: Precision issues,  Prev: Hardware vs. Software Rendering,  Up: Graphics Toolkits

15.4.8.3 Precision issues
.........................

The OpenGL graphics toolkits ("qt" and "fltk") use single precision for
rendering.  This limitation in particular applies to plots of time
series against serial dates as used by the ‘datenum’, ‘datestr’,
‘datestruct’, and ‘datetick’ functions.

   Serial dates encode timestamps as days elapsed since the year zero
with hours, minutes, seconds as the fractional part.  On December 31st
1999, the serial date representation was 730485.  A double precision
variable with this integer part allows for a resolution in its
fractional part of 1.2e-10, representing about 5 microseconds.  But with
single precision, the resolution is reduced to about 0.06, representing
45 minutes.  Any attempt to plot timestamped data with finer granularity
will result in a distorted graph.

   As a workaround, it is possible to use the "gnuplot" graphics toolkit
or subtract 2000 years—i.e., ‘datenum (2000, 0, 0)’ or 730485—from the
time values.  Due to the fact that the calendar structure repeats every
2000 years, the relation between year, month, day of month and day of
week will stay unchanged and the ticks and ticklabels produced by the
‘datetick’ function will still be correct.  Only years will lack the
millennium digit.  Thus, "2020" will be printed as "20".  For example:

     # timestamps of 24 hours in one minute steps
     t = datenum (2020, 1, 1):(1/1440):datenum (2020, 1, 2);

     # some example time series data
     x = -cos (2*pi*t) + rand (size (t)) / 10;

     subplot (1, 2, 1);
     plot (t, x);
     datetick ("x");
     xlabel ("serial date");
     title ("problem");

     subplot (1, 2, 2);
     plot (t - 730485, x);
     datetick ("x");
     xlabel ("2000 years off");
     title ("workaround");

   Similarly, other data can be translated or re-scaled to work around
this issue.


File: octave.info,  Node: Matrix Manipulation,  Next: Arithmetic,  Prev: Plotting,  Up: Top

16 Matrix Manipulation
**********************

There are a number of functions available for checking to see if the
elements of a matrix meet some condition, and for rearranging the
elements of a matrix.  For example, Octave can easily tell you if all
the elements of a matrix are finite, or are less than some specified
value.  Octave can also rotate the elements, extract the upper- or
lower-triangular parts, or sort the columns of a matrix.

* Menu:

* Finding Elements and Checking Conditions::
* Rearranging Matrices::
* Special Utility Matrices::
* Famous Matrices::


File: octave.info,  Node: Finding Elements and Checking Conditions,  Next: Rearranging Matrices,  Up: Matrix Manipulation

16.1 Finding Elements and Checking Conditions
=============================================

The functions ‘any’ and ‘all’ are useful for determining whether any or
all of the elements of a matrix satisfy some condition.  The ‘find’
function is also useful in determining which elements of a matrix meet a
specified condition.

 -- : any (X)
 -- : any (X, DIM)
     For a vector argument, return true (logical 1) if any element of
     the vector is nonzero.

     For a matrix argument, return a row vector of logical ones and
     zeros with each element indicating whether any of the elements of
     the corresponding column of the matrix are nonzero.  For example:

          any (eye (2, 4))
           ⇒ [ 1, 1, 0, 0 ]

     If the optional argument DIM is supplied, work along dimension DIM.
     For example:

          any (eye (2, 4), 2)
           ⇒ [ 1; 1 ]

     See also: *note all: XREFall.

 -- : all (X)
 -- : all (X, DIM)
     For a vector argument, return true (logical 1) if all elements of
     the vector are nonzero.

     For a matrix argument, return a row vector of logical ones and
     zeros with each element indicating whether all of the elements of
     the corresponding column of the matrix are nonzero.  For example:

          all ([2, 3; 1, 0])
              ⇒ [ 1, 0 ]

     If the optional argument DIM is supplied, work along dimension DIM.

     See also: *note any: XREFany.

   Since the comparison operators (*note Comparison Ops::) return
matrices of ones and zeros, it is easy to test a matrix for many things,
not just whether the elements are nonzero.  For example,

     all (all (rand (5) < 0.9))
          ⇒ 0

tests a random 5 by 5 matrix to see if all of its elements are less than
0.9.

   Note that in conditional contexts (like the test clause of ‘if’ and
‘while’ statements) Octave treats the test as if you had typed ‘all (all
(condition))’.

 -- : Z = xor (X, Y)
 -- : Z = xor (X1, X2, ...)
     Return the “exclusive or” of X and Y.

     For boolean expressions X and Y, ‘xor (X, Y)’ is true if and only
     if one of X or Y is true.  Otherwise, if X and Y are both true or
     both false, ‘xor’ returns false.

     The truth table for the xor operation is

                                      X  Y    Z
                                      -  -    -
                                      0  0    0
                                      1  0    1
                                      0  1    1
                                      1  1    0

     If more than two arguments are given the xor operation is applied
     cumulatively from left to right:

          (...((x1 XOR x2) XOR x3) XOR ...)

     See also: *note and: XREFand, *note or: XREFor, *note not: XREFnot.

 -- : diff (X)
 -- : diff (X, K)
 -- : diff (X, K, DIM)
     If X is a vector of length n, ‘diff (X)’ is the vector of first
     differences X(2) - X(1), ..., X(n) - X(n-1).

     If X is a matrix, ‘diff (X)’ is the matrix of column differences
     along the first non-singleton dimension.

     The second argument is optional.  If supplied, ‘diff (X, K)’, where
     K is a non-negative integer, returns the K-th differences.  It is
     possible that K is larger than the first non-singleton dimension of
     the matrix.  In this case, ‘diff’ continues to take the differences
     along the next non-singleton dimension.

     The dimension along which to take the difference can be explicitly
     stated with the optional variable DIM.  In this case the K-th order
     differences are calculated along this dimension.  In the case where
     K exceeds ‘size (X, DIM)’ an empty matrix is returned.

     See also: *note sort: XREFsort, *note merge: XREFmerge.

 -- : isinf (X)
     Return a logical array which is true where the elements of X are
     infinite and false where they are not.

     For example:

          isinf ([13, Inf, NA, NaN])
                ⇒ [ 0, 1, 0, 0 ]

     See also: *note isfinite: XREFisfinite, *note isnan: XREFisnan,
     *note isna: XREFisna.

 -- : isnan (X)
     Return a logical array which is true where the elements of X are
     NaN values and false where they are not.

     NA values are also considered NaN values.  For example:

          isnan ([13, Inf, NA, NaN])
                ⇒ [ 0, 0, 1, 1 ]

     See also: *note isna: XREFisna, *note isinf: XREFisinf, *note
     isfinite: XREFisfinite.

 -- : isfinite (X)
     Return a logical array which is true where the elements of X are
     finite values and false where they are not.

     For example:

          isfinite ([13, Inf, NA, NaN])
               ⇒ [ 1, 0, 0, 0 ]

     See also: *note isinf: XREFisinf, *note isnan: XREFisnan, *note
     isna: XREFisna.

 -- : [ERR, YI, ...] = common_size (XI, ...)
     Determine if all input arguments are either scalar or of common
     size.

     If true, ERR is zero, and YI is a matrix of the common size with
     all entries equal to XI if this is a scalar or XI otherwise.  If
     the inputs cannot be brought to a common size, ERR is 1, and YI is
     XI.  For example:

          [err, a, b] = common_size ([1 2; 3 4], 5)
               ⇒ err = 0
               ⇒ a = [ 1, 2; 3, 4 ]
               ⇒ b = [ 5, 5; 5, 5 ]

     This is useful for implementing functions where arguments can
     either be scalars or of common size.

     See also: *note size: XREFsize, *note size_equal: XREFsize_equal,
     *note numel: XREFnumel, *note ndims: XREFndims.

 -- : IDX = find (X)
 -- : IDX = find (X, N)
 -- : IDX = find (X, N, DIRECTION)
 -- : [i, j] = find (...)
 -- : [i, j, v] = find (...)
     Return a vector of indices of nonzero elements of a matrix, as a
     row if X is a row vector or as a column otherwise.

     To obtain a single index for each matrix element, Octave pretends
     that the columns of a matrix form one long vector (like Fortran
     arrays are stored).  For example:

          find (eye (2))
            ⇒ [ 1; 4 ]

     If two inputs are given, N indicates the maximum number of elements
     to find from the beginning of the matrix or vector.

     If three inputs are given, DIRECTION should be one of "first" or
     "last", requesting only the first or last N indices, respectively.
     However, the indices are always returned in ascending order.

     If two outputs are requested, ‘find’ returns the row and column
     indices of nonzero elements of a matrix.  For example:

          [i, j] = find (2 * eye (2))
              ⇒ i = [ 1; 2 ]
              ⇒ j = [ 1; 2 ]

     If three outputs are requested, ‘find’ also returns a vector
     containing the nonzero values.  For example:

          [i, j, v] = find (3 * eye (2))
                 ⇒ i = [ 1; 2 ]
                 ⇒ j = [ 1; 2 ]
                 ⇒ v = [ 3; 3 ]

     Note that this function is particularly useful for sparse matrices,
     as it extracts the nonzero elements as vectors, which can then be
     used to create the original matrix.  For example:

          sz = size (a);
          [i, j, v] = find (a);
          b = sparse (i, j, v, sz(1), sz(2));

     See also: *note nonzeros: XREFnonzeros.

 -- : IDX = lookup (TABLE, Y)
 -- : IDX = lookup (TABLE, Y, OPT)
     Lookup values in a *sorted* table.

     This function is usually used as a prelude to interpolation.

     If table is increasing, of length N and ‘idx = lookup (table, y)’,
     then ‘table(idx(i)) <= y(i) < table(idx(i+1))’ for all ‘y(i)’
     within the table.  If ‘y(i) < table(1)’ then ‘idx(i)’ is 0.  If
     ‘y(i) >= table(end)’ or ‘isnan (y(i))’ then ‘idx(i)’ is N.

     If the table is decreasing, then the tests are reversed.  For
     non-strictly monotonic tables, empty intervals are always skipped.
     The result is undefined if TABLE is not monotonic, or if TABLE
     contains a NaN.

     The complexity of the lookup is O(M*log(N)) where M is the size of
     Y.  In the special case when Y is also sorted, the complexity is
     O(min (M*log(N), M+N)).

     TABLE and Y can also be cell arrays of strings (or Y can be a
     single string).  In this case, string lookup is performed using
     lexicographical comparison.

     If OPTS is specified, it must be a string with letters indicating
     additional options.

     ‘m’
          Match.  ‘table(idx(i)) == y(i)’ if ‘y(i)’ occurs in table;
          otherwise, ‘idx(i)’ is zero.

     ‘b’
          Boolean.  ‘idx(i)’ is a logical 1 or 0, indicating whether
          ‘y(i)’ is contained in table or not.

     ‘l’
          Left.  For numeric lookups the leftmost subinterval shall be
          extended to minus infinity (i.e., all indices at least 1).

     ‘r’
          Right.  For numeric lookups the rightmost subinterval shall be
          extended to infinity (i.e., all indices at most N-1).

     *Note*: If TABLE is not sorted the results from ‘lookup’ will be
     unpredictable.

   If you wish to check if a variable exists at all, instead of
properties its elements may have, consult *note Status of Variables::.

