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
new	Creates a new figure and uses it as the current figure.	Not an option for axes.
add	Adds new graphics objects without clearing or resetting the current figure. (Default)	Adds new graphics objects without clearing or resetting the current axes.
replacechildren	Removes all axes objects whose handles are not hidden before adding new objects. Does not reset figure properties. Equivalent to clf.	Removes all axes child objects whose handles are not hidden before adding new graphics objects. Does not reset axes properties. Equivalent to cla.
replace	Removes all axes objects and resets figure properties to their defaults before adding new objects. Equivalent to clf reset.	Removes all child objects and resets axes properties to their defaults before adding new objects. Equivalent to cla reset. (Default)

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:

1. Checks the value of the current figure's NextPlot property (which is, add).

2. 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.

3. 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.

4. 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.
add	Makes the figure the current figure.
new	Creates a new figure and makes it the current figure.
replacechildren	Deletes the figure's children (axes objects and their descendants) and makes this figure the current figure.
replace	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
add	Makes the axes the current axes and returns its handle.
replacechildren	Deletes the axes' children and makes this axes the current axes.
replace	Deletes the axes' children, reset the axes' properties to their defaults, and makes this axes the current axes.