1########################################################################
2##
3## Copyright (C) 2016-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  {} {@var{h} =} dialog ()
28## @deftypefnx {} {@var{h} =} dialog ("@var{property}", @var{value}, @dots{})
29##
30## Create an empty modal dialog window to which other uicontrols can be added.
31##
32## The dialog box is a figure object with properties as recommended for a
33## dialog box.
34##
35## The default properties differing from a figure are:
36##
37## @table @asis
38## @item buttondownfcn
39## @code{if isempty (allchild(gcbf)), close (gcbf), endif}
40##
41## @item colormap
42## []
43##
44## @item color
45## defaultuicontrolbackgroundcolor
46##
47## @item dockcontrols
48## off
49##
50## @item handlevisibility
51## callback
52##
53## @item integerhandle
54## off
55##
56## @item inverthardcopy
57## off
58##
59## @item menubar
60## none
61##
62## @item numbertitle
63## off
64##
65## @item paperpositionmode
66## auto
67##
68## @item resize
69## off
70##
71## @item windowstyle
72## modal
73##
74## @end table
75##
76##
77## Multiple property-value pairs may be specified for the dialog object, but
78## they must appear in pairs.  The full list of properties is documented at
79## @ref{Figure Properties}.
80##
81## The return value @var{h} is a graphics handle to the created figure.
82##
83## Example:
84##
85## @example
86## @group
87## ## create an empty dialog window titled "Dialog Example"
88## h = dialog ("name", "Dialog Example");
89##
90## ## create a button (default style)
91## b = uicontrol (h, "string", "OK",
92##                   "position", [10 10 150 40],
93##                   "callback", "delete (gcf)");
94##
95## ## wait for dialog to resume or close
96## uiwait (h);
97## @end group
98## @end example
99##
100## @seealso{errordlg, msgbox, questdlg, warndlg, figure, uiwait}
101## @end deftypefn
102
103function h = dialog (varargin)
104
105  h = figure ( ...
106    "buttondownfcn", "if isempty (allchild (gcbf)), close (gcbf), endif",
107    "color", get (0,"defaultuicontrolbackgroundcolor"),
108    "colormap", [],
109    "dockcontrols", "off",
110    "handlevisibility", "callback",
111    "integerhandle", "off",
112    "inverthardcopy", "off",
113    "menubar", "none",
114    "numbertitle", "off",
115    "paperpositionmode", "auto",
116    "resize", "off",
117    "toolbar", "none",
118    "windowstyle", "modal",
119    varargin{:});
120
121endfunction
122
123## No BIST tests.  This function just dispatches to figure().
124%!assert (1)
125