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