newplot

Specify where to draw graphics objects

Syntax

newplot

newplot(ax)

cax = newplot(___)

Description

newplot prepares the current axes for a new plot by ensuring that the new plot either adds to or replaces the existing plot. The behavior of newplot depends on the NextPlot property of both the axes and its parent figure. For more information, see Algorithms.

If no axes exist, newplot creates a new Cartesian axes object in the current figure.

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

newplot(ax) updates the specified axes ax instead of the current axes. You can use this newplot syntax at the beginning of your graphics code to determine which axes and figure to target with subsequent plotting commands.

cax = newplot(___) returns the Axes object. Specify the output argument with either of the previous syntaxes. Use cax to query and modify axes properties after creation. For a list of properties, see Axes Properties.

Examples

Create Default Axes

Create the default plotting axes.

newplot

Specify Axes to Update

Position two Axes objects in a figure, and add a plot to each Axes object. Specify the axes as the first input argument to each plotting function.

tiledlayout('flow')
ax1 = nexttile;
ax2 = nexttile;

plot(ax1,peaks(20))
surf(ax2,peaks(20))

view([450 0])

By default, ax2 has a NextPlot property of 'replace'. Change the NextPlot property to 'add'.

ax2.NextPlot

ans = 
'replace'

ax2.NextPlot = 'add';

When the axes NextPlot property value is 'add', plotting into the axes does not reset axes properties or remove child objects from the axes. The new values are plotted with the existing child objects.

newplot(ax2)
surf(ax2,peaks(5)+10)

Customize Appearance of Axes Before Plotting

Create two Axes objects, and add a plot to one of the objects.

tiledlayout("flow")
ax1 = nexttile;
ax2 = nexttile;

surf(ax1,peaks(20))

nexttile(1)
view([450 0])

Return the Axes object, and customize the axes appearance by setting properties of the object. For example, show the box outline and grid lines. Then set the axes NextPlot property to "add".

curr = newplot(ax2);

curr.Box = "on";
curr.XGrid = "on";
curr.YGrid = "on";
curr.NextPlot = "add";

Add a plot to the second Axes object.

plot(curr,peaks(20))

Write Plotting Function That Respects Hold State

Write a function named myPlot that plots data while respecting whether the hold state is on or off. In the function, call newplot to prepare the current axes for a new plot or to create axes if no axes exist.

function myPlot(data)
ax = newplot;
line(ax,XData=1:numel(data),YData=data,Marker="o");
end

Use myPlot to plot some data. The call to newplot in the myPlot function creates new axes if no existing axes are found.

d = linspace(0,12,100);
myPlot(sin(d));

Turn the hold state on and use myPlot to plot another set of data. Because the hold function sets the NextPlot property of the current axes, this call to newplot ensures that the myPlot function adds to the existing plot.

hold on
myPlot(cos(d));
hold off

Now replace the content of the axes with a new plot. Because hold is turned off, myPlot replaces the contents of the previous axes.

myPlot(cos(d+pi));

Input Arguments

ax — Axes to change or replace

Axes object | GeographicAxes object | PolarAxes object

Axes to change or replace, specified as an Axes, GeographicAxes, or PolarAxes object.

Algorithms

The behavior of the newplot function depends on both the NextPlot property of the figure and the NextPlot property of the axes.

First, the newplot function queries the NextPlot property of the figure. This table shows how the newplot function changes the figure based on the value of NextPlot.

Value of NextPlot Property (Figure)	Behavior of newplot
"add" (default)	Do not remove child objects from the figure. Do not reset figure properties.
"new"	Create a new figure.
"replacechildren"	Remove all child objects that are not hidden from the figure (that is, child objects whose HandleVisibility property is set to "on"). Reset the NextPlot property of the figure to "add". This behavior is equivalent to using the clf function.
"replace"	Remove all child objects from the figure, even if the child objects are hidden. Reset all figure properties to their default values, except Position, Units, PaperPosition, and PaperUnits. Reset the NextPlot property of the figure to "add", regardless of user-defined defaults. This behavior is equivalent to using the clf reset syntax of the clf function.

Then, the newplot function queries the NextPlot property of the axes in the figure. This table shows how the newplot function changes the axes based on the value of its NextPlot property.

Value of NextPlot Property (Axes)	Behavior of newplot
"replace" (default)	Remove all child objects from the axes. Reset all axes properties to their default values, except Position and Units. This behavior is equivalent to calling the cla function with the reset argument.
"add"	Do not remove child objects from the axes. Do not reset axes properties.
"replacechildren"	Remove all child objects from the axes. Reset the NextSeriesIndex property of the axes to 1. This behavior is equivalent to calling the cla function without the reset argument.
"replaceall"	Remove all child objects from the axes. Reset all axes properties to their default values, except Position and Units. For axes with only one y-axis, 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