Implementing multiple syntaxes for a MATLAB plot function

Question

Many of the plotting functions in MATLAB and toolboxes (thought not all) allow both the following syntaxes:

plotfcn(data1, data2, ...)
plotfcn(axes_handle, data1, data2, ...)

The first plots into the current axes (gca) or creates and plots into a new axes if none exists. The second plots into the axes with handle axes_handle.

Having looked into the internals of several MATLAB and toolbox plotting functions, it looks like there isn't really a standardised way that MathWorks do this. Some plotting routines use the internal, but open, function axescheck to parse the input arguments; some do a simple check on the first input argument; and some use a more complex input-parsing subfunction that can handle a larger variety of input syntaxes.

Note that axescheck appears to use an undocumented syntax of ishghandle - the doc says that ishghandle takes only one input, returning true if it is any Handle Graphics object; but axescheck calls it as ishghandle(h, 'axes'), which returns true only if it's specifically an axes object.

Is anyone aware of a best practice or standard for implementing this syntax? If not, which way have you found to be most robust?

Sam Roberts Sam Roberts · Accepted Answer · 2017-07-25T14:45:30

In case anyone is still interested, four years after I posted the question, this is the pattern that I have mostly settled on.

function varargout = myplotfcn(varargin)
% MYPLOTFCN Example plotting function.
%
% MYPLOTFCN(...) creates an example plot.
%
% MYPLOTFCN(AXES_HANDLE, ...) plots into the axes object with handle
% AXES_HANDLE instead of the current axes object (gca).
%
% H = MYPLOTFCN(...) returns the handle of the axes of the plot.

% Check the number of output arguments.
nargoutchk(0,1);

% Parse possible axes input.
[cax, args, ~] = axescheck(varargin{:});

% Get handle to either the requested or a new axis.
if isempty(cax)
    hax = gca;
else
    hax = cax;
end

% At this point, |hax| refers either to a supplied axes handle,
% or to |gca| if none was supplied; and |args| is a cell array of the
% remaining inputs, just like a normal |varargin| input.

% Set hold to on, retaining the previous hold state to reinstate later.
prevHoldState = ishold(hax);
hold(hax, 'on')          


% Do the actual plotting here, plotting into |hax| using |args|.


% Set the hold state of the axis to its previous state.
switch prevHoldState
    case 0
        hold(hax,'off')
    case 1
        hold(hax,'on')
end

% Output a handle to the axes if requested.
if nargout == 1
    varargout{1} = hax;
end

Implementing multiple syntaxes for a MATLAB plot function

3 Answers