## Prepare Figures and Axes for Graphs

### Behavior of MATLAB Plotting Functions

MATLAB^{®} plotting functions either create a new figure and
axes if none exist, or reuse an existing figure and axes. When reusing
existing axes, MATLAB

Clears the graphics objects from the axes.

Resets most axes properties to their default values.

Calculates new axes limits based on the new data.

When a plotting function creates a graph, the function can:

Create a figure and an axes for the graph and set necessary properties for the particular graph (default behavior if no current figure exists)

Reuse an existing figure and axes, clearing and resetting axes properties as required (default behavior if a graph exists)

Add new data objects to an existing graph without resetting properties (if

`hold`

is`on`

)

The `NextPlot`

figure and axes properties control
the way that MATLAB plotting functions behave.

### How the NextPlot Properties Control Behavior

MATLAB plotting functions rely on the values of the figure
and axes `NextPlot`

properties to determine whether
to add, clear, or clear and reset the figure and axes before drawing
the new graph. Low-level object-creation functions do not check the `NextPlot`

properties.
They simply add the new graphics objects to the current figure and
axes.

This table summarizes the possible values for the `NextPlot`

properties.

NextPlot | Figure | Axes |
---|---|---|

| Creates a new figure and uses it as the current figure. | Not an option for axes. |

| Adds new graphics objects without clearing or resetting the current figure. (Default) | Adds new graphics objects without clearing or resetting the current axes. |

| Removes all axes objects whose handles are not hidden
before adding new objects. Does not reset figure properties. Equivalent
to | Removes all axes child objects whose handles are not
hidden before adding new graphics objects. Does not reset axes properties.
Equivalent to |

| Removes all axes objects and resets figure properties
to their defaults before adding new objects. Equivalent to | Removes all child objects and resets axes properties
to their defaults before adding new objects. Equivalent to |

Plotting functions call the `newplot`

function
to obtain the handle to the appropriate axes.

#### The Default Scenario

Consider the default situation where the figure `NextPlot`

property
is `add`

and the axes `NextPlot`

property
is `replace`

. When you call `newplot`

,
it:

Checks the value of the current figure's

`NextPlot`

property (which is,`add`

).Determines that MATLAB can draw into the current figure without modifying the figure. If there is no current figure,

`newplot`

creates one, but does not recheck its`NextPlot`

property.Checks the value of the current axes'

`NextPlot`

property (which is,`replace`

), deletes all graphics objects from the axes, resets all axes properties (except`Position`

and`Units`

) to their defaults, and returns the handle of the current axes. If there is no current axes,`newplot`

creates one, but does not recheck its`NextPlot`

property.Deletes all graphics objects from the axes, resets all axes properties (except

`Position`

and`Units`

) to their defaults, and returns the handle of the current axes. If there is no current axes,`newplot`

creates one, but does not recheck its`NextPlot`

property.

#### hold Function and NextPlot Properties

The `hold`

function provides
convenient access to the `NextPlot`

properties. When
you want add objects to a graph without removing other objects or
resetting properties use `hold on`

:

`hold on`

— Sets the figure and axes`NextPlot`

properties to`add`

. Line graphs continue to cycle through the`ColorOrder`

and`LineStyleOrder`

property values.`hold off`

— Sets the axes`NextPlot`

property to`replace`

Use the `ishold`

to determine
if `hold`

is `on`

or `off`

.

### Control Behavior of User-Written Plotting Functions

MATLAB provides the `newplot`

function
to simplify writing plotting functions that conform to the settings
of the `NextPlot`

properties.

`newplot`

checks the values of the `NextPlot`

properties
and takes the appropriate action based on these values. Place `newplot`

at
the beginning of any function that calls object creation functions.

When your function calls `newplot`

, `newplot`

first
queries the figure `NextPlot`

property. Based on
the property values `newplot`

then takes the action
described in the following table based on the property value.

Figure NextPlot Property Value | newplot Function |
---|---|

No figures exist | Creates a figure and makes this figure the current figure. |

| Makes the figure the current figure. |

| Creates a new figure and makes it the current figure. |

| Deletes the figure's children (axes objects and their descendants) and makes this figure the current figure. |

| Deletes the figure's children, resets the figure's properties to their defaults, and makes this figure the current figure. |

Then `newplot`

checks the current axes' `NextPlot`

property.
Based on the property value `newplot`

takes the
action described in the following table.

Axes NextPlot Property Value | newplot Function |
---|---|

No axes in current figure | Creates an axes and makes it the current axes |

| Makes the axes the current axes and returns its handle. |

| Deletes the axes' children and makes this axes the current axes. |

| Deletes the axes' children, reset the axes' properties to their defaults, and makes this axes the current axes. |