#### 15.2.1 Graphics Objects

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

root figure
  The parent of all figure objects. The index for the root figure is defined to be 0.
figure
  A figure window.
axes
  An set of axes. This object is a child of a figure object and may be a parent of line, text, image, patch, or surface objects.
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.

To determine whether an object is a graphics object index or a figure index, use the functions `ishandle` and `isfigure`.

— Built-in Function: ishandle (h)

> Return true if h is a graphics handle and false otherwise.

— Function File: isfigure (h)

> Return true if h is a graphics handle that contains a figure object and false otherwise.

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.

— Function File: gcf ()

> Return the current figure handle. If a figure does not exist, create one and return its handle. The handle may then be used to examine or set properties of the figure. For example,

>               fplot (@sin, [-10, 10]);
>               fig = gcf ();
>               set (fig, "visible", "off");

> plots a sine wave, finds the handle of the current figure, and then makes that figure invisible. Setting the visible property of the figure to `"on"` will cause it to be displayed again.

> See also: get, set.

— Function File: gca ()

> Return a handle to the current axis object. If no axis object exists, create one and return its handle. The handle may then be used to examine or set properties of the axes. For example,

>               ax = gca ();
>               set (ax, "position", [0.5, 0.5, 0.5, 0.5]);

> creates an empty axes object, then changes its location and size in the figure window.

> See also: get, set.

The `get` and `set` functions may be used to examine and set properties for graphics objects. For example,

         get (0)
             => ans =
                {
                  type = root figure
                  currentfigure = [](0x0)
                  children = [](0x0)
                  visible = on
                }

returns a structure containing all the properties of the root figure. As with all functions in Octave, the structure is returned by value, so modifying it will not modify the internal root figure plot object. To do that, you must use the `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]`'. Additionally, calling set with a graphics object index as the only argument returns a structure containing the default values for all the properties for the given object type. For example,

         set (gca ())

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

— Built-in Function: get (h, p)

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

— Built-in Function: set (h, p, v, ...)

> Set the named property value or vector p to the value v for the graphics handle h.

— Function File: parent = ancestor (h, type)
— Function File: 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 is of type type, return h.

> If `"toplevel"` is given as a 3rd argument, return the highest parent in the object hierarchy that matches the condition, instead of the first (nearest) one.

> See also: get, set.

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

— Function File: axes ()
— Function File: axes (property, value, ...)
— Function File: axes (h)

> Create an axes object and return a handle to it.

— Function File: line ()
— Function File: line (x, y)
— Function File: line (x, y, z)
— Function File: line (x, y, z, property, value, ...)

> Create line object from x and y and insert in current axes object. Return a handle (or vector of handles) to the line objects created.

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

— Function File: patch ()
— Function File: patch (x, y, c)
— Function File: patch (x, y, c, opts)
— Function File: patch ('Faces', f, 'Vertices', v, ...)
— Function File: patch (..., prop, val)
— Function File: patch (h, ...)
— Function File: h = patch (...)

> Create patch object from x and y with color c and insert in the current axes object. Return handle to patch object.

> For a uniform colored patch, c can be given as an RGB vector, scalar value referring to the current colormap, or string value (for example, "r" or "red").

— Function File: surface (x, y, z, c)
— Function File: surface (x, y, z)
— Function File: surface (z, c)
— Function File: surface (z)
— Function File: surface (..., prop, val)
— Function File: surface (h, ...)
— Function File: h = surface (...)

> Plot a surface graphic object given matrices x, and y from `meshgrid` and a matrix 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 x and y are missing, they are constructed from size of the matrix z.

> Any additional properties passed are assigned the the surface..

> See also: surf, mesh, patch, line.

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

— Function File: drawnow ()

> Update and display the current graphics.

> Octave automatically calls drawnow just before printing a prompt, when `sleep` or `pause` is called, or while waiting for command-line input.

Normally, high-level plot functions like `plot` or `mesh` call `newplot` to initialize the state of the current axes so that the next plot is drawn in a blank window with default property settings. To have two plots superimposed over one another, call the `hold` function. 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.

— Function File: newplot ()

> Prepare graphics engine to produce a new plot. This function should be called at the beginning of all high-level plotting functions.

— Function File: hold args

> Tell Octave to `hold' the current data on the plot when executing subsequent plotting commands. This allows you to execute a series of plot commands and have all the lines end up on the same figure. The default is for each new plot command to clear the plot device first. For example, the command

>               hold on

> turns the hold state on. An argument of `"off"` turns the hold state off, and `hold` with no arguments toggles the current hold state.

— Function File: ishold

> Return true if the next line will be added to the current plot, or false if the plot device will be cleared before drawing the next line.

To clear the current figure, call the `clf` function. To bring it 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.

— Function File: clf ()
— Function File: clf ("reset")
— Function File: clf (hfig)
— Function File: clf (hfig, "reset")
— Function File: hfig = clf (...)

> Delete the children of the current figure with visible handles. If hfig is specified and is an figure object handle, operate on it instead of the current figure. If the optional argument `"reset"` is specified, also delete the figure's children with hidden handles.

> See also: cla, close, delete.

— Function File: shg

> Show the graph window. Currently, this is the same as executing `drawnow`.

> See also: drawnow, figure.

— Function File: delete (file)
— Function File: delete (h)

> Delete the named file or figure handle.

— Command: close
— Command: close (n)
— Command: close all
— Command: close all hidden

> Close figure window(s) by calling the function specified by the `"closerequestfcn"` property for each figure. By default, the function `closereq` is used.

> See also: closereq.

— Function File: closereq ()

> Close the current figure and delete all graphics objects associated with it.

> See also: close, delete.