function t = dcolbar(clev,hor_vert,titlestr, shrink, varargin)
% h = dcolbar(clev, hor_vert, titlestr, shrink, ...)
%
%  Makes a Discrete COLorBAR suitable for filled contouring
%  with contourf.
%     h is the handle of the new colorbar object
%     clev is a 1xn row-vector of contour levels
%     hor_vert is orientation: default (i.e. missing) is vertical
%        options are 'horiz' and 'vert'
%     titlestr: a label for the X or Y axis, as appropriate
%     shrink: [sw sl], where sw is the thickness of the colorbar
%        as a fraction of what the colorbar command produces,
%        and sl is the length, also as a fraction of the original.
%        Default is [0.25, 0.7].  Default is set if shrink = [].
%        Alternative: [left bottom width height]; if shrink
%        is a 4-element vector, it will be interpreted as
%        an axes object 'Position' specification.  Units are
%        still the Matlab default, normalized.
%     any arguments following shrink will be treated as
%        axes property-value pairs, and will be passed to
%        the colorbar axes object without checking.  Note that
%        to use this option, you must specify something for each
%        of the previous arguments.  titlestr can be '' and
%        shrink can be [] if you don't want them to do anything.
%
% Note: you must set caxis based on clev as shown below.
% The reasons we don't do it inside dcolbar are (1) it is better
% to see how clev is being set in the same block of code where
% contourf is called, and (2) it allows us to pass, for example,
% clev/1000 into dcolbar so that it can label depths in km even
% though they were contoured in meters.
%
% recommended usage:
%
% either
%
% (1) clev=[-100:10:100]
% (2) contourf(data_field,clev)
% (3) caxis([clev(1) clev(end-1)])  %MUST be one level back from the end
% (4) dcolbar(clev,'horiz','title goes here') %or 'vert'
%
% or
%
% (1) clev=[-100:10:100]
% (2) contourf(data_field,clev) 
% (3) caxis([clev(1) clev(end)])
% (4) dcolbar([clev clev(end)*1.0001],'horiz','title goes here') 
%    'horiz' could be 'vert'.  The second method limits the dynamic range
%    of the colorbar a little, and does not show a color for values beyond
%    max(clev).

%  See also cf_index.m.

% Original version by Dail Rowe; extensively modified by Jules Hummon
% and Eric Firing.

% corrected bug introduced by 5.2 upgrade.  Dail Rowe, 5/11/98


% defaults ------------------------------
if nargin < 4,
   shrink = [];
end
if isempty(shrink), shrink = [0.25 0.7]; end
if nargin < 3,
   titlestr = '';
end
if nargin < 2,
   hor_vert = 'vert';
end

% Argument checking ------------------
if (nargin<1)
        help dcolbar
        error('At least one argument is needed.')
end

if (~strcmp(hor_vert,'vert')&~strcmp(hor_vert,'horiz'))
   help dcolbar
   error(['orientation string given as ' hor_vert ...
         ' must be either ''horiz'' or ''vert'' '])
end
% No checking of third argument: title string.
if isempty(shrink) | length(shrink) == 2 | length(shrink) == 4,
      % shrink is valid
else
   help dcolbar
   error('shrink (4th argument) must have 0, 2, or 4 elements');
end

%now make the colorbar ----------------------------------------

ax = gca;
t = colorbar(hor_vert);
if length(shrink) == 2,
   pos = get(t, 'Position');
   if strcmp(hor_vert,'vert'),
      cb_pos = [pos(1), pos(2)+ 0.5*(1-shrink(2))*pos(4), ...
               shrink(1)*pos(3), shrink(2)*pos(4)];
   else
      cb_pos = [pos(1)+  0.5*(1-shrink(2))*pos(3), ...
               pos(2)+ (1-shrink(1))*pos(4), ...
               shrink(2)*pos(3), shrink(1)*pos(4)];
   end
else  % length must be 4
   cb_pos = shrink;
end
set(t, 'Position', cb_pos, 'Tag', 'dcolbar');
set( get(t,'children'), 'deletefcn','')
hold on
axes(t)

if strcmp(hor_vert,'horiz')
        contourf(clev,[1 2],[1;1]*clev,clev);
        set(t,'YTickLabel',[], 'YTick', []);
        xlabel(titlestr);
     else
        contourf([1 2],clev,([1;1]*clev)',clev);
        set(t,'XTickLabel',[], 'XTick', []);
        set(t,'YAxisLocation','right')
        ylabel(titlestr);
end
set(t, 'TickDir', 'out');
if ~isempty(varargin)
   set(t, varargin{:})
end

% Back to the original axes.
axes(ax);



