function hhh=hline(y,in1,in2,varargin)
%HLINE  draw horizontal line
%
% function h=hline(y, linetype, label)
% function h=hline(y, linetype, label,'on')
% function h=hline(y, linetype, label,'off')
% 
% Draws a horizontal line on the current axes at the location 
% specified by 'y'.  Optional arguments are 'linetype' 
% (default is 'r:') and 'label', which applies a text label to 
% the graph near the line. The label appears in the same color 
% as the line.
%
% The line is held on the current axes, and after plotting the 
% line, the function returns the axes to its prior hold state.
%
% The HandleVisibility property of the line object is set to "off", 
% so not only does it not appear on legends, but it is not findable 
% by using findobj.  Specifying an output argument causes the function 
% to return a handle to the line, so it can be manipulated or deleted.
% Also, the HandleVisibility can be overridden by setting the root's 
% ShowHiddenHandles property to on.
%
% function h=hline(y, linetype, label,'on'/'off')
% An optional 4th argument can be specified that is passed to 
% the 'handlevisibility' property of the line (default 'off').
%
% h = hline(42,'g','The Answer')
%
% returns a handle to a green horizontal line on the current axes at y=42,
% and creates a text object on the current axes, close to the line, 
% which reads "The Answer".
%
% hline also supports vector inputs to draw multiple lines at once.  For example,
%
% hline([4 8 12],{'g','r','b'},{'l1','lab2','LABELC'})
%
% draws three lines with the appropriate labels and colors.
% 
% HLINE comes from the <a href="http://www.mathworks.com/matlabcentral/fileexchange/1039">Mathworks download central</a>, for copyright: edit hline.
% 
% Note that when axis limits are set to '-Inf' or 'Inf', function will not work.
% Note that sometimes the hline does show up in the legend when 'off' is passed, 
% but stops doing so after rebooting matlab ...
%
% See also: VLINE

%% Copyright notice
% By Brandon Kuczenski for Kensington Labs (brandon_kuczenski@kensingtonlabs.com) 8 November 2001

% Copyright (c) 2001, Brandon Kuczenski
% All rights reserved.
% 
% Redistribution and use in source and binary forms, with or without 
% modification, are permitted provided that the following conditions are 
% met:
% 
%     * Redistributions of source code must retain the above copyright 
%       notice, this list of conditions and the following disclaimer.
%     * Redistributions in binary form must reproduce the above copyright 
%       notice, this list of conditions and the following disclaimer in 
%       the documentation and/or other materials provided with the distribution
%       
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
% AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
% ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
% INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
% CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
% ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
% POSSIBILITY OF SUCH DAMAGE.

%% Version <http://svnbook.red-bean.com/en/1.5/svn.advanced.props.special.keywords.html>
% changed G.J. de Boer(g.j.deboer@tudelft.nl) 11th March 2006

% $Id$
% $Date$
% $Author$
% $Revision$
% $HeadURL$
% $Keywords: $

if length(y)>1  % vector input
    for I=1:length(y)
        if nargin == 1
            linetype='r:';
            label='';
        elseif nargin == 2
            if ~iscell(in1)
                in1={in1};
            end
            if I>length(in1)
                linetype=in1{end};
            else
                linetype=in1{I};
            end
            label='';
        elseif nargin > 2
            if ~iscell(in1)
                in1={in1};
            end
            if ~iscell(in2)
                in2={in2};
            end
            if I>length(in1)
                linetype=in1{end};
            else
                linetype=in1{I};
            end
            if I>length(in2)
                label=in2{end};
            else
                label=in2{I};
            end
        end
        h(I)=hline(y(I),linetype,label);
    end
else

    if nargin ==1
        linetype = 'r:';
        label    = '';
    elseif nargin == 2 
        linetype = in1;
        label    = '';
    elseif nargin > 2
        linetype = in1;
        label    = in2;
    end
    
    g=ishold(gca);
    hold on

    x=get(gca,'xlim');
    h=plot(x,[y y],linetype);
    if ~isempty(label)
        yy=get(gca,'ylim');
        yrange=yy(2)-yy(1);
        yunit=(y-yy(1))/yrange;
        if yunit<0.2
            text(x(1)+0.02*(x(2)-x(1)),y+0.02*yrange,label,'color',get(h,'color'))
        else
            text(x(1)+0.02*(x(2)-x(1)),y-0.02*yrange,label,'color',get(h,'color'))
        end
    end

    if g==0
    hold off
    end
    if nargin==4
       handlevisibility = varargin{1};
    else
       handlevisibility ='off';
    end
    set(h,'tag','vline','handlevisibility',handlevisibility);
    % this last part is so that it doesn't show up on legends
    % NOT ALWAYS A GOOD IDEA AS THEN THE LINE DOES NOT DISAPPEAR WHEN CALLING CLA
end % else

if nargout
    hhh=h;
end
