|
6146
|
1 ## Copyright (C) 2001 Laurent Mazet |
|
|
2 ## Copyright (C) 2006 John W. Eaton |
|
|
3 ## |
|
6440
|
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 |
|
7016
|
8 ## the Free Software Foundation; either version 3 of the License, or (at |
|
|
9 ## your option) any later version. |
|
6440
|
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. |
|
6146
|
15 ## |
|
|
16 ## You should have received a copy of the GNU General Public License |
|
7016
|
17 ## along with Octave; see the file COPYING. If not, see |
|
|
18 ## <http://www.gnu.org/licenses/>. |
|
6146
|
19 |
|
|
20 ## -*- texinfo -*- |
|
6450
|
21 ## @deftypefn {Function File} {} legend (@var{st1}, @var{st2}, @dots{}) |
|
6977
|
22 ## @deftypefnx {Function File} {} legend (@var{st1}, @var{st2}, @dots{}, "location", @var{pos}) |
|
6146
|
23 ## @deftypefnx {Function File} {} legend (@var{matstr}) |
|
6977
|
24 ## @deftypefnx {Function File} {} legend (@var{matstr}, "location", @var{pos}) |
|
6146
|
25 ## @deftypefnx {Function File} {} legend (@var{cell}) |
|
6977
|
26 ## @deftypefnx {Function File} {} legend (@var{cell}, "location", @var{pos}) |
|
6146
|
27 ## @deftypefnx {Function File} {} legend ('@var{func}') |
|
|
28 ## |
|
6895
|
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. |
|
6146
|
34 ## |
|
6895
|
35 ## The optional parameter @var{pos} specifies the location of the legend |
|
|
36 ## as follows: |
|
6146
|
37 ## |
|
6977
|
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 |
|
6146
|
58 ## @end multitable |
|
|
59 ## |
|
7001
|
60 ## Some specific functions are directly available using @var{func}: |
|
6146
|
61 ## |
|
|
62 ## @table @code |
|
6895
|
63 ## @item "show" |
|
6146
|
64 ## Show legends from the plot |
|
6895
|
65 ## @item "hide" |
|
6146
|
66 ## @itemx off |
|
|
67 ## Hide legends from the plot |
|
6895
|
68 ## @item "boxon" |
|
6146
|
69 ## Draw a box around legends |
|
6895
|
70 ## @item "boxoff" |
|
6146
|
71 ## Withdraw the box around legends |
|
6895
|
72 ## @item "left" |
|
6146
|
73 ## Text is to the left of the keys |
|
6895
|
74 ## @item "right" |
|
6146
|
75 ## Text is to the right of the keys |
|
|
76 ## @end table |
|
|
77 ## @end deftypefn |
|
|
78 |
|
|
79 ## PKG_ADD mark_as_command legend |
|
|
80 |
|
|
81 function legend (varargin) |
|
|
82 |
|
6257
|
83 nargs = nargin; |
|
6146
|
84 |
|
6257
|
85 ca = gca (); |
|
6146
|
86 |
|
|
87 if (nargs > 0) |
|
|
88 pos = varargin{nargs}; |
|
|
89 if (isnumeric (pos) && isscalar (pos) && round (pos) == pos) |
|
6395
|
90 if (pos >= -1 && pos <= 4) |
|
6257
|
91 set (ca, "keypos", pos); |
|
6146
|
92 nargs--; |
|
|
93 else |
|
|
94 error ("legend: invalid position specified"); |
|
|
95 endif |
|
|
96 endif |
|
|
97 endif |
|
6977
|
98 |
|
|
99 if (nargs > 1) |
|
|
100 pos = varargin{nargs-1}; |
|
|
101 if (strcmpi (pos, "location") && ischar (str)) |
|
|
102 set (ca, "keypos", str); |
|
|
103 nargs -= 2; |
|
|
104 endif |
|
|
105 endif |
|
6146
|
106 |
|
6257
|
107 kids = get (ca, "children"); |
|
|
108 nkids = numel (kids); |
|
|
109 k = 1; |
|
|
110 turn_on_legend = false; |
|
|
111 |
|
6146
|
112 if (nargs == 1) |
|
|
113 arg = varargin{1}; |
|
|
114 if (ischar (arg)) |
|
|
115 if (rows (arg) == 1) |
|
|
116 str = tolower (deblank (arg)); |
|
|
117 switch (str) |
|
|
118 case {"off", "hide"} |
|
6257
|
119 set (ca, "key", "off"); |
|
6146
|
120 case "show" |
|
6257
|
121 set (ca, "key", "on"); |
|
6146
|
122 case "toggle" |
|
6257
|
123 val = get (ca, "key"); |
|
|
124 if (strcmp (val, "on")) |
|
|
125 set (ca, "key", "off"); |
|
|
126 else |
|
|
127 set (ca, "key", "on"); |
|
|
128 endif |
|
6146
|
129 case "boxon" |
|
6257
|
130 set (ca, "key", "on", "keybox", "on"); |
|
6146
|
131 case "boxoff" |
|
6257
|
132 set (ca, "keybox", "off"); |
|
6146
|
133 otherwise |
|
6257
|
134 while (k <= nkids && ! strcmp (get (kids(k), "type"), "line")) |
|
|
135 k++; |
|
|
136 endwhile |
|
|
137 if (k <= nkids) |
|
|
138 turn_on_legend = true; |
|
|
139 set (kids(k), "keylabel", arg); |
|
|
140 else |
|
|
141 warning ("legend: ignoring extra labels"); |
|
|
142 endif |
|
6146
|
143 endswitch |
|
|
144 nargs--; |
|
|
145 else |
|
|
146 varargin = cellstr (arg); |
|
6740
|
147 nargs = numel (varargin); |
|
6146
|
148 endif |
|
|
149 elseif (iscellstr (arg)) |
|
|
150 varargin = arg; |
|
|
151 nargs = numel (varargin); |
|
|
152 else |
|
|
153 error ("legend: expecting argument to be a character string"); |
|
|
154 endif |
|
|
155 endif |
|
|
156 |
|
6272
|
157 if (nargs > 0) |
|
|
158 have_data = false; |
|
|
159 for i = 1:nkids |
|
|
160 if (strcmp (get (kids(k), "type"), "line")) |
|
|
161 have_data = true; |
|
|
162 break; |
|
|
163 endif |
|
|
164 endfor |
|
|
165 if (! have_data) |
|
|
166 warning ("legend: plot data is empty; setting key labels has no effect"); |
|
|
167 endif |
|
6147
|
168 endif |
|
|
169 |
|
6575
|
170 warned = false; |
|
6146
|
171 for i = 1:nargs |
|
|
172 arg = varargin{i}; |
|
|
173 if (ischar (arg)) |
|
6257
|
174 while (k <= nkids && ! strcmp (get (kids(k), "type"), "line")) |
|
|
175 k++; |
|
|
176 endwhile |
|
|
177 if (k <= nkids) |
|
|
178 set (kids(k), "keylabel", arg); |
|
|
179 turn_on_legend = true; |
|
6450
|
180 k++; |
|
6257
|
181 elseif (! warned) |
|
|
182 warned = true; |
|
|
183 warning ("legend: ignoring extra labels"); |
|
|
184 endif |
|
6146
|
185 else |
|
|
186 error ("legend: expecting argument to be a character string"); |
|
|
187 endif |
|
|
188 endfor |
|
|
189 |
|
6257
|
190 if (turn_on_legend) |
|
|
191 set (ca, "key", "on"); |
|
6146
|
192 endif |
|
|
193 |
|
|
194 endfunction |
|
|
195 |
|
|
196 %!demo |
|
|
197 %! close all; |
|
|
198 %! plot(1:10, 1:10); |
|
|
199 %! title("a very long label can sometimes cause problems"); |
|
6977
|
200 %! legend({"hello world"}, "location", "northeastoutside") |
|
6146
|
201 |
|
|
202 %!demo |
|
|
203 %! close all; |
|
|
204 %! labels = {}; |
|
|
205 %! for i = 1:5 |
|
|
206 %! plot(1:100, i + rand(100,1)); hold on; |
|
|
207 %! labels = {labels{:}, strcat("Signal ", num2str(i))}; |
|
|
208 %! endfor; hold off; |
|
|
209 %! title("Signals with random offset and uniform noise") |
|
|
210 %! xlabel("Sample Nr [k]"); ylabel("Amplitude [V]"); |
|
6977
|
211 %! legend(labels, "location", "southoutside") |
|
6146
|
212 %! legend("boxon") |
