gridxy.m

function hh = gridxy(x,varargin)
% GRIDXY - Plot horizontal / vertical grid reference lines
%
%   GRIDXY(X) plots vertical grid lines at the positions specified
%   by X. GRIDXY(X,Y) also plots horizontal grid lines at the positions
%   specified by Y. GRIDXY uses the current axes, if any. Lines outside
%   the plot area are plotted but not shown. When X or Y is empty no
%   vertical or horizontal lines are plotted.
%
%   The lines are plotted as a single graphics object. H = GRIDXY(..)
%   returns a graphics handle to that line object. 
%
%   GRIDXY(..., 'Prop1','Val1','Prop2','Val2', ...) uses the properties
%   and values specified for color, linestyle, etc. Execute GET(H), where H
%   is a line handle, to see a list of line object properties and their
%   current values. Execute SET(H) to see a list of line object properties
%   and legal property values.
%
%   Examples:
%     plot(10*rand(100,1), 10*rand(100,1),'bo') ; % random points
%     % horizontal red dashed grid
%     gridxy([1.1 3.2 4.5],'Color','r','Linestyle',':') ;
%     % vertical solid thicker yellowish grid, and store the handle
%     h = gridxy([],[2.1:0.7:5 8],'Color',[0.9 1.0 0.2],'linewidth',3) ;
%
%   GRIDXY can be used to plot a irregular grid on the axes.
%
%   See also PLOT, REFLINE, GRID, AXES, REFLINEXY, CROSSHAIR

% tested in Matlab R2017b
% version 2.4 (dec 2017)
% (c) Jos van der Geest
% email: samelinoa@gmail.com

% History
% Created (1.0) feb 2006
% 2.0 apr 2007 - renamed from reflinexy to gridxy, reflinexy is now used
%               for plotting intersection between X and Y axes
% 2.1 apr 2007 - add error check for line properties
% 2.2 feb 2008 - added set(gca,'layer','top') to put gridlines behind the
%                axis tick marks
% 2.3 feb 2014 - updated error checks, help section and comments
% 2.4 dec 2017 - updated for newer versions of matlab

narginchk(1,Inf) ;

% check the arguments
if ~isnumeric(x)
    error('GridXY:InvalidArgumentX', 'Numeric argument expected') ;
end

if nargin==1
    y = [] ;
    va = [] ;
else
    va = varargin ;
    if ischar(va{1})
        % optional arguments are
        y = [] ;
    elseif isnumeric(va{1})        
        y = va{1} ;
        va = va(2:end) ;
    else
        error('GridXY:InvalidArgumentY', 'Invalid second argument') ;
    end

end
if numel(va) > 0 && (~ischar(va{1}) || mod(numel(va), 2) == 1)
    error('GridXY:ArgumentNotPairs', 'Additional arguments have to be String/Value pairs') ;
end

% get the axes to plot in
hca=get(get(0,'currentfigure'),'currentaxes');
if isempty(hca)
    warning('No current axes found') ;
    return ;
end

% get the current limits of the axis
% used for limit restoration later on
xlim = get(hca, 'xlim') ;
ylim = get(hca, 'ylim') ;

% setup data for the vertical lines
xx1 = repmat(x(:).', 3, 1) ;
yy1 = repmat([ylim(:) ; nan], 1, numel(x)) ;

% setup data for the horizontal lines
xx2 = repmat([xlim(:) ; nan], 1, numel(y)) ;
yy2 = repmat(y(:).', 3, 1) ;

% create data for a single line object
xx1 = [xx1 xx2] ;
if ~isempty(xx1)     
    yy1 = [yy1 yy2] ;
    % add the line to the current axes
    np = get(hca, 'nextplot') ;
    set(hca, 'nextplot', 'add') ;
    h = line('xdata', xx1(:), 'ydata', yy1(:)) ;          
    set(hca,'ylim', ylim, 'xlim', xlim) ; % reset the limits
    
    uistack(h, 'bottom') ; % push lines to the bottom of the graph
    set(hca, 'nextplot', np, 'Layer', 'top') ;    % reset the nextplot state

    if ~isempty(va)
        try
            set(h,va{:}) ; % set line properties        
        catch ME
            rethrow(ME) ;
        end
    end
else
    h = [] ;
end

if nargout==1 
    % if requested return handle
    hh = h ;
end