1########################################################################
2##
3## Copyright (C) 2012-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{hui} =} uicontrol (@var{property}, @var{value}, @dots{})
28## @deftypefnx {} {@var{hui} =} uicontrol (@var{parent}, @var{property}, @var{value}, @dots{})
29## @deftypefnx {} {} uicontrol (@var{h})
30##
31## Create a uicontrol object and return a handle to it.
32##
33## A uicontrol object is used to create simple interactive controls such as
34## push buttons, checkboxes, edit and list controls.
35##
36## If @var{parent} is omitted then a uicontrol for the current figure is
37## created.  If no figure is available, a new figure is created first.
38##
39## If @var{parent} is given then a uicontrol relative to @var{parent} is
40## created.
41##
42## Any provided property value pairs will override the default values of the
43## created uicontrol object.
44##
45## The full list of properties is documented at @ref{Uicontrol Properties}.
46##
47## The type of uicontrol created is specified by the @var{style} property.  If
48## no style property is provided, a push button will be created.
49##
50## Valid styles for uicontrol are:
51##
52## @table @asis
53## @item @qcode{"checkbox"}
54## Create a checkbox control that allows user on/off selection.
55##
56## @item @qcode{"edit"}
57## Create an edit control that allows user input of single or multiple lines
58## of text.
59##
60## @item @qcode{"listbox"}
61## Create a listbox control that displays a list of items and allows user
62## selection of single or multiple items.
63##
64## @item @qcode{"popupmenu"}
65## Create a popupmenu control that displays a list of options that can be
66## selected when the user clicks on the control.
67##
68## @item @qcode{"pushbutton"}
69## Create a push button control that allows user to press to cause an action.
70##
71## @item @qcode{"radiobutton"}
72## Create a radio button control intended to be used for mutually exclusive
73## input in a group of radiobutton controls.
74##
75## @item @qcode{"slider"}
76## Create a slider control that allows user selection from a range of values
77## by sliding knob on the control.
78##
79## @item @qcode{"text"}
80## Create a static text control to display single or multiple lines of text.
81##
82## @item @qcode{"togglebutton"}
83## Create a toggle button control that appears like a push button but allows
84## the user to select between two states.
85##
86## @end table
87##
88## Examples:
89##
90## @example
91## @group
92## ## Create figure and panel on it
93## f = figure;
94## ## Create a button (default style)
95## b1 = uicontrol (f, "string", "A Button", ...
96##                    "position", [10 10 150 40]);
97## ## Create an edit control
98## e1 = uicontrol (f, "style", "edit", "string", "editable text", ...
99##                    "position", [10 60 300 40]);
100## ## Create a checkbox
101## c1 = uicontrol (f, "style", "checkbox", "string", "a checkbox", ...
102##                    "position", [10 120 150 40]);
103## @end group
104## @end example
105##
106## When called with a single argument @var{h} which is a handle to an existing
107## uicontrol object, switch the keyboard focus to the specified
108## uicontrol.  As a result, the uicontrol object will receive keyboard
109## events that can be processed using the @qcode{"keypressfcn"} callback.
110## @seealso{figure, uipanel}
111## @end deftypefn
112
113function hui = uicontrol (varargin)
114
115  if (nargin == 1 && isgraphics (varargin{1}, "uicontrol"))
116    set (varargin{1}, "__focus__", "on");
117    return;
118  endif
119
120  [h, args] = __uiobject_split_args__ ("uicontrol", varargin,
121                                       {"figure", "uipanel", "uibuttongroup"});
122  htmp = __go_uicontrol__ (h, args{:});
123
124  if (nargout > 0)
125    hui = htmp;
126  endif
127
128endfunction
129