octave_packages/m/plot/text.m

   1 ## Copyright (C) 2007-2012 John W. Eaton
   2 ##
   3 ## This file is part of Octave.
   4 ##
   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.
   9 ##
  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.
  14 ##
  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/>.
  18
  19 ## -*- texinfo -*-
  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.
  28 ##
  29 ## The optional return value @var{h} is a graphics handle to the created text
  30 ## object.
  31 ## @end deftypefn
  32
  33 ## Author: jwe
  34
  35 function h = text (varargin)
  36
  37   nargs = nargin;
  38   offset = 0;
  39
  40   if (nargs > 2 && isnumeric (varargin{1}) && isnumeric (varargin{2}))
  41     x = varargin{1};
  42     y = varargin{2};
  43     offset = 3;
  44
  45     if (nargin > 3 && isnumeric (varargin{3}))
  46       z = varargin{3};
  47       offset = 4;
  48     else
  49       z = zeros (size (x));
  50       offset = 3;
  51     endif
  52
  53     label = varargin{offset};
  54     varargin(1:offset) = [];
  55
  56     nx = numel (x);
  57     ny = numel (y);
  58     nz = numel (z);
  59     if (ischar (label) || isnumeric (label))
  60       nt = size (label, 1);
  61       if (nx > 1 && nt == 1)
  62         ## Mutiple text objects with same string
  63         label = repmat ({label}, [nx, 1]);
  64         nt = nx;
  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
  70         label = {label};
  71       endif
  72     elseif (iscell (label))
  73       nt = numel (label);
  74       if (nx > 1 && nt == 1)
  75         label = repmat ({label}, [nx, 1]);
  76         nt = nx;
  77       elseif (! (nx > 1 && nt == nx))
  78         label = {label};
  79         nt = 1;
  80       endif
  81     else
  82       error ("text: expecting LABEL to be a character string or cell array of character strings");
  83     endif
  84   else
  85     x = y = z = 0;
  86     nx = ny = nz = 1;
  87     label = {""};
  88     nt = 1;
  89   endif
  90
  91   if (rem (numel (varargin), 2) == 0)
  92
  93     if (nx == ny && nx == nz && (nt == nx || nt == 1 || nx == 1))
  94       pos = [x(:), y(:), z(:)];
  95       ca = gca ();
  96       tmp = zeros (nt, 1);
  97       if (nx == 1)
  98         ## TODO - Modify __go_text__() to accept cell-strings
  99         tmp = __go_text__ (ca, "string", "foobar",
 100                            varargin{:},
 101                            "position", pos);
 102         set (tmp, "string", label{1});
 103       elseif (nt == nx)
 104         for n = 1:nt
 105           tmp(n) = __go_text__ (ca, "string", label{n},
 106                                 varargin{:},
 107                                 "position", pos(n,:));
 108         endfor
 109         __request_drawnow__ ();
 110       else
 111         error ("text: dimension mismatch for coordinates and LABEL");
 112       endif
 113     elseif (nt == nx || nt == 1 || nx == 1)
 114       error ("text: dimension mismatch for coordinates");
 115     else
 116       error ("text: mismatch betwween coordinates and strings");
 117     endif
 118
 119     if (nargout > 0)
 120       h = tmp;
 121     endif
 122
 123   else
 124     print_usage ();
 125   endif
 126
 127 endfunction
 128
 129 %!demo
 130 %! clf
 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];
 135 %! for t = 0:30:359;
 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});
 142 %!     endfor
 143 %!   endfor
 144 %! endfor
 145 %! set (gca, "xtick", [0.25, 0.5, 0.75], ...
 146 %!           "xticklabel", ha, ...
 147 %!           "ytick", [0.25, 0.5, 0.75], ...
 148 %!           "yticklabel", va);
 149 %! axis ([0 1 0 1]);
 150 %! xlabel ("horizontal alignment");
 151 %! ylabel ("vertical alignment");
 152 %! title ("text alignment and rotation (0:30:360 degrees)")
 153
 154 %!demo
 155 %! clf
 156 %! h = mesh (peaks, "edgecolor", 0.7 * [1 1 1], ...
 157 %!                  "facecolor", "none", ...
 158 %!                  "facealpha", 0);
 159 %! for t = 0:45:359;
 160 %!   text (25, 25, 0, "Vertical Alignment = Bottom", ...
 161 %!                    "rotation", t, ...
 162 %!                    "horizontalalignment", "left", ...
 163 %!                    "verticalalignment", "bottom");
 164 %! endfor
 165 %! caxis ([-100 100]);
 166 %! title ("Vertically Aligned at Bottom");
 167
 168 %!demo
 169 %! clf
 170 %! axis ([0 8 0 8]);
 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");
 177 %! grid on
 178
 179 %!demo
 180 %! clf
 181 %! h = mesh (peaks, "edgecolor", 0.7 * [1 1 1], ...
 182 %!                  "facecolor", "none", ...
 183 %!                  "facealpha", 0);
 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");
 191 %! hold on;
 192 %! plot3 (0, 0, 5, "+k");
 193
 194 %!demo
 195 %! clf
 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")));
 220 %! xlabel (1:2);
 221 %! ylabel (1:2);
 222 %! title (1:2);
 223
 224 %!test
 225 %! hf = figure ("visible", "off");
 226 %! unwind_protect
 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
 252 %!   close (hf);
 253 %! end_unwind_protect
 254