uicontrol: Fix online help syntax
[scilab.git] / scilab / modules / gui / help / en_US / uicontrol.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="uicontrol" xml:lang="en"
3           xmlns="http://docbook.org/ns/docbook"
4           xmlns:xlink="http://www.w3.org/1999/xlink"
5           xmlns:svg="http://www.w3.org/2000/svg"
6           xmlns:ns4="http://www.w3.org/1999/xhtml"
7           xmlns:mml="http://www.w3.org/1998/Math/MathML"
8           xmlns:db="http://docbook.org/ns/docbook">
9
10   <refnamediv>
11     <refname>uicontrol</refname>
12
13     <refpurpose>create a Graphic User Interface object</refpurpose>
14   </refnamediv>
15
16   <refsynopsisdiv>
17     <title>Calling Sequence</title>
18
19     <synopsis>
20     h = uicontrol(PropertyName,PropertyValue,...)
21     h = uicontrol(parent,PropertyName,PropertyValue,...)
22     h = uicontrol(uich)
23     </synopsis>
24   </refsynopsisdiv>
25
26   <refsection>
27     <title>Description</title>
28
29     <para>This routine creates an object in a figure.</para>
30
31     <para>If the handle of the figure is given (as the first parameter), the
32     uicontrol is created in this figure. If no handle is given, the uicontrol
33     is created in the current figure (which may be obtained with a call to
34     <literal>gcf()</literal>). If there is no current figure, then one is
35     created before the creation of the uicontrol.</para>
36
37     <para>Then when the control is created, the properties given as parameters
38     are set with the corresponding values. It is equivalent to create the
39     uicontrol, and then set its properties with the <literal>set()</literal>
40     command. Nevertheless, it generally more efficient to set the properties
41     in the call to <literal>uicontrol()</literal>. This is particularly true
42     concerning the "Style" property. Indeed, the default value for this
43     property is "Pushbutton". So if you do not set it at creation time, a
44     button will be created, and will be transformed to another uicontrol when
45     you call the <literal>set(h, "Style", ... )</literal> instruction. Scilab
46     and all the graphic objects communicate through the property mechanism.
47     Thus, to create adapted uicontrol, one has to know the use of the property
48     fields.</para>
49
50     <para><literal>h = uicontrol(PropertyName, PropertyValue,...)</literal>
51     creates an uicontrol and assigns the specified properties and values to
52     it. It assigns the default values to any properties you do not specify.
53     The default uicontrol style is a "Pushbutton". The default parent is the
54     current figure. See the Properties section for information about these and
55     other properties.</para>
56
57     <para><literal>h = uicontrol(parent, PropertyName,
58     PropertyValue,...)</literal> creates a uicontrol in the object specified
59     by the handle, parent. If you also specify a different value for the
60     Parent property, the value of the Parent property takes precedence. parent
61     is the handle of a figure.</para>
62
63     <para><literal>h = uicontrol(uich)</literal> gives focus to the uicontrol
64     specified by uich.</para>
65   </refsection>
66
67   <refsection>
68     <title>Properties</title>
69
70     <variablelist>
71       <varlistentry>
72         <term>BackgroundColor</term>
73
74         <listitem>
75           <para>[1,3] real vector or string</para>
76
77           <para>Background color of the uicontrol. A color is specified as
78           Red, Green and Blue values. Those values are real in [0,1]. The
79           color can be given as a real vector, ie [R,G,B] or a string where
80           each value is separated by a "|", ie "R|G|B".</para>
81         </listitem>
82       </varlistentry>
83
84       <varlistentry>
85         <term>Callback</term>
86
87         <listitem>
88           <para>String</para>
89
90           <para>Instruction evaluated by the Scilab interpreter when an
91           uicontrol is activated. (for example when you click on a
92           button).</para>
93         </listitem>
94       </varlistentry>
95
96       <varlistentry>
97         <term>Callback_Type</term>
98
99         <listitem>
100           <para>Integer</para>
101
102           <para>The type of callback transmitted to the uicontrol.</para>
103           <itemizedlist>
104             <listitem><para><literal>-1</literal> none (callback desactivated)</para></listitem>
105             <listitem><para><literal>0</literal> a Scilab instruction</para></listitem>
106             <listitem><para><literal>1</literal> a C or a Fortran function</para></listitem>
107             <listitem><para><literal>2</literal> a Scilab function</para></listitem>
108           </itemizedlist>
109         </listitem>
110       </varlistentry>
111
112       <varlistentry>
113         <term>Enable</term>
114
115         <listitem>
116           <para>{on} | off</para>
117
118           <para>Enable or disable the uicontrol. If this property is set to <literal>"on"</literal> (default), the uicontrol is operational, 
119           but if this property is set to <literal>"off"</literal>, the uicontrol will not respond to the mouse actions and will be grayed out.</para>
120         </listitem>
121       </varlistentry>
122
123       <varlistentry>
124         <term>FontAngle</term>
125
126         <listitem>
127           <para>{normal} | italic | oblique</para>
128
129           <para>For a control containing some text, this property sets the
130           slant of the font.</para>
131         </listitem>
132       </varlistentry>
133
134       <varlistentry>
135         <term>FontSize</term>
136
137         <listitem>
138           <para>Scalar</para>
139
140           <para>For a control containing some text, this property sets the
141           size of the font in FontUnits.</para>
142         </listitem>
143       </varlistentry>
144
145       <varlistentry>
146         <term>FontUnits</term>
147
148         <listitem>
149           <para>{points} | pixels | normalized</para>
150
151           <para>For a control containing some text, this property sets the
152           units with which the FontSize is specified.</para>
153         </listitem>
154       </varlistentry>
155
156       <varlistentry>
157         <term>FontWeight</term>
158
159         <listitem>
160           <para>light | {normal} | demi | bold</para>
161
162           <para>For a control containing some text, this property sets the
163           weight of the used font.</para>
164         </listitem>
165       </varlistentry>
166
167       <varlistentry>
168         <term>FontName</term>
169
170         <listitem>
171           <para>String</para>
172
173           <para>Used to choose the name of the font selected to display the
174           text of the control.</para>
175         </listitem>
176       </varlistentry>
177
178       <varlistentry>
179         <term>ForegroundColor</term>
180
181         <listitem>
182           <para>[1,3] real vector or string</para>
183
184           <para>Foreground color of the uicontrol. A color is specified as
185           Red, Green and Blue values. Those values are real in [0,1]. The
186           color can be given as a real vector, ie [R,G,B] or a string where
187           each value is separated by a "|", ie "R|G|B".</para>
188         </listitem>
189       </varlistentry>
190
191       <varlistentry>
192         <term>HorizontAlalignment</term>
193
194         <listitem>
195           <para>left | {center} | right</para>
196
197           <para>Set text horizontal alignment in the uicontrol. This property
198           has only effect with Text, Edit and Check Boxes.</para>
199         </listitem>
200       </varlistentry>
201
202       <varlistentry>
203         <term>ListboxTop</term>
204
205         <listitem>
206           <para>Scalar</para>
207
208           <para>For a ListBox, this property tells which item of the list
209           appears on the first line of the visible area of the list.</para>
210         </listitem>
211       </varlistentry>
212
213       <varlistentry>
214         <term>Max</term>
215
216         <listitem>
217           <para>Scalar</para>
218
219           <para>Specifies the largest value the "Value" property can be set
220           to. It has however different meaning on each uicontrol:</para>
221
222           <itemizedlist>
223             <listitem>
224               <para>CheckBoxes: Max is the value the "Value" property take
225               when control is checked.</para>
226             </listitem>
227
228             <listitem>
229               <para>Sliders: Maximum value of the slider.</para>
230             </listitem>
231
232             <listitem>
233               <para>ListBoxes: if (Max-Min)&gt;1 the list allows multiple
234               selection, Otherwise not.</para>
235             </listitem>
236           </itemizedlist>
237         </listitem>
238       </varlistentry>
239
240       <varlistentry>
241         <term>Min</term>
242
243         <listitem>
244           <para>Scalar</para>
245
246           <para>Specifies the lowest value the "Value" property can be set to.
247           It has however different meaning on each uicontrol:</para>
248
249           <itemizedlist>
250             <listitem>
251               <para>CheckBoxes: Min is the value the "Value" property take
252               when control is unchecked.</para>
253             </listitem>
254
255             <listitem>
256               <para>Sliders: Minimum value of the slider.</para>
257             </listitem>
258
259             <listitem>
260               <para>ListBoxes: if (Max-Min)&gt;1 the list allows multiple
261               selection, Otherwise not.</para>
262             </listitem>
263           </itemizedlist>
264         </listitem>
265       </varlistentry>
266
267       <varlistentry>
268         <term>Parent</term>
269
270         <listitem>
271           <para>Handle</para>
272
273           <para>Handle of the uicontrol parent. Changing this property allows
274           to move a control from a figure to another.</para>
275         </listitem>
276       </varlistentry>
277
278       <varlistentry>
279         <term>Path</term>
280
281         <listitem>
282           <para>This property is no more supported.</para>
283         </listitem>
284       </varlistentry>
285
286       <varlistentry>
287         <term>Position</term>
288
289         <listitem>
290           <para>[1,4] real vector or string.</para>
291
292           <para>This property is used to set or get the geometrical
293           configuration of a control. It is a vector [x y w h] where the
294           letters stand for the x location of the left bottom corner, the y
295           location of the left bottom corner, the width and the height of the
296           uicontrol or a character string where each value is separated by a
297           "|", ie "x|y|w|h". The units are determined by the "Units"
298           property.</para>
299           <para>The width and height values determine the orientation of sliders. If width is greater than height, then the slider is oriented horizontally, otherwise the slider is oriented vertically.</para>
300         </listitem>
301       </varlistentry>
302
303       <varlistentry>
304         <term>Relief</term>
305
306         <listitem>
307           <para>flat | groove | raised | ridge | solid | sunken</para>
308
309           <para>Appearance of the border of the uicontrol:</para>
310
311           <itemizedlist>
312             <listitem>
313               <para>PushButtons: the default value for "Relief" property is
314               "raised".</para>
315             </listitem>
316
317             <listitem>
318               <para>Edits: the default value for "Relief" property is
319               "sunken".</para>
320             </listitem>
321
322             <listitem>
323               <para>Other styles: the default value for "Relief" property is
324               "flat".</para>
325             </listitem>
326           </itemizedlist>
327         </listitem>
328       </varlistentry>
329
330       <varlistentry>
331         <term>SliderStep</term>
332
333         <listitem>
334           <para>[1,2] real vector</para>
335
336           <para>[small big], the small step represents the movement achieved
337           when clicking on the slider trough or tapping on the keyboard arrows
338           (when the slider has focus); the big step is the amount moved when
339           using Ctrl-keyboard-arrows. If the big step is omitted, it is
340           defaulted to 1/10 of the scale.</para>
341         </listitem>
342       </varlistentry>
343
344       <varlistentry>
345         <term>String</term>
346
347         <listitem>
348           <para>String.</para>
349
350           <para>This property represents the text appearing in a uicontrol
351           (Except for Frame and Slider styles). For ListBoxes and PopupMenus,
352           the value can be a vector of string or a string where the items are
353           separated by a "|". For Text uicontrols, this string can contain HTML code to format the text.</para>
354         </listitem>
355       </varlistentry>
356
357       <varlistentry>
358         <term>Style</term>
359
360         <listitem>
361           <para>{pushbutton} | radiobutton | checkbox | edit | text | slider |
362           frame | listbox | popupmenu</para>
363
364           <para>Style of the uicontrol. Here is a short description of each
365           one:</para>
366
367           <itemizedlist>
368             <listitem>
369               <para>Pushbutton: a rectangular button generally used to run a
370               callback.</para>
371             </listitem>
372
373             <listitem>
374               <para>Radiobutton: a button with to states. RadioButtons are
375               intended to be mutually exclusive (Your code must implement
376               mutually exclusive behavior).</para>
377             </listitem>
378
379             <listitem>
380               <para>Checkbox: a button with to states (Used for multiple
381               independent choices). </para>
382             </listitem>
383
384             <listitem>
385               <para>Edit: an editable string zone.</para>
386             </listitem>
387
388             <listitem>
389               <para>Text: a text control (generally static).</para>
390             </listitem>
391
392             <listitem>
393               <para>Slider: a scale control, that is a scrollbar use to set
394               values between in range with the mouse.</para>
395             </listitem>
396
397             <listitem>
398               <para>Frame: a control representing a zone used to group related
399               controls.</para>
400             </listitem>
401
402             <listitem>
403               <para>Listbox: a control representing a list of items that can
404               be scrolled. The items can be selected with the mouse.</para>
405             </listitem>
406
407             <listitem>
408               <para>Popupmenu: a button which make a menu appear when
409               clicked.</para>
410             </listitem>
411           </itemizedlist>
412         </listitem>
413       </varlistentry>
414
415       <varlistentry>
416         <term>Tag</term>
417
418         <listitem>
419           <para>String</para>
420
421           <para>This property is generally used to identify the control. It
422           allows to give it a "name". Mainly used in conjunction with
423           <literal>findobj()</literal>.</para>
424         </listitem>
425       </varlistentry>
426
427       <varlistentry>
428         <term>Units</term>
429
430         <listitem>
431           <para>{points} | pixels | normalized</para>
432
433           <para>Set the units used to specify the "Position" property.</para>
434         </listitem>
435       </varlistentry>
436
437       <varlistentry>
438         <term>Userdata</term>
439
440         <listitem>
441           <para>Scilab data</para>
442
443           <para>This can be used to associate some Scilab objects
444           (string,string matrix, matrix mxn) to an uicontrol.</para>
445         </listitem>
446       </varlistentry>
447
448       <varlistentry>
449         <term>Value</term>
450
451         <listitem>
452           <para>Scalar or vector</para>
453
454           <para>Value of the uicontrol. The exact meaning depends on the style
455           of the uicontrol:</para>
456
457           <itemizedlist>
458             <listitem>
459               <para>CheckBoxes, Radio buttons: value is set to Max (see above)
460               when on and Min when off.</para>
461             </listitem>
462
463             <listitem>
464               <para>ListBoxes, PopupMenus: value is a vector of indexes
465               corresponding to the indexes of the selected entries in the
466               list. 1 is the first item of the list.</para>
467             </listitem>
468
469             <listitem>
470               <para>Sliders: value indicated by the slider bar.</para>
471             </listitem>
472           </itemizedlist>
473         </listitem>
474       </varlistentry>
475
476       <varlistentry>
477         <term>Verticalalignment</term>
478
479         <listitem>
480           <para>top | {middle} | bottom</para>
481
482           <para>Set text vertical alignment in the uicontrol. This property
483           has only effect with Text and CheckBoxes styles.</para>
484         </listitem>
485       </varlistentry>
486
487       <varlistentry>
488         <term>Visible</term>
489
490         <listitem>
491           <para>{on} | off</para>
492
493           <para>Set the visibility of the uicontrol. If this property is set to <literal>"on"</literal> (default), the uicontrol is visible, 
494           but if this property is set to <literal>"off"</literal>, the uicontrol will not appear in its parent figure.</para>
495         </listitem>
496       </varlistentry>
497
498     </variablelist>
499   </refsection>
500
501   <refsection>
502     <title>Examples</title>
503
504     <programlisting role="example"><![CDATA[ 
505 f=figure();
506 // create a figure
507 h=uicontrol(f,'style','listbox', ...
508  'position', [10 10 150 160]);
509 // create a listbox
510 set(h, 'string', "item 1|item 2|item3");
511 // fill the list
512 set(h, 'value', [1 3]);
513 // select item 1 and 3 in the list
514 close(f);
515 // close the figure
516  ]]></programlisting>
517
518     <para>uicontrol function can be overloaded</para>
519     <programlisting role="example"><![CDATA[ 
520 // create a mlist
521 mymlist = mlist(['objid','A','B'],[],[]);
522
523 // overload set / get for objid
524 function result = %objid_uicontrol(varargin)
525   // res = uicontrol(mymlist,'A');
526   obj_tmp   = varargin(1);
527   field_tmp = varargin(2);
528   printf('uicontrol on an object of type %s, field = %s\n', typeof(obj_tmp), field_tmp);
529   result = %t;
530 endfunction
531
532 res = uicontrol(mymlist,'property');
533  ]]></programlisting>
534
535   </refsection>
536
537   <refsection>
538     <title>See Also</title>
539
540     <simplelist type="inline">
541       <member><link linkend="figure">figure</link></member>
542
543       <member><link linkend="set">set</link></member>
544
545       <member><link linkend="get">get</link></member>
546
547       <member><link linkend="uimenu">uimenu</link></member>
548     </simplelist>
549   </refsection>
550
551   <refsection>
552     <title>Authors</title>
553
554     <para>Bertrand Guiheneuf</para>
555
556     <para>Vincent Couvert</para>
557
558     <para>Yann Collette</para>
559   </refsection>
560 </refentry>