time   calls  line
                  1 function [leg,labelhandles,outH,outM] = legend(varargin)
                  2 %LEGEND Display legend.
                  3 %   LEGEND(string1,string2,string3, ...) puts a legend on the current plot
                  4 %   using the specified strings as labels. LEGEND works on line graphs,
                  5 %   bar graphs, pie graphs, ribbon plots, etc.  You can label any
                  6 %   solid-colored patch or surface object.  The fontsize and fontname for
                  7 %   the legend strings matches the axes fontsize and fontname.
                  8 %
                  9 %   LEGEND(H,string1,string2,string3, ...) puts a legend on the plot
                 10 %   containing the handles in the vector H using the specified strings as
                 11 %   labels for the corresponding handles.
                 12 %
                 13 %   LEGEND(M), where M is a string matrix or cell array of strings, and
                 14 %   LEGEND(H,M) where H is a vector of handles to lines and patches also
                 15 %   works.
                 16 %
                 17 %   LEGEND(AX,...) puts a legend on the axes with handle AX.
                 18 %
                 19 %   LEGEND OFF removes the legend from the current axes and deletes
                 20 %   the legend handle.
                 21 %   LEGEND(AX,'off') removes the legend from the axis AX.
                 22 %
                 23 %   LEGEND TOGGLE toggles legend on or off.  If no legend exists for the
                 24 %   current axes one is created using default strings. The default
                 25 %   string for an object is the value of the DisplayName property
                 26 %   if it is non-empty and otherwise it is a string of the form
                 27 %   'data1','data2', etc.
                 28 %   LEGEND(AX,'toggle') toggles legend for axes AX
                 29 %
                 30 %   LEGEND HIDE makes legend invisible.
                 31 %   LEGEND(AX,'hide') makes legend on axes AX invisible.
                 32 %   LEGEND SHOW makes legend visible. If no legend exists for the
                 33 %   current axes one is created using default strings.
                 34 %   LEGEND(AX,'show') makes legend on axes AX visible.
                 35 %
                 36 %   LEGEND BOXOFF  makes legend background box invisible when legend is
                 37 %   visible.
                 38 %   LEGEND(AX,'boxoff') for axes AX makes legend background box invisible when
                 39 %   legend is visible.
                 40 %   LEGEND BOXON makes legend background box visible when legend is visible.
                 41 %   LEGEND(AX,'boxon') for axes AX making legend background box visible when
                 42 %   legend is visible.
                 43 %
                 44 %   LEGH = LEGEND returns the handle to legend on the current axes or
                 45 %   empty if none exists.
                 46 %
                 47 %
                 48 %   LEGEND(...,'Location',LOC) adds a legend in the specified
                 49 %   location, LOC, with respect to the axes.  LOC may be either a
                 50 %   1x4 position vector or one of the following strings:
                 51 %       'North'              inside plot box near top
                 52 %       'South'              inside bottom
                 53 %       'East'               inside right
                 54 %       'West'               inside left
                 55 %       'NorthEast'          inside top right (default for 2-D plots)
                 56 %       'NorthWest'           inside top left
                 57 %       'SouthEast'          inside bottom right
                 58 %       'SouthWest'          inside bottom left
                 59 %       'NorthOutside'       outside plot box near top
                 60 %       'SouthOutside'       outside bottom
                 61 %       'EastOutside'        outside right
                 62 %       'WestOutside'        outside left
                 63 %       'NorthEastOutside'   outside top right (default for 3-D plots)
                 64 %       'NorthWestOutside'   outside top left
                 65 %       'SouthEastOutside'   outside bottom right
                 66 %       'SouthWestOutside'   outside bottom left
                 67 %       'Best'               least conflict with data in plot
                 68 %       'BestOutside'        least unused space outside plot
                 69 %   If the legend does not fit in the 1x4 position vector the position
                 70 %   vector is resized around the midpoint to fit the preferred legend size.
                 71 %   Moving the legend manually by dragging with the mouse or setting
                 72 %   the Position property will set the legend Location property to 'none'.
                 73 %
                 74 %   LEGEND(...,'Orientation',ORIENTATION) creates a legend with the
                 75 %   legend items arranged in the specified ORIENTATION. Allowed
                 76 %   values for ORIENTATION are 'vertical' (the default) and 'horizontal'.
                 77 %
                 78 %   [LEGH,OBJH,OUTH,OUTM] = LEGEND(...) returns a handle LEGH to the
                 79 %   legend axes; a vector OBJH containing handles for the text, lines,
                 80 %   and patches in the legend; a vector OUTH of handles to the
                 81 %   lines and patches in the plot; and a cell array OUTM containing
                 82 %   the text in the legend.
                 83 %
                 84 %   Examples:
                 85 %       x = 0:.2:12;
                 86 %       plot(x,besselj(1,x),x,besselj(2,x),x,besselj(3,x));
                 87 %       legend('First','Second','Third','Location','NorthEastOutside')
                 88 %
                 89 %       b = bar(rand(10,5),'stacked'); colormap(summer); hold on
                 90 %       x = plot(1:10,5*rand(10,1),'marker','square','markersize',12,...
                 91 %                'markeredgecolor','y','markerfacecolor',[.6 0 .6],...
                 92 %                'linestyle','-','color','r','linewidth',2); hold off
                 93 %       legend([b,x],'Carrots','Peas','Peppers','Green Beans',...
                 94 %                 'Cucumbers','Eggplant')
                 95 
                 96 
                 97 %   Unsupported APIs for internal use:
                 98 %
                 99 %   LOC strings can be abbreviated NE, SO, etc or lower case.
                100 %
                101 %   LEGEND('-DynamicLegend') or LEGEND(AX,'-DynamicLegend')
                102 %   creates a legend that adds new entries when new plots appear
                103 %   in the peer axes.
                104 %
                105 %   LEGEND(LI,string1,string2,string3) creates a legend for legendinfo
                106 %   objects LI with strings string1, etc.
                107 %   LEGEND(LI,M) creates a legend for legendinfo objects LI where M is a
                108 %   string matrix or cell array of strings corresponding to the legendinfo
                109 %   objects.
                110 
                111 %   Copyright 1984-2010 The MathWorks, Inc.
                112 
                113 % First we check whether Handle Graphics uses MATLAB classes
            14  114 isHGUsingMATLABClasses = feature('HGUsingMATLABClasses'); 
                115 
  0.01      14  116 if isHGUsingMATLABClasses 
                117     % Legend no longer supports more than one output argument
                118     % Warn the user and ignore additional output arguments.
                119     if nargout > 1
                120         warning(['MATLAB:legend:maxlhs'],...
                121             'LEGEND does not support more than one output argument.  Additional output arguments will be ignored.');
                122     end
                123 
                124     if nargout == 0
                125         legendHGUsingMATLABClasses(varargin{:});
                126     else
                127         leg = legendHGUsingMATLABClasses(varargin{:});
                128         if nargout > 1
                129             % populate unsupported additional outputs if requested
                130             % @todo - return empty default object instead
                131             labelhandles = [];
                132             outH = [];
                133             outM = [];
                134         end
                135     end
            14  136 else 
            14  137     narg = nargin; 
            14  138     if (narg > 1 && ischar(varargin{1}) && ~ischar(varargin{2}) && strcmp(varargin{1},'v6')) 
                139         warning(['MATLAB:', mfilename, ':DeprecatedV6Argument'],...
                140             ['The ''v6'' argument to %s is deprecated,',...
                141             ' and will no longer be supported in a future release.'], upper(mfilename));
                142         if nargout == 0
                143             legendv6(varargin{2:end});
                144         elseif nargout == 1
                145             leg = legendv6(varargin{2:end});
                146         elseif nargout == 2
                147             [leg,labelhandles] = legendv6(varargin{2:end});
                148         else
                149             [leg,labelhandles,outH,outM] = legendv6(varargin{2:end});
                150         end
                151         return;
                152         
                153         % look for special callbacks into legend for V6 legend code
            14  154     elseif (narg==1 && ischar(varargin{1}) && ... 
                155             isvector(varargin{1}) && ...
                156             size(varargin{1},2) == length(varargin{1}) && ...
                157             any(strcmp(varargin{1},{'DeleteLegend','ResizeLegend'})))
                158         legendv6(varargin{:});
                159         return;
                160         
            14  161     elseif (narg==2 && ischar(varargin{1}) && ... 
                162             isvector(varargin{1}) && ...
                163             size(varargin{1},2) == length(varargin{1}) && ...
                164             any(strcmp(varargin{1},...
                165             {'EditLegend','ShowLegendPlot','RestoreSize','RecordSize'})))
                166         legendv6(varargin{:});
                167         return
                168     end
                169     % HANDLE FINDLEGEND CASES FIRST
            14  170     if narg==2 && ... 
                171             ischar(varargin{1}) && ...
                172             isequal(lower(varargin{1}),'-find') && ...
                173             ~isempty(varargin{2}) && ...
                174             ishandle(varargin{2}) && ...
                175             strcmpi(get(varargin{2},'type'),'axes')
                176         if nargout<=1
                177             leg = find_legend(varargin{2});
                178         else
                179             [leg,labelhandles,outH,outM] = find_legend_info(varargin{2});
                180         end
                181         return;
                182     end
                183     
  0.01      14  184     old_currfig = get(0,'CurrentFigure'); 
            14  185     if ~isempty(old_currfig) 
            14  186         old_currax = get(old_currfig,'CurrentAxes'); 
  0.01      14  187     end 
                188     
            14  189     arg = 1; 
                190     
                191     % GET AXES FROM INPUTS
  0.02      14  192     if narg > 0  && ~isempty(varargin{1}) && ... 
                193             length(varargin{1})==1 && ...
                194             ishandle(varargin{1}) && ...
                195             ~isa(varargin{1},'scribe.legendinfo') && ...
                196             strcmp(get(varargin{1}(1),'type'),'axes') % legend(ax,...)
                197         ha = varargin{1}(1);
                198         arg = arg + 1;
            14  199     elseif narg > 0 && ~ischar(varargin{1}) && ... 
                200             ~isempty(varargin{1}) && ...
                201             all(ishandle(varargin{1})) && ...
                202             ~any(isa(varargin{1},'scribe.legendinfo'))  % legend(children,strings,...)
             1  203         ha = ancestor(varargin{1}(1),'axes'); 
             1  204         if isempty(ha) 
                205             error(id('InvalidPeerParameter'),...
                206                 'Handle must be an axes or child of an axes.');
                207         end
            13  208     else 
            13  209         ha = gca; 
            13  210     end 
                211     
                212     % LOOK FOR -DEFAULTSTRINGS option flag
            14  213     dfltstrings=false; 
            14  214     if narg >= arg && all(ischar(varargin{arg})) && ... 
                215             all(strcmpi(varargin{arg},'-defaultstrings'))
                216         dfltstrings=true;
                217         arg = arg + 1;
                218     end
                219     
                220     % if axes is a legend use its plotaxes
            14  221     h = handle(ha); 
  0.03      14  222     if isa(h,'scribe.colorbar') || isa(h,'scribe.legend'); 
                223         ha = double(h.axes);
                224     end
            14  225     h = []; 
                226     
                227     % PROCESS REMAINING INPUTS
            14  228     msg = ''; 
  0.01      14  229     if narg < arg % legend 
                230         if nargout<=1, % h = legend or legend with no outputs
                231             l = find_legend(ha);
                232             if isempty(l) && dfltstrings
                233                 [l,msg]=make_legend(ha,{});
                234             end
                235             if nargout == 1, leg = l; end
                236         else % [h,objh,...] = legend
                237             [leg,labelhandles,outH,outM] = find_legend_info(ha);
                238             if isempty(leg) && dfltstrings
                239                 [h,msg] = make_legend(ha,{}); %#ok
                240                 [leg,labelhandles,outH,outM] = find_legend_info(ha);
                241             end
                242         end
                243         if ~isempty(msg)
                244             warning(msg.identifier,msg.message);
                245         end
                246         return;
            14  247     elseif narg >= arg && ischar(varargin{arg}) 
             5  248         if strcmpi(varargin{arg},'off') || strcmpi(varargin{arg},'DeleteLegend') 
                249             delete_legend(find_legend(ha));
             5  250         elseif strcmpi(varargin{arg},'resizelegend') 
                251             % do nothing. there is no need for this call, but it exists in old
                252             % code that was needed when legend did not have listeners to keep
                253             % itself positioned (prior to R14).
             5  254         elseif strcmpi(varargin{arg},'toggle') 
                255             l=find_legend(ha);
                256             if isempty(l) || strcmpi(get(l,'Visible'),'off')
                257                 legend(ha,'show');
                258             else
                259                 legend(ha,'hide');
                260             end
             5  261         elseif strcmpi(varargin{arg},'show') 
                262             l=find_legend(ha);
                263             if isempty(l)
                264                 [h,msg] = make_legend(ha,varargin(arg+1:end));
                265             else
                266                 set(l,'Visible','on');
                267             end
             5  268         elseif strcmpi(varargin{arg},'hide') 
                269             l=find_legend(ha);
                270             if ~isempty(l)
                271                 set(l,'Visible','off');
                272             end
             5  273         elseif strcmpi(varargin{arg},'boxon') 
                274             l=handle(find_legend(ha));
                275             if ~isempty(l)
                276                 set(l,'Visible','on');
                277             end
             5  278         elseif strcmpi(varargin{arg},'boxoff') 
                279             lh=handle(find_legend(ha));
                280             if ~isempty(lh)
                281                 lh.ObserveStyle='off';
                282                 set(lh,'Visible','off');
                283                 lh.ObserveStyle='on';
                284             end
             5  285         else 
  0.80       5  286             [h,msg] = make_legend(ha,varargin(arg:end)); 
             5  287         end 
             9  288     else % narg > 1 
  1.19       9  289         [h,msg] = make_legend(ha,varargin(arg:end)); 
             9  290     end 
  0.02      14  291     if ~isempty(msg) 
                292         if isstruct(msg)
                293             warning(msg.identifier,msg.message);
                294         else
                295             warning(msg); %#ok
                296         end
                297     end
                298     
                299     % PROCESS OUTPUTS
            14  300     if nargout==0 
                301     elseif nargout==1
                302         if isempty(h)
                303             leg = find_legend(ha);
                304         else
                305             leg = h;
                306         end
                307     elseif nargout==2
                308         [leg,labelhandles] = find_legend_labelhandles(ha);
                309     elseif nargout<=4
                310         [leg,labelhandles,outH,outM] = find_legend_info(ha);
                311     elseif nargout>4
                312         error(id('BadNumberOfOutputs'),'Must have 0,1,2,3 or 4 outputs.');
                313     end
                314     
                315     % before going, be sure to reset current figure and axes
            14  316     if ~isempty(old_currfig) && ishandle(old_currfig) && ~strcmpi(get(old_currfig,'beingdeleted'),'on') 
            14  317         set(0,'CurrentFigure',old_currfig); 
            14  318         if ~isempty(old_currax) && ishandle(old_currax) && ~strcmpi(get(old_currax,'beingdeleted'),'on') 
            14  319             set(old_currfig,'CurrentAxes',old_currax); 
            14  320         end 
            14  321     end 
            14  322 end 

Other subfunctions in this file are not included in this listing.