1 ## Copyright (C) 2007-2012 John W. Eaton
3 ## This file is part of Octave.
5 ## Octave is free software; you can redistribute it and/or modify it
6 ## under the terms of the GNU General Public License as published by
7 ## the Free Software Foundation; either version 3 of the License, or (at
8 ## your option) any later version.
10 ## Octave is distributed in the hope that it will be useful, but
11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 ## General Public License for more details.
15 ## You should have received a copy of the GNU General Public License
16 ## along with Octave; see the file COPYING. If not, see
17 ## <http://www.gnu.org/licenses/>.
20 ## @deftypefn {Function File} {} text (@var{x}, @var{y}, @var{label})
21 ## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{z}, @var{label})
22 ## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{label}, @var{p1}, @var{v1}, @dots{})
23 ## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{z}, @var{label}, @var{p1}, @var{v1}, @dots{})
24 ## @deftypefnx {Function File} {@var{h} =} text (@dots{})
25 ## Create a text object with text @var{label} at position @var{x},
26 ## @var{y}, @var{z} on the current axes. Property-value pairs following
27 ## @var{label} may be used to specify the appearance of the text.
29 ## The optional return value @var{h} is a graphics handle to the created text
35 function h = text (varargin)
40 if (nargs > 2 && isnumeric (varargin{1}) && isnumeric (varargin{2}))
45 if (nargin > 3 && isnumeric (varargin{3}))
53 label = varargin{offset};
54 varargin(1:offset) = [];
59 if (ischar (label) || isnumeric (label))
61 if (nx > 1 && nt == 1)
62 ## Mutiple text objects with same string
63 label = repmat ({label}, [nx, 1]);
65 elseif (nx > 1 && nt == nx)
66 ## Mutiple text objects with different strings
67 label = cellstr (label);
68 elseif (ischar (label))
69 ## Single text object with one or more lines
72 elseif (iscell (label))
74 if (nx > 1 && nt == 1)
75 label = repmat ({label}, [nx, 1]);
77 elseif (! (nx > 1 && nt == nx))
82 error ("text: expecting LABEL to be a character string or cell array of character strings");
91 if (rem (numel (varargin), 2) == 0)
93 if (nx == ny && nx == nz && (nt == nx || nt == 1 || nx == 1))
94 pos = [x(:), y(:), z(:)];
98 ## TODO - Modify __go_text__() to accept cell-strings
99 tmp = __go_text__ (ca, "string", "foobar",
102 set (tmp, "string", label{1});
105 tmp(n) = __go_text__ (ca, "string", label{n},
107 "position", pos(n,:));
109 __request_drawnow__ ();
111 error ("text: dimension mismatch for coordinates and LABEL");
113 elseif (nt == nx || nt == 1 || nx == 1)
114 error ("text: dimension mismatch for coordinates");
116 error ("text: mismatch betwween coordinates and strings");
131 %! ha = {"left", "center", "right"};
132 %! va = {"bottom", "middle", "top"};
133 %! x = [0.25 0.5 0.75];
134 %! y = [0.25 0.5 0.75];
136 %! for nh = 1:numel(ha)
137 %! for nv = 1:numel(va)
138 %! text (x(nh), y(nv), "Hello World", ...
139 %! "rotation", t, ...
140 %! "horizontalalignment", ha{nh}, ...
141 %! "verticalalignment", va{nv});
145 %! set (gca, "xtick", [0.25, 0.5, 0.75], ...
146 %! "xticklabel", ha, ...
147 %! "ytick", [0.25, 0.5, 0.75], ...
148 %! "yticklabel", va);
150 %! xlabel ("horizontal alignment");
151 %! ylabel ("vertical alignment");
152 %! title ("text alignment and rotation (0:30:360 degrees)")
156 %! h = mesh (peaks, "edgecolor", 0.7 * [1 1 1], ...
157 %! "facecolor", "none", ...
160 %! text (25, 25, 0, "Vertical Alignment = Bottom", ...
161 %! "rotation", t, ...
162 %! "horizontalalignment", "left", ...
163 %! "verticalalignment", "bottom");
165 %! caxis ([-100 100]);
166 %! title ("Vertically Aligned at Bottom");
171 %! title (["1st title";"2nd title"]);
172 %! xlabel (["1st xlabel";"2nd xlabel"]);
173 %! ylabel (["1st ylabel";"2nd ylabel"]);
174 %! text (4, 4, {"Hello", "World"}, ...
175 %! "horizontalalignment", "center", ...
176 %! "verticalalignment", "middle");
181 %! h = mesh (peaks, "edgecolor", 0.7 * [1 1 1], ...
182 %! "facecolor", "none", ...
184 %! title (["1st title";"2nd title"]);
185 %! xlabel (["1st xlabel";"2nd xlabel"]);
186 %! ylabel (["1st ylabel";"2nd ylabel"]);
187 %! zlabel (["1st zlabel";"2nd zlabel"]);
188 %! text (0, 0, 5, {"Hello", "World"}, ...
189 %! "horizontalalignment", "center", ...
190 %! "verticalalignment", "middle");
192 %! plot3 (0, 0, 5, "+k");
196 %! h = text (0.5, 0.3, "char");
197 %! assert ("char", class (get (h, "string")));
198 %! h = text (0.5, 0.4, ["char row 1"; "char row 2"]);
199 %! assert ("char", class (get (h, "string")));
200 %! h = text (0.5, 0.6, {"cell2str (1,1)", "cell2str (1,2)"; "cell2str (2,1)", "cell2str (2,2)"});
201 %! assert ("cell", class (get (h, "string")));
202 %! h = text (0.5, 0.8, "foobar");
203 %! set (h, "string", 1:3);
204 %! h = text ([0.1, 0.1], [0.3, 0.4], "one string & two objects");
205 %! assert ("char", class (get (h(1), "string")));
206 %! assert ("char", class (get (h(2), "string")));
207 %! h = text ([0.1, 0.1], [0.5, 0.6], {"one cellstr & two objects"});
208 %! assert ("cell", class (get (h(1), "string")));
209 %! assert ("cell", class (get (h(2), "string")));
210 %! h = text ([0.1, 0.1], [0.7, 0.8], {"cellstr 1 object 1", "cellstr 2 object 2"});
211 %! assert ("char", class (get (h(1), "string")));
212 %! assert ("char", class (get (h(2), "string")));
213 %! h = text ([0.1, 0.1], [0.1, 0.2], ["1st string & 1st object"; "2nd string & 2nd object"]);
214 %! assert ("char", class (get (h(1), "string")));
215 %! assert ("char", class (get (h(2), "string")));
216 %! h = text (0.7, 0.6, "single string");
217 %! assert ("char", class (get (h, "string")));
218 %! h = text (0.7, 0.5, {"single cell-string"});
219 %! assert ("cell", class (get (h, "string")));
225 %! hf = figure ("visible", "off");
227 %! h = text (0.5, 0.3, "char");
228 %! assert ("char", class (get (h, "string")));
229 %! h = text (0.5, 0.4, ["char row 1"; "char row 2"]);
230 %! assert ("char", class (get (h, "string")));
231 %! h = text (0.5, 0.6, {"cell2str (1,1)", "cell2str (1,2)"; "cell2str (2,1)", "cell2str (2,2)"});
232 %! assert ("cell", class (get (h, "string")));
233 %! h = text (0.5, 0.8, "foobar");
234 %! set (h, "string", 1:3);
235 %! h = text ([0.1, 0.1], [0.3, 0.4], "one string & two objects");
236 %! assert ("char", class (get (h(1), "string")));
237 %! assert ("char", class (get (h(2), "string")));
238 %! h = text ([0.1, 0.1], [0.5, 0.6], {"one cellstr & two objects"});
239 %! assert ("cell", class (get (h(1), "string")));
240 %! assert ("cell", class (get (h(2), "string")));
241 %! h = text ([0.1, 0.1], [0.7, 0.8], {"cellstr 1 object 1", "cellstr 2 object 2"});
242 %! assert ("char", class (get (h(1), "string")));
243 %! assert ("char", class (get (h(2), "string")));
244 %! h = text ([0.1, 0.1], [0.1, 0.2], ["1st string & 1st object"; "2nd string & 2nd object"]);
245 %! assert ("char", class (get (h(1), "string")));
246 %! assert ("char", class (get (h(2), "string")));
247 %! h = text (0.7, 0.6, "single string");
248 %! assert ("char", class (get (h, "string")));
249 %! h = text (0.7, 0.5, {"single cell-string"});
250 %! assert ("cell", class (get (h, "string")));
251 %! unwind_protect_cleanup
253 %! end_unwind_protect