% MSUPTITLE Puts a title above all subplots.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% DESCRIPTION: MSUPTITLE Puts a title above all subplots.
%	             MSUPTITLE('text') adds text to the top of the figure
%            	 above all subplots (a "super title"). Use this function
%              after all subplot commands.
%
% CALL:        xaxis(x1,x2)
%
% REMARK:      If the figure or axis units are non-default, this will break.
%
% VERSION:     $Id: msuptitle.m,v 1.1 2008/08/05 17:51:32 ingo Exp $
%
% HISTORY:     15-06-1995 Drea Thomas (drea@mathworks.com)
%                 Creation.
%              13-12-2000 John Cristion
%                 Modified.
%              13-03-2004 Mark Histed (histed@mit.edu)
%                 Fix disappearing legend on last plot
%              xx-xx-xxxx M Hewitson
%                 Just a copy and rename with some small adjustements
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

function hout = msuptitle(str)

  % Parameters used to 1position the supertitle.

  % Amount of the figure window devoted to subplots
  plotregion = .92;

  % Y position of title in normalized coordinates
  titleypos  = .95;

  % Fontsize for supertitle
  %fs = get(gcf,'defaultaxesfontsize')+4;

  fs = get(gcf,'defaultaxesfontsize');

  % Fudge factor to adjust y spacing between subplots
  fudge=1;

  haold = gca;
  figunits = get(gcf,'units');

  % Get the (approximate) difference between full height (plot + title
  % + xlabel) and bounding rectangle.

  if (~strcmp(figunits,'pixels')),
    set(gcf,'units','pixels');
    pos = get(gcf,'position');
    set(gcf,'units',figunits);
  else
    pos = get(gcf,'position');
  end
  ff = (fs-4)*1.27*5/pos(4)*fudge;

  % The 5 here reflects about 3 characters of height below
  % an axis and 2 above. 1.27 is pixels per point.

  % Determine the bounding rectange for all the plots

  % h = findobj('Type','axes');

  % findobj is a 4.2 thing.. if you don't have 4.2 comment out
  % the next line and uncomment the following block.

  % h = findobj(gcf,'Type','axes');  % Change suggested by Stacy J. Hills

  % If you don't have 4.2, use this code instead
  ch = get(gcf,'children');
  h=[];
  for i=1:length(ch),
    if strcmp(get(ch(i),'type'),'axes'),
      h=[h,ch(i)];
    end
  end


  max_y=0;
  min_y=1;

  oldtitle =0;
  for i=1:length(h),
    if (~strcmp(get(h(i),'Tag'),'suptitle')),
      pos=get(h(i),'pos');
      if (pos(2) < min_y), min_y=pos(2)-ff/5*3;end;
      if (pos(4)+pos(2) > max_y), max_y=pos(4)+pos(2)+ff/5*2;end;
    else
      oldtitle = h(i);
    end
  end

  if max_y > plotregion,
    scale = (plotregion-min_y)/(max_y-min_y);
    for i=1:length(h),
      get(h(i),'Tag')
      if ~strcmp(get(h(i),'Tag'),'legend')
        pos = get(h(i),'position');
        pos(2) = (pos(2)-min_y)*scale+min_y;
        pos(4) = pos(4)*scale-(1-scale)*ff/5*3;
        set(h(i),'position',pos);
      end
    end
  end

  np = get(gcf,'nextplot');
  set(gcf,'nextplot','add');
  if (oldtitle),
    delete(oldtitle);
  end
  ha=axes('pos',[0 1 1 1],'visible','off','Tag','suptitle');
  ht=text(.5,titleypos-1,str);set(ht,'horizontalalignment','center','fontsize',fs);
  set(gcf,'nextplot',np);
  axes(haold);

  % fix legend if one exists
  legH = legend;
  if ~isempty(legH)
    axes(legH);
  end

  if nargout,
    hout=ht;
  end

end