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