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