newplot (MATLAB Function Reference)

Determine where to draw graphics objects

newplot
h = newplot

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.

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 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 nextplot 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
`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`	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`	Removes all child objects (regardless of the setting of the `HandleVisibility` property) and resets Axes properties to their defaults, except `Position` and `Units` This clears and resets the current Axes like the `cla reset` command.