changelog shortlog tags changeset files revisions annotate raw

scripts/plot/legend.m

changeset 10289: 4b124317dc38
parent:350148cc0774
author: John W. Eaton <jwe@octave.org>
date: Tue Feb 09 20:58:55 2010 -0500 (47 minutes ago)
permissions: -rw-r--r--
description: base_properties::set_children: account for hidden children 
     1## Copyright (C) 2001, 2006, 2007, 2008, 2009 Laurent Mazet

     2## Copyright (C) 2006 John W. Eaton

     3##

     4## This file is part of Octave.

     5##

     6## Octave is free software; you can redistribute it and/or modify it

     7## under the terms of the GNU General Public License as published by

     8## the Free Software Foundation; either version 3 of the License, or (at

     9## your option) any later version.

    10##

    11## Octave is distributed in the hope that it will be useful, but

    12## WITHOUT ANY WARRANTY; without even the implied warranty of

    13## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    14## General Public License for more details.

    15##

    16## You should have received a copy of the GNU General Public License

    17## along with Octave; see the file COPYING.  If not, see

    18## <http://www.gnu.org/licenses/>.

    19

    20## -*- texinfo -*-

    21## @deftypefn {Function File} {} legend (@var{st1}, @var{st2}, @dots{})

    22## @deftypefnx {Function File} {} legend (@var{st1}, @var{st2}, @dots{}, "location", @var{pos})

    23## @deftypefnx {Function File} {} legend (@var{matstr})

    24## @deftypefnx {Function File} {} legend (@var{matstr}, "location", @var{pos})

    25## @deftypefnx {Function File} {} legend (@var{cell})

    26## @deftypefnx {Function File} {} legend (@var{cell}, "location", @var{pos})

    27## @deftypefnx {Function File} {} legend ('@var{func}')

    28##

    29## Display a legend for the current axes using the specified strings

    30## as labels.  Legend entries may be specified as individual character

    31## string arguments, a character array, or a cell array of character

    32## strings.  Legend works on line graphs, bar graphs, etc.  A plot must

    33## exist before legend is called.

    34##

    35## The optional parameter @var{pos} specifies the location of the legend

    36## as follows:

    37##

    38## @multitable @columnfractions 0.06 0.14 0.80

    39## @item @tab north @tab

    40##   center top

    41## @item @tab south @tab

    42##   center bottom

    43## @item @tab east @tab

    44##   right center

    45## @item @tab west @tab

    46##   left center

    47## @item @tab northeast @tab

    48##   right top (default)

    49## @item @tab northwest @tab

    50##   left top

    51## @item @tab southeast @tab

    52##   right bottom

    53## @item @tab southwest @tab

    54##   left bottom

    55## @item 

    56## @item @tab outside @tab

    57##   can be appended to any location string

    58## @end multitable

    59##

    60## Some specific functions are directly available using @var{func}:

    61##

    62## @table @asis

    63## @item "show"

    64##   Show legends from the plot

    65## @item "hide"

    66## @itemx "off"

    67##   Hide legends from the plot

    68## @item "boxon"

    69##   Draw a box around legends

    70## @item "boxoff"

    71##   Withdraw the box around legends

    72## @item "left"

    73##   Text is to the left of the keys

    74## @item "right"

    75##   Text is to the right of the keys

    76## @end table

    77## @end deftypefn

    78

    79function legend (varargin)

    80

    81  [ca, varargin, nargin] = __plt_get_axis_arg__ ("legend", varargin{:});

    82  nargs = nargin;

    83

    84  if (nargs > 0)

    85    pos = varargin{nargs};

    86    if (isnumeric (pos) && isscalar (pos) && round (pos) == pos)

    87      if (pos >= -1 && pos <= 4)

    88	set (ca, "keypos", pos);

    89	nargs--;

    90      else

    91	error ("legend: invalid position specified");

    92      endif

    93    endif

    94  endif

    95  

    96  if (nargs > 1)

    97    pos = varargin{nargs-1};

    98    str = varargin{nargs};

    99    if (strcmpi (pos, "location")  && ischar (str))

   100      set (ca, "keypos", str);

   101      nargs -= 2;

   102    endif

   103  endif

   104

   105  kids = get (ca, "children");

   106  nkids = numel (kids);

   107  k = 1;

   108  turn_on_legend = false;

   109

   110  if (nargs == 1)

   111    arg = varargin{1};

   112    if (ischar (arg))

   113      if (rows (arg) == 1)

   114	str = tolower (deblank (arg));

   115	switch (str)

   116	  case {"off", "hide"}

   117	    set (ca, "key", "off");

   118	    nargs--;

   119	  case "show"

   120	    set (ca, "key", "on");

   121	    nargs--;

   122	  case "toggle"

   123	    val = get (ca, "key");

   124	    if (strcmpi (val, "on"))

   125	      set (ca, "key", "off");

   126	    else

   127	      set (ca, "key", "on");

   128	    endif

   129	    nargs--;

   130	  case "boxon"

   131	    set (ca, "key", "on", "keybox", "on");

   132	    nargs--;

   133	  case "boxoff"

   134	    set (ca, "keybox", "off");

   135	    nargs--;

   136	  case "left"

   137	    set (ca, "keyreverse", "off")

   138	    nargs--;

   139	  case "right"

   140	    set (ca, "keyreverse", "on")

   141	    nargs--;

   142	  otherwise

   143	endswitch

   144      else

   145	varargin = cellstr (arg);

   146	nargs = numel (varargin);

   147      endif

   148    elseif (iscellstr (arg))

   149      varargin = arg;

   150      nargs = numel (varargin);

   151    else

   152      error ("legend: expecting argument to be a character string");

   153    endif

   154  endif

   155

   156  if (nargs > 0)

   157    have_data = false;

   158    for k = 1:nkids

   159      typ = get (kids(k), "type");

   160      if (strcmp (typ, "line") || strcmp (typ, "surface")

   161	  || strcmp (typ, "patch") || strcmp (typ, "hggroup"))

   162	have_data = true;

   163	break;

   164      endif

   165    endfor

   166    if (! have_data)

   167      warning ("legend: plot data is empty; setting key labels has no effect");

   168    endif

   169  endif

   170

   171  warned = false;

   172  k = nkids;

   173  for i = 1:nargs

   174    arg = varargin{i};

   175    if (ischar (arg))

   176      typ = get (kids(k), "type");

   177      while (k > 1

   178	     && ! (strcmp (typ, "line") || strcmp (typ, "surface")

   179		   || strcmp (typ, "patch") || strcmp (typ, "hggroup")))

   180	typ = get (kids(--k), "type");

   181      endwhile

   182      if (k > 0)

   183	if (strcmp (get (kids(k), "type"), "hggroup"))

   184	  hgkids = get (kids(k), "children");

   185	  for j = 1 : length (hgkids)

   186	    hgobj = get (hgkids (j));

   187	    if (isfield (hgobj, "keylabel"))

   188	      set (hgkids(j), "keylabel", arg);

   189	      break;

   190	    endif

   191	  endfor

   192	else

   193	  set (kids(k), "keylabel", arg);

   194	endif

   195	turn_on_legend = true;

   196	if (--k == 0)

   197	  break;

   198	endif

   199      elseif (! warned)

   200	warned = true;

   201	warning ("legend: ignoring extra labels");

   202      endif

   203    else

   204      error ("legend: expecting argument to be a character string");

   205    endif

   206  endfor

   207

   208  if (turn_on_legend)

   209    set (ca, "key", "on");

   210  endif

   211

   212endfunction

   213

   214%!demo

   215%! clf

   216%! plot(1:10, 1:10, 1:10, fliplr(1:10));

   217%! title("incline is blue and decline is green");

   218%! legend({"I'm blue", "I'm green"}, "location", "east")

   219

   220%!demo

   221%! clf

   222%! plot(1:10, 1:10, 1:10, fliplr(1:10));

   223%! title("incline is blue and decline is green");

   224%! legend("I'm blue", "I'm green", "location", "east")

   225

   226%!demo

   227%! clf

   228%! plot(1:10, 1:10);

   229%! title("a very long label can sometimes cause problems");

   230%! legend({"hello world"}, "location", "northeastoutside")

   231

   232%!demo

   233%! clf

   234%! plot(1:10, 1:10);

   235%! title("a very long label can sometimes cause problems");

   236%! legend("hello world", "location", "northeastoutside")

   237

   238%!demo

   239%! clf

   240%! labels = {};

   241%! for i = 1:5

   242%!     h = plot(1:100, i + rand(100,1)); hold on;

   243%!     set (h, "color", get (gca, "colororder")(i,:))

   244%!     labels = {labels{:}, cstrcat("Signal ", num2str(i))};

   245%! endfor; hold off;

   246%! title("Signals with random offset and uniform noise")

   247%! xlabel("Sample Nr [k]"); ylabel("Amplitude [V]");

   248%! legend(labels, "location", "southoutside")

   249%! legend("boxon")

   250

   251%!demo

   252%! clf

   253%! labels = {};

   254%! for i = 1:5

   255%!     h = plot(1:100, i + rand(100,1)); hold on;

   256%!     set (h, "color", get (gca, "colororder")(i,:))

   257%!     labels = {labels{:}, cstrcat("Signal ", num2str(i))};

   258%! endfor; hold off;

   259%! title("Signals with random offset and uniform noise")

   260%! xlabel("Sample Nr [k]"); ylabel("Amplitude [V]");

   261%! legend(labels{:}, "location", "southoutside")

   262%! legend("boxon")

   263

   264%!demo

   265%! clf

   266%! x = linspace (0, 10);

   267%! plot (x, x);

   268%! hold ("on");

   269%! stem (x, x.^2, 'g')

   270%! legend ("linear");

   271%! hold ("off");

   272

   273%!demo

   274%! clf

   275%! x = linspace (0, 10);

   276%! plot (x, x, x, x.^2);

   277%! legend ("linear");

   278

   279%!demo

   280%! clf

   281%! x = linspace (0, 10);

   282%! plot (x, x, x, x.^2);

   283%! legend ("linear", "quadratic");

   284

   285%!demo

   286%! clf

   287%! bar (rand (2, 3))

   288%! ylim ([0 1.2])

   289%! legend ({"1st Bar", "2nd Bar", "3rd Bar"})

   290

   291%!demo

   292%! clf

   293%! bar (rand (2, 3))

   294%! ylim ([0 1.2])

   295%! legend ("1st Bar", "2nd Bar", "3rd Bar")