MATLAB Function Reference Previous page   Next Page
newplot

Determine where to draw graphics objects

Syntax

Description

newplot prepares a figure and axes for subsequent graphics commands.

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

h = newplot(hsave) prepares and returns an axes, but does not delete any objects whose handles appear in hsave. If hsave is specified, the figure and axes containing hsave are prepared for plotting instead of the current axes of the current figure. If hsave is empty, newplot behaves as if it were called without any inputs.

Remarks

Use newplot at the beginning of high-level graphics M-files 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:

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.

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
Draw into the current axes, retaining all graphics objects already present.
replacechildren
Remove all child objects whose HandleVisibility property is set to on, but do not reset axes properties. This clears the current axes like the cla command.
replace
Remove all child objects (regardless of the setting of the HandleVisibility property) and reset axes properties to their defaults, except Position and Units.
This clears and resets the current axes like the cla reset command.

See Also

axes, cla, clf, figure, hold, ishold, reset

The NextPlot property for figure and axes graphics objects

Figure Windows for related functions

Controlling Graphics Output for more examples.


Previous page  ne nextpow2 Next page

© 1994-2005 The MathWorks, Inc.