newplot

Determine where to draw graphics objects

Syntax

newplot
h = newplot
h = newplot(target)


Description

newplot prepares a figure and axes for subsequent graphics commands.

h = newplot prepares a figure and axes for subsequent graphics commands and returns the current axes.

h = newplot(target) prepares the object specified by target for plotting instead of the current axes of the current figure. The target object can be a Cartesian axes, polar axes, or geographic axes object. If target is empty, newplot behaves as if it were called without any inputs.

Tips

To create a simple 2-D plot, use the plot function instead.

Use newplot at the beginning of high-level graphics code to determine which figure and axes to target for graphics output. Calling newplot can change the current figure and current axes. Basically, there are three options when you are drawing graphics in existing figures and axes:

• Add the new graphics without changing any properties or deleting any objects.

• Delete all existing objects whose handles are not hidden before drawing the new objects.

• Delete all existing objects regardless of whether or not their handles are hidden, and reset most properties to their defaults before drawing the new objects (refer to the following table for specific information).

The figure and axes NextPlot properties determine how newplot behaves. The following two tables describe this behavior with various property values.

First, newplot reads the current figure's NextPlot property and acts accordingly.

NextPlot	What Happens
new	Create a new figure and use it as the current figure.
add	Draw to the current figure without clearing any graphics objects already present.
replacechildren	Remove all child objects whose HandleVisibility property is set to on and reset figure NextPlot property to add. This clears the current figure and is equivalent to issuing the clf command.
replace	Remove all child objects (regardless of the setting of the HandleVisibility property) and reset figure properties to their defaults, except NextPlot is reset to add regardless of user-defined defaults. Position, Units, PaperPosition, and PaperUnits are not reset. This clears and resets the current figure and is equivalent to issuing the clf reset command.

After newplot establishes which figure to draw in, it reads the current axes' NextPlot property and acts accordingly.

NextPlot	Description
add	Add new plots to the existing axes. Do not delete existing plots or reset axes properties before displaying the new plot.
replacechildren	Delete existing plots before displaying the new plot. Reset the ColorOrderIndex and LineStyleOrderIndex axes properties to 1, but do not reset other axes properties. The next plot added to the axes uses the first color and line style based on the ColorOrder and LineStyleOrder properties of the axes. This value is similar to using cla before every new plot.
replace	Delete existing plots and reset all axes properties, except Position and Units, to their default values before displaying the new plot.
replaceall	Delete existing plots and reset all axes properties, except Position and Units, to their default values before displaying the new plot. This value is similar to using cla reset before every new plot. For axes with only one y-axes, the replace and replaceall values are equivalent. For axes with two y-axes, the replace value affects only the active side while the replaceall value affects both sides.

Version History

Introduced before R2006a