1########################################################################
2##
3## Copyright (C) 2008-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  {} {} hggroup ()
28## @deftypefnx {} {} hggroup (@var{hax})
29## @deftypefnx {} {} hggroup (@dots{}, @var{property}, @var{value}, @dots{})
30## @deftypefnx {} {@var{h} =} hggroup (@dots{})
31## Create handle graphics group object with axes parent @var{hax}.
32##
33## If no parent is specified, the group is created in the current axes.
34##
35## Multiple property/value pairs may be specified for the hggroup, but they
36## must appear in pairs.  The full list of properties is documented at
37## @ref{Axes Properties}.
38##
39## The optional return value @var{h} is a graphics handle to the created
40## hggroup object.
41##
42## Programming Note: An hggroup is a way to group base graphics objects such
43## as line objects or patch objects into a single unit which can react
44## appropriately.  For example, the individual lines of a contour plot are
45## collected into a single hggroup so that they can be made visible/invisible
46## with a single command, @code{set (hg_handle, "visible", "off")}.
47##
48## @seealso{addproperty, addlistener}
49## @end deftypefn
50
51function h = hggroup (varargin)
52
53  [hax, varargin] = __plt_get_axis_arg__ ("hggroup", varargin{:});
54
55  if (isempty (hax))
56    hax = gca ();
57  endif
58
59  htmp = __go_hggroup__ (hax, varargin{:});
60
61  if (nargout > 0)
62    h = htmp;
63  endif
64
65endfunction
66
67
68%!test
69%! hf = figure ("visible", "off");
70%! unwind_protect
71%!   h = hggroup;
72%!   assert (findobj (hf, "type", "hggroup"), h);
73%!   assert (get (h, "type"), "hggroup");
74%! unwind_protect_cleanup
75%!   close (hf);
76%! end_unwind_protect
77