function axReturn = newplot(hsave)

%NEWPLOT Prepares figure, axes for graphics according to NextPlot.

%   H = NEWPLOT returns the handle of the prepared 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

%   instead of the current axes of the current figure. If HSAVE is

%   empty, NEWPLOT behaves as if it were called without any inputs.

%

%   NEWPLOT is a standard preamble command that is put at

%   the beginning of graphics functions that draw graphs

%   using only low-level object creation commands. NEWPLOT

%   "does the right thing" in terms of determining which axes and/or

%   figure to draw the plot in, based upon the setting of the

%   NextPlot property of axes and figure objects, and returns a

%   handle to the appropriate axes.

%

%   The "right thing" is:

%

%   First, prepare a figure for graphics:

%   Clear and reset the current figure using CLF RESET if its NextPlot

%   is 'replace', or clear the current figure using CLF if its

%   NextPlot is 'replacechildren', or reuse the current figure as-is

%   if its NextPlot is 'add', or if no figures exist, create a figure.

%   When the figure is prepared, set its NextPlot to 'add', and then

%   prepare an axes in that figure:

%   Clear and reset the current axes using CLA RESET if its NextPlot

%   is 'replace', or clear the current axes using CLA if its NextPlot

%   is 'replacechildren', or reuse the current axes as-is if its

%   NextPlot is 'add', or if no axes exist, create an axes.

%

%   See also HOLD, ISHOLD, FIGURE, AXES, CLA, CLF.

%   Copyright 1984-2017 The MathWorks, Inc.

%   Built-in function.

if nargin == 0 || isempty(hsave) 

    hsave = []; 

elseif ~isscalar(hsave) || ~ishghandle(hsave)

    error(message('MATLAB:newplot:InvalidHandle'))

else

    % Make sure we have an object handle.

    hsave = handle(hsave);

end

fig = gobjects(0); 

ax = gobjects(0); 

if ~isempty(hsave) 

    obj = hsave;

    while ~isempty(obj)

        if isgraphics(obj, 'figure')

            fig = obj;

        elseif isgraphics(obj, 'axes') || isgraphics(obj,'polaraxes')

            ax = obj;

        end

        obj = obj.Parent;

    end

end

if isempty(fig) 

    fig = gcf; 

end 

fig = ObserveFigureNextPlot(fig, hsave); 

% Set figure's NextPlot property to 'add' after obeying the previous setting.

fig.NextPlot = 'add'; 

checkNextPlot = true; 

if isempty(ax) 

    ax = gca(fig); 

    if ~isa(ax,'matlab.graphics.axis.Axes') 

        if isprop(ax,'NextPlot') && ishold(ax)

            error(message('MATLAB:newplot:HoldOnMixing'))

        else

            ax = matlab.graphics.internal.swapaxes(ax,@axes);

            % We just creaetd a new axes, no need to check NextPlot

            checkNextPlot = false;

        end

    end

elseif ~any(ishghandle(ax))

    error(message('MATLAB:newplot:NoAxesParent'))

end

if checkNextPlot 

    ax = ObserveAxesNextPlot(ax, hsave); 

end 

if nargout 

    axReturn = ax; 

end