* Bug 16177 fixed [doc]: 1st example was KO in uicontrol page
[scilab.git] / scilab / modules / gui / help / en_US / uicontrol.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
3           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
4           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
5           xmlns:scilab="http://www.scilab.org" xml:id="uicontrol" xml:lang="en">
6     <refnamediv>
7         <refname>uicontrol</refname>
8         <refpurpose>create a Graphic User Interface object</refpurpose>
9     </refnamediv>
10     <refsynopsisdiv>
11         <title>Syntax</title>
12         <synopsis>
13             h = uicontrol(PropertyName,PropertyValue,...)
14             h = uicontrol(parent,PropertyName,PropertyValue,...)
15             h = uicontrol(uich)
16         </synopsis>
17     </refsynopsisdiv>
18     <refsection>
19         <title>Description</title>
20         <para>This routine creates an object in a figure.</para>
21         <para>If the handle of the figure is given (as the first parameter), the
22             uicontrol is created in this figure. If no handle is given, the uicontrol
23             is created in the current figure (which may be obtained with a call to
24             <literal>gcf()</literal>). If there is no current figure, then one is
25             created before the creation of the uicontrol.
26         </para>
27         <para>Then when the control is created, the properties given as parameters
28             are set with the corresponding values. It is equivalent to create the
29             uicontrol, and then set its properties with the <literal>set()</literal>
30             command. Nevertheless, it generally more efficient to set the properties
31             in the call to <literal>uicontrol()</literal>. Scilab
32             and all the graphic objects communicate through the property mechanism.
33             Thus, to create adapted uicontrol, one has to know the use of the property
34             fields.
35         </para>
36         <para>
37             <literal>h = uicontrol(PropertyName, PropertyValue,...)</literal>
38             creates an uicontrol and assigns the specified properties and values to
39             it. It assigns the default values to any properties you do not specify.
40             The default uicontrol style is a "Pushbutton". The default parent is the
41             current figure. See the Properties section for information about these and
42             other properties.
43         </para>
44         <para>
45             <literal>h = uicontrol(parent, PropertyName, PropertyValue,...) </literal>
46             creates a uicontrol in the object specified
47             by the handle, parent. If you also specify a different value for the
48             Parent property, the value of the Parent property takes precedence. parent
49             is the handle of a figure.
50         </para>
51         <para>
52             <literal>h = uicontrol(uich)</literal> gives focus to the uicontrol
53             specified by uich.
54         </para>
55         <para>
56             All available properties and their description are given in the
57             <link linkend="uicontrol_properties">uicontrol properties</link> help page.
58         </para>
59         <para>
60             Uicontrols rendering and properties display can be customized using
61             <link linkend="console_properties">Console properties</link>.
62         </para>
63     </refsection>
64     <refsection>
65         <title>Available styles</title>
66         <para>
67             The available styles are listed below. The <literal>style</literal> of an
68             <literal>uicontrol</literal> must be set at creation using the
69             <literal>"Style"</literal> property and can not be changed once the
70             <literal>uicontrol</literal> is created.
71         </para>
72         <itemizedlist>
73             <listitem>
74                 <para>Checkbox: a button with two states (Used for multiple independent choices).
75                 </para>
76             </listitem>
77             <listitem>
78                 <para>Edit: an editable string zone.</para>
79             </listitem>
80             <listitem>
81                 <para>Frame: a container for other uicontrols or axes.
82                 </para>
83             </listitem>
84             <listitem>
85                 <para>Image: a component where a specified image is displayed.</para>
86             </listitem>
87             <listitem>
88                 <para>
89                     Layer: a container for <literal>frame</literal> style uicontrols enabling to
90                     switch between them programmatically using the <literal>value</literal> property.
91                 </para>
92             </listitem>
93             <listitem>
94                 <para>Listbox: a control representing a list of items that can be scrolled.
95                     The items can be selected with the mouse.
96                 </para>
97             </listitem>
98             <listitem>
99                 <para>Popupmenu: a button which make a menu appear when clicked.</para>
100             </listitem>
101             <listitem>
102                 <para>Pushbutton: (default style) a rectangular button generally used to run a callback.
103                 </para>
104             </listitem>
105             <listitem>
106                 <para>
107                     Radiobutton: a button with two states. RadioButtons are intended to be mutually
108                     exclusive.
109                 </para>
110                 <para>
111                     Your code must implement mutually exclusive behavior if you do not use groups
112                     (See <literal>GroupName</literal> property in
113                     <link linkend="uicontrol_properties">uicontrol properties</link>).
114                 </para>
115             </listitem>
116             <listitem>
117                 <para>
118                     Slider: a scale control, that is a slider used to set a value in a given
119                     interval, with the mouse.
120                 </para>
121             </listitem>
122             <listitem>
123                 <para>
124                     Spinner: a component which enables the user to select/edit a value between
125                     bounds with a fixed step.
126                 </para>
127             </listitem>
128             <listitem>
129                 <para>
130                     Tab: a container for <literal>frame</literal> style uicontrols enabling to
131                     switch between them by clicking on a tab with a given title and/or icon.
132                 </para>
133                 <para>The font related properties set on the frame will be used for the tab label.</para>
134             </listitem>
135             <listitem>
136                 <para>Table: an editable table.</para>
137             </listitem>
138             <listitem>
139                 <para>Text: a text control (generally static).</para>
140             </listitem>
141         </itemizedlist>
142     </refsection>
143     <refsection>
144         <title>Examples</title>
145         <programlisting role="example"><![CDATA[
146 // Create a figure:
147 f = scf();
148
149 // Create a listbox:
150 h = uicontrol(f,'style','listbox','position', [10 10 150 160]);
151
152 // Set labels
153 h.string = "item 1|item 2|item 3";
154
155 // Set (max-min)>1 to allow multiple selection, and select items 1 and 3
156 set(h, "min",0, "max",2, "value", [1 3]);
157  ]]></programlisting>
158         <para>uicontrol function can be overloaded</para>
159         <programlisting role="example"><![CDATA[
160 // create a mlist
161 mymlist = mlist(['objid','A','B'],[],[]);
162
163 // overload set / get for objid
164 function result = %objid_uicontrol(varargin)
165   // res = uicontrol(mymlist,'A');
166   obj_tmp   = varargin(1);
167   field_tmp = varargin(2);
168   mprintf('uicontrol on an object of type %s, field = %s\n', typeof(obj_tmp), field_tmp);
169   result = %t;
170 endfunction
171
172 res = uicontrol(mymlist,'property');
173  ]]></programlisting>
174         <para>Pushbuttons or Text can have LaTeX or MathML label</para>
175         <programlisting role="example"><![CDATA[
176 // LaTeX
177 f=figure();
178 h=uicontrol(f,"style","pushbutton","string","$x^2$");
179 // MathML
180 hh=uicontrol(f,"style","pushbutton","string","<msup><mi>x</mi><mn>2</mn></msup>");
181 hh.Position = h.Position + [50, 0, 0, 0];
182 // Text
183 h=uicontrol(f,"Style","text","string","$\Gamma(s)=\int_0^\infty t^{s-1}\mathrm{e}^{-t}\,\mathrm{d}t$");
184 // If it is too little
185 h.fontsize=20
186  ]]></programlisting>
187         <programlisting role="example"><![CDATA[
188 // Include an editable table into a figure:
189 // Building a table of data:
190 params = [" " "Country" "Population [Mh]" "Temp.[°C]" ];
191 towns = ["Mexico" "Paris" "Tokyo" "Singapour"]';
192 country = ["Mexico" "France" "Japan" "Singapour"]';
193 pop  = string([22.41 11.77 33.41 4.24]');
194 temp = string([26 19 22 17]');
195 table = [params; [ towns country pop temp ]]
196
197 f = gcf();
198 clf
199 as = f.axes_size;  // [width height]
200 ut = uicontrol("style","table",..
201                "string",table,..
202                "position",[5 as(2)-100 300 87],.. // => @top left corner of figure
203                "tooltipstring","Data from majors towns")
204
205 // Modify by hand some values in the table. Then get them back from the ui:
206 matrix(ut.string,size(table))
207  ]]></programlisting>
208     </refsection>
209     <refsection role="see also">
210         <title>See also</title>
211         <simplelist type="inline">
212             <member>
213                 <link linkend="uicontrol_properties">uicontrol_properties</link>
214             </member>
215             <member>
216                 <link linkend="figure">figure</link>
217             </member>
218             <member>
219                 <link linkend="set">set</link>
220             </member>
221             <member>
222                 <link linkend="get">get</link>
223             </member>
224             <member>
225                 <link linkend="uimenu">uimenu</link>
226             </member>
227             <member>
228                 <link linkend="math_rendering_features_in_graphic">LaTeX and MathML</link>
229             </member>
230         </simplelist>
231     </refsection>
232     <refsection>
233         <title>History</title>
234         <revhistory>
235             <revision>
236                 <revnumber>5.5.0</revnumber>
237                 <revremark>
238                     <para>
239                         New styles added:
240                     </para>
241                     <itemizedlist>
242                         <listitem>Tab</listitem>
243                         <listitem>Spinner</listitem>
244                         <listitem>Layer</listitem>
245                     </itemizedlist>
246                     <para>
247                         Uicontrols rendering is now based on operating system look and feel (See <link linkend="console_properties">console properties</link>).
248                     </para>
249                     <para>
250                         Uicontrols handles display is now limited to properties used by Java rendering (See <link linkend="console_properties">console properties</link>).
251                     </para>
252                 </revremark>
253             </revision>
254         </revhistory>
255     </refsection>
256 </refentry>