Next: Use of the `interpreter` Property, Previous: Multiple Plot Windows, Up: High-Level Plotting [Contents][Index]

#### 15.2.6 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.

Built-in Function: drawnow ()
Built-in Function: drawnow ("expose")
Built-in Function: drawnow (term, file, mono, 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.

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

Function File: refresh ()
Function File: 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: drawnow.

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, use 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 ()
Function File: newplot (hfig)
Function File: newplot (hax)
Function File: 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 axis 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`.

  Axis 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 axis properties unmodified. This typically clears a plot, but preserves special settings such as log scaling for axes. This is equivalent to `cla`.
  `"replace"` (default) | Delete all child objects of the axis and reset all axis 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 axis.

Command: hold
Command: hold on
Command: hold off
Command: hold all
Function File: 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.

  `hold all`

    Retain plot line color, line style, data, and settings so that subsequent plot commands are displayed on a single graph with the next line color and style.

  `hold off`

    Restore default graphics settings which clear the graph and reset axis 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 axis rather than the current axes returned by `gca`.

  To query the current hold state use the `ishold` function.

  See also: ishold, cla, clf, newplot.

Command: ishold
Function File: ishold (hax)
Function File: 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: hold, newplot.

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.

Command: clf
Command: clf reset
Function File: clf (hfig)
Function File: clf (hfig, "reset")
Function File: 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: cla, close, delete, reset.

Command: cla
Command: cla reset
Function File: cla (hax)
Function File: cla (hax, "reset")

  Clear the current axes.

  `cla` operates by deleting child graphic 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 axis 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 axis rather than the current axes returned by `gca`.

  See also: clf, delete, reset.

Command: shg

  Show the graph window.

  Currently, this is the same as executing `drawnow`.

  See also: drawnow, figure.

Function File: delete (file)
Function File: delete (handle)

  Delete the named file or graphics handle.

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

  See also: clf, cla, unlink.

Command: close
Command: close (h)
Command: close all
Command: close all hidden

  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.

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

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

  Implementation Note: `close` operates by calling the function specified by the `"closerequestfcn"` property for each 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: closereq, delete.

Function File: 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: close, delete.

Next: Use of the `interpreter` Property, Previous: Multiple Plot Windows, Up: High-Level Plotting [Contents][Index]