1######################################################################## 2## 3## Copyright (C) 1993-2021 The Octave Project Developers 4## 5## See the file COPYRIGHT.md in the top-level directory of this 6## distribution or <https://octave.org/copyright/>. 7## 8## This file is part of Octave. 9## 10## Octave is free software: you can redistribute it and/or modify it 11## under the terms of the GNU General Public License as published by 12## the Free Software Foundation, either version 3 of the License, or 13## (at your option) any later version. 14## 15## Octave is distributed in the hope that it will be useful, but 16## WITHOUT ANY WARRANTY; without even the implied warranty of 17## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18## GNU General Public License for more details. 19## 20## You should have received a copy of the GNU General Public License 21## along with Octave; see the file COPYING. If not, see 22## <https://www.gnu.org/licenses/>. 23## 24######################################################################## 25 26## -*- texinfo -*- 27## @deftypefn {} {} title (@var{string}) 28## @deftypefnx {} {} title (@var{string}, @var{prop}, @var{val}, @dots{}) 29## @deftypefnx {} {} title (@var{hax}, @dots{}) 30## @deftypefnx {} {@var{h} =} title (@dots{}) 31## Specify the string used as a title for the current axis. 32## 33## An optional list of @var{property}/@var{value} pairs can be used to change 34## the appearance of the created title text object. 35## 36## If the first argument @var{hax} is an axes or legend handle, then add a 37## title to this object, rather than the current axes returned by @code{gca}. 38## 39## The optional return value @var{h} is a graphics handle to the created text 40## object. 41## @seealso{xlabel, ylabel, zlabel, text} 42## @end deftypefn 43 44function h = title (varargin) 45 46 [hax, varargin, nargin] = __plt_get_axis_arg__ ("title", varargin{:}); 47 48 if (isempty (hax)) 49 if (! isempty (varargin) && isscalar (varargin{1}) 50 && ishghandle (varargin{1}) 51 && strcmp (get (varargin{1}, "tag"), "legend")) 52 hax = varargin{1}; 53 varargin(1) = []; 54 nargin--; 55 else 56 hax = gca (); 57 endif 58 endif 59 60 if (rem (nargin, 2) != 1) 61 print_usage (); 62 endif 63 64 htmp = __axis_label__ (hax, "title", varargin{:}); 65 66 if (nargout > 0) 67 h = htmp; 68 endif 69 70endfunction 71 72 73%!demo 74%! clf; 75%! title ("Test Title Text"); 76 77%!demo 78%! clf; 79%! title ({"Multi-line"; "Title"; "Text"}); 80 81%!demo 82%! clf; 83%! plot3 ([0,1], [0,1], [0,1]); 84%! title ("Test FontSize Property", "fontsize", 16); 85 86%!test 87%! hf = figure ("visible", "off"); 88%! unwind_protect 89%! title ("Test Title Text"); 90%! h = get (gca, "title"); 91%! assert (get (h, "string"), "Test Title Text"); 92%! unwind_protect_cleanup 93%! close (hf); 94%! end_unwind_protect 95 96%!test 97%! hf = figure ("visible", "off"); 98%! unwind_protect 99%! title ({"Multi-line"; "Title"; "Text"}); 100%! h = get (gca, "title"); 101%! assert (get (h, "string"), {"Multi-line"; "Title"; "Text"}); 102%! unwind_protect_cleanup 103%! close (hf); 104%! end_unwind_protect 105 106%!test 107%! hf = figure ("visible", "off"); 108%! unwind_protect 109%! set (gca, "fontsize", 5, "titlefontsizemultiplier", 3); 110%! ht = title ("title_string", "color", "r"); 111%! assert (get (ht, "fontsize"), 15); 112%! assert (get (ht, "color"), [1 0 0]); 113%! unwind_protect_cleanup 114%! close (hf); 115%! end_unwind_protect 116 117%!test 118%! hf = figure ("visible", "off"); 119%! unwind_protect 120%! plot3 ([0,1], [0,1], [0,1]); 121%! title ("Test FontSize Property", "fontsize", 16); 122%! h = get (gca, "title"); 123%! assert (get (h, "string"), "Test FontSize Property"); 124%! assert (get (h, "fontsize"), 16); 125%! unwind_protect_cleanup 126%! close (hf); 127%! end_unwind_protect 128 129%!test <*49469> 130%! hf = figure ("visible", "off"); 131%! unwind_protect 132%! ht = title ("Test FontSize Property"); 133%! set (gca, "fontname", "Liberation Serif") 134%! set (gca, "fontsize", 13) 135%! assert (get (ht, "fontname"), "Liberation Serif"); 136%! assert (get (ht, "fontsize"), 13 * get (gca, "titlefontsizemultiplier")); 137%! unwind_protect_cleanup 138%! close (hf); 139%! end_unwind_protect 140 141%!test <*57372> 142%! hf = figure ("visible", "off"); 143%! unwind_protect 144%! plot (1:10); 145%! hl = legend ("legend text"); 146%! ht = title (hl, "Legend Title"); 147%! assert (get (ht, "string"), "Legend Title"); 148%! assert (get (ht, "parent"), hl); 149%! unwind_protect_cleanup 150%! close (hf); 151%! end_unwind_protect 152