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,
  43                 PropertyValue,...)
  44             </literal>
  45             creates a uicontrol in the object specified
  46             by the handle, parent. If you also specify a different value for the
  47             Parent property, the value of the Parent property takes precedence. parent
  48             is the handle of a figure.
  49         </para>
  50         <para>
  51             <literal>h= uicontrol(uich)</literal> gives focus to the uicontrol
  52             specified by uich.
  53         </para>
  54     </refsection>
  55     <refsection>
  56         <title>Properties</title>
  57         <variablelist>
  58             <varlistentry>
  59                 <term>BackgroundColor</term>
  60                 <listitem>
  61                     <para>[1,3] real vector or string</para>
  62                     <para>Background color of the uicontrol. A color is specified as
  63                         Red, Green and Blue values. Those values are real in [0,1]. The
  64                         color can be given as a real vector, ie [R,G,B] or a string where
  65                         each value is separated by a "|", ie "R|G|B".
  66                     </para>
  67                 </listitem>
  68             </varlistentry>
  69             <varlistentry>
  70                 <term>Callback</term>
  71                 <listitem>
  72                     <para>String</para>
  73                     <para>Instruction evaluated by the Scilab interpreter when an
  74                         uicontrol is activated. (for example when you click on a
  75                         button).
  76                     </para>
  77                 </listitem>
  78             </varlistentry>
  79             <varlistentry>
  80                 <term>Callback_Type</term>
  81                 <listitem>
  82                     <para>Integer</para>
  83                     <para>The type of callback transmitted to the uicontrol.</para>
  84                     <itemizedlist>
  85                         <listitem>
  86                             <para>
  87                                 <literal>-1</literal> none (callback desactivated)
  88                             </para>
  89                         </listitem>
  90                         <listitem>
  91                             <para>
  92                                 <literal>0</literal> a Scilab instruction
  93                             </para>
  94                         </listitem>
  95                         <listitem>
  96                             <para>
  97                                 <literal>1</literal> a C or a Fortran function
  98                             </para>
  99                         </listitem>
 100                         <listitem>
 101                             <para>
 102                                 <literal>2</literal> a Scilab function
 103                             </para>
 104                         </listitem>
 105                     </itemizedlist>
 106                 </listitem>
 107             </varlistentry>
 108             <varlistentry>
 109                 <term>Enable</term>
 110                 <listitem>
 111                     <para>{on} | off</para>
 112                     <para>
 113                         Enable or disable the uicontrol. If this property is set to <literal>"on"</literal> (default), the uicontrol is operational,
 114                         but if this property is set to <literal>"off"</literal>, the uicontrol will not respond to the mouse actions and will be grayed out.
 115                     </para>
 116                 </listitem>
 117             </varlistentry>
 118             <varlistentry>
 119                 <term>FontAngle</term>
 120                 <listitem>
 121                     <para>{normal} | italic | oblique</para>
 122                     <para>For a control containing some text, this property sets the
 123                         slant of the font.
 124                     </para>
 125                 </listitem>
 126             </varlistentry>
 127             <varlistentry>
 128                 <term>FontSize</term>
 129                 <listitem>
 130                     <para>Scalar</para>
 131                     <para>For a control containing some text, this property sets the
 132                         size of the font in FontUnits.
 133                     </para>
 134                 </listitem>
 135             </varlistentry>
 136             <varlistentry>
 137                 <term>FontUnits</term>
 138                 <listitem>
 139                     <para>{points} | pixels | normalized</para>
 140                     <para>For a control containing some text, this property sets the
 141                         units with which the FontSize is specified.
 142                     </para>
 143                 </listitem>
 144             </varlistentry>
 145             <varlistentry>
 146                 <term>FontWeight</term>
 147                 <listitem>
 148                     <para>light | {normal} | demi | bold</para>
 149                     <para>For a control containing some text, this property sets the
 150                         weight of the used font.
 151                     </para>
 152                 </listitem>
 153             </varlistentry>
 154             <varlistentry>
 155                 <term>FontName</term>
 156                 <listitem>
 157                     <para>String</para>
 158                     <para>Used to choose the name of the font selected to display the
 159                         text of the control.
 160                     </para>
 161                 </listitem>
 162             </varlistentry>
 163             <varlistentry>
 164                 <term>ForegroundColor</term>
 165                 <listitem>
 166                     <para>[1,3] real vector or string</para>
 167                     <para>Foreground color of the uicontrol. A color is specified as
 168                         Red, Green and Blue values. Those values are real in [0,1]. The
 169                         color can be given as a real vector, ie [R,G,B] or a string where
 170                         each value is separated by a "|", ie "R|G|B".
 171                     </para>
 172                 </listitem>
 173             </varlistentry>
 174             <varlistentry>
 175                 <term>HorizontalAlignment</term>
 176                 <listitem>
 177                     <para>left | {center} | right</para>
 178                     <para>Set text horizontal alignment in the uicontrol. This property
 179                         has only effect with Text, Edit and Check Boxes.
 180                     </para>
 181                 </listitem>
 182             </varlistentry>
 183             <varlistentry>
 184                 <term>ListboxTop</term>
 185                 <listitem>
 186                     <para>Scalar</para>
 187                     <para>For a ListBox, this property tells which item of the list
 188                         appears on the first line of the visible area of the list.
 189                     </para>
 190                 </listitem>
 191             </varlistentry>
 192             <varlistentry>
 193                 <term>Max</term>
 194                 <listitem>
 195                     <para>Scalar</para>
 196                     <para>Specifies the largest value the "Value" property can be set
 197                         to. It has however different meaning on each uicontrol:
 198                     </para>
 199                     <itemizedlist>
 200                         <listitem>
 201                             <para>CheckBoxes: Max is the value the "Value" property take
 202                                 when control is checked.
 203                             </para>
 204                         </listitem>
 205                         <listitem>
 206                             <para>Sliders: Maximum value of the slider.</para>
 207                         </listitem>
 208                         <listitem>
 209                             <para>ListBoxes: if (Max-Min)&gt;1 the list allows multiple
 210                                 selection, Otherwise not.
 211                             </para>
 212                         </listitem>
 213                     </itemizedlist>
 214                 </listitem>
 215             </varlistentry>
 216             <varlistentry>
 217                 <term>Min</term>
 218                 <listitem>
 219                     <para>Scalar</para>
 220                     <para>Specifies the lowest value the "Value" property can be set to.
 221                         It has however different meaning on each uicontrol:
 222                     </para>
 223                     <itemizedlist>
 224                         <listitem>
 225                             <para>CheckBoxes: Min is the value the "Value" property take
 226                                 when control is unchecked.
 227                             </para>
 228                         </listitem>
 229                         <listitem>
 230                             <para>Sliders: Minimum value of the slider.</para>
 231                         </listitem>
 232                         <listitem>
 233                             <para>ListBoxes: if (Max-Min)&gt;1 the list allows multiple
 234                                 selection, Otherwise not.
 235                             </para>
 236                         </listitem>
 237                     </itemizedlist>
 238                 </listitem>
 239             </varlistentry>
 240             <varlistentry>
 241                 <term>Parent</term>
 242                 <listitem>
 243                     <para>Handle</para>
 244                     <para>Handle of the uicontrol parent. Changing this property allows
 245                         to move a control from a figure to another.
 246                     </para>
 247                 </listitem>
 248             </varlistentry>
 249             <varlistentry>
 250                 <term>Path</term>
 251                 <listitem>
 252                     <para>This property is no more supported.</para>
 253                 </listitem>
 254             </varlistentry>
 255             <varlistentry>
 256                 <term>Position</term>
 257                 <listitem>
 258                     <para>[1,4] real vector or string.</para>
 259                     <para>This property is used to set or get the geometrical
 260                         configuration of a control. It is a vector [x y w h] where the
 261                         letters stand for the x location of the left bottom corner, the y
 262                         location of the left bottom corner, the width and the height of the
 263                         uicontrol or a character string where each value is separated by a
 264                         "|", ie "x|y|w|h". The units are determined by the "Units"
 265                         property.
 266                     </para>
 267                     <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>
 268                 </listitem>
 269             </varlistentry>
 270             <varlistentry>
 271                 <term>Relief</term>
 272                 <listitem>
 273                     <para>flat | groove | raised | ridge | solid | sunken</para>
 274                     <para>Appearance of the border of the uicontrol:</para>
 275                     <itemizedlist>
 276                         <listitem>
 277                             <para>PushButtons: the default value for "Relief" property is
 278                                 "raised".
 279                             </para>
 280                         </listitem>
 281                         <listitem>
 282                             <para>Edits: the default value for "Relief" property is
 283                                 "sunken".
 284                             </para>
 285                         </listitem>
 286                         <listitem>
 287                             <para>Other styles: the default value for "Relief" property is
 288                                 "flat".
 289                             </para>
 290                         </listitem>
 291                     </itemizedlist>
 292                 </listitem>
 293             </varlistentry>
 294             <varlistentry>
 295                 <term>SliderStep</term>
 296                 <listitem>
 297                     <para>[1,2] real vector</para>
 298                     <para>[small big], the small step represents the movement achieved
 299                         when clicking on the slider trough or tapping on the keyboard arrows
 300                         (when the slider has focus); the big step is the amount moved when
 301                         using Ctrl-keyboard-arrows. If the big step is omitted, it is
 302                         defaulted to 1/10 of the scale.
 303                     </para>
 304                 </listitem>
 305             </varlistentry>
 306             <varlistentry>
 307                 <term>String</term>
 308                 <listitem>
 309                     <para>String.</para>
 310                     <para>
 311                         This property represents the text appearing in a uicontrol
 312                         (Except for Frame and Slider styles). For tables, the value is a string matrix. For ListBoxes and PopupMenus,
 313                         the value can be a vector of string or a string where the items are
 314                         separated by a "|". For Text uicontrols, this string can contain HTML code to format the text.
 315                     </para>
 316                     <para>
 317                         For Pushbutton or Text uicontrols, if the text is enclosed between two $ (dollar sign), then it will be
 318                         considered as a LaTeX expression, and if it is enclosed between &lt; and &gt;, it will be considered
 319                         as a MathML one.
 320                     </para>
 321                     <para>
 322                         For Image, the value specifies the path of the image file.
 323                     </para>
 324                     <para>
 325                         For Table, the value specifies the whole table data: <literal>[IGNORED COL1-HEADER...COLN-HEADER;ROW1-HEADER, ROW1COL1-DATA, ROW1COLN-DATA;...;ROWM-HEADER, ROWMCOL1-DATA, ROWMCOLN-DATA]</literal>.
 326                     </para>
 327                 </listitem>
 328             </varlistentry>
 329             <varlistentry>
 330                 <term>TooltipString</term>
 331                 <listitem>
 332                     <para>String or String vector</para>
 333                     <para>
 334                         This property represents the text of the uicontrol tooltip appearing when the mouse is over the uicontrol.
 335                     </para>
 336                 </listitem>
 337             </varlistentry>
 338             <varlistentry>
 339                 <term>Style</term>
 340                 <listitem>
 341                     <para>{pushbutton} | radiobutton | checkbox | edit | text | slider |
 342                         frame | listbox | popupmenu | image | table
 343                     </para>
 344                     <para>Style of the uicontrol. This property has to be set at creation time and can not be changed once the uicontrol is created. Here is a short description of each
 345                         one:
 346                     </para>
 347                     <itemizedlist>
 348                         <listitem>
 349                             <para>Pushbutton: a rectangular button generally used to run a
 350                                 callback.
 351                             </para>
 352                         </listitem>
 353                         <listitem>
 354                             <para>Radiobutton: a button with to states. RadioButtons are
 355                                 intended to be mutually exclusive (Your code must implement
 356                                 mutually exclusive behavior).
 357                             </para>
 358                         </listitem>
 359                         <listitem>
 360                             <para>Checkbox: a button with to states (Used for multiple
 361                                 independent choices).
 362                             </para>
 363                         </listitem>
 364                         <listitem>
 365                             <para>Edit: an editable string zone.</para>
 366                         </listitem>
 367                         <listitem>
 368                             <para>Text: a text control (generally static).</para>
 369                         </listitem>
 370                         <listitem>
 371                             <para>Slider: a scale control, that is a scrollbar use to set
 372                                 values between in range with the mouse.
 373                             </para>
 374                         </listitem>
 375                         <listitem>
 376                             <para>Frame: a control representing a zone used to group related
 377                                 controls.
 378                             </para>
 379                         </listitem>
 380                         <listitem>
 381                             <para>Listbox: a control representing a list of items that can
 382                                 be scrolled. The items can be selected with the mouse.
 383                             </para>
 384                         </listitem>
 385                         <listitem>
 386                             <para>Popupmenu: a button which make a menu appear when
 387                                 clicked.
 388                             </para>
 389                         </listitem>
 390                         <listitem>
 391                             <para>Image: a sub-window where the image specified is displayed.</para>
 392                         </listitem>
 393                         <listitem>
 394                             <para>Table: an editable table.</para>
 395                         </listitem>
 396                     </itemizedlist>
 397                 </listitem>
 398             </varlistentry>
 399             <varlistentry>
 400                 <term>Tag</term>
 401                 <listitem>
 402                     <para>String</para>
 403                     <para>This property is generally used to identify the control. It
 404                         allows to give it a "name". Mainly used in conjunction with
 405                         <literal>findobj()</literal>.
 406                     </para>
 407                 </listitem>
 408             </varlistentry>
 409             <varlistentry>
 410                 <term>Units</term>
 411                 <listitem>
 412                     <para>{points} | pixels | normalized</para>
 413                     <para>Set the units used to specify the "Position" property.</para>
 414                 </listitem>
 415             </varlistentry>
 416             <varlistentry>
 417                 <term>Userdata</term>
 418                 <listitem>
 419                     <para>Scilab data</para>
 420                     <para>This can be used to associate some Scilab objects
 421                         (string,string matrix, matrix mxn) to an uicontrol.
 422                     </para>
 423                 </listitem>
 424             </varlistentry>
 425             <varlistentry>
 426                 <term>Value</term>
 427                 <listitem>
 428                     <para>Scalar or vector</para>
 429                     <para>Value of the uicontrol. The exact meaning depends on the style
 430                         of the uicontrol:
 431                     </para>
 432                     <itemizedlist>
 433                         <listitem>
 434                             <para>CheckBoxes, Radio buttons: value is set to Max (see above)
 435                                 when on and Min when off.
 436                             </para>
 437                         </listitem>
 438                         <listitem>
 439                             <para>ListBoxes, PopupMenus: value is a vector of indexes
 440                                 corresponding to the indexes of the selected entries in the
 441                                 list. 1 is the first item of the list.
 442                             </para>
 443                         </listitem>
 444                         <listitem>
 445                             <para>Sliders: value indicated by the slider bar.</para>
 446                         </listitem>
 447                         <listitem>
 448                             <para>
 449                                 Images: value is used to set some image properties <literal>[X-Scale Y-Scale X-Shear Y-Shear RotationAngle]</literal>
 450                             </para>
 451                         </listitem>
 452                     </itemizedlist>
 453                 </listitem>
 454             </varlistentry>
 455             <varlistentry>
 456                 <term>Verticalalignment</term>
 457                 <listitem>
 458                     <para>top | {middle} | bottom</para>
 459                     <para>Set text vertical alignment in the uicontrol. This property
 460                         has only effect with Text and CheckBoxes styles.
 461                     </para>
 462                 </listitem>
 463             </varlistentry>
 464             <varlistentry>
 465                 <term>Visible</term>
 466                 <listitem>
 467                     <para>{on} | off</para>
 468                     <para>
 469                         Set the visibility of the uicontrol. If this property is set to <literal>"on"</literal> (default), the uicontrol is visible,
 470                         but if this property is set to <literal>"off"</literal>, the uicontrol will not appear in its parent figure.
 471                     </para>
 472                 </listitem>
 473             </varlistentry>
 474         </variablelist>
 475     </refsection>
 476     <refsection>
 477         <title>Examples</title>
 478         <programlisting role="example"><![CDATA[
 479 f=figure();
 480 // create a figure
 481 h=uicontrol(f,'style','listbox', ...
 482  'position', [10 10 150 160]);
 483 // create a listbox
 484 set(h, 'string', "item 1|item 2|item3");
 485 // fill the list
 486 set(h, 'value', [1 3]);
 487 // select item 1 and 3 in the list
 488 close(f);
 489 // close the figure
 490  ]]></programlisting>
 491         <para>uicontrol function can be overloaded</para>
 492         <programlisting role="example"><![CDATA[
 493 // create a mlist
 494 mymlist = mlist(['objid','A','B'],[],[]);
 495
 496 // overload set / get for objid
 497 function result = %objid_uicontrol(varargin)
 498   // res = uicontrol(mymlist,'A');
 499   obj_tmp   = varargin(1);
 500   field_tmp = varargin(2);
 501   mprintf('uicontrol on an object of type %s, field = %s\n', typeof(obj_tmp), field_tmp);
 502   result = %t;
 503 endfunction
 504
 505 res = uicontrol(mymlist,'property');
 506  ]]></programlisting>
 507         <para>Pushbuttons or Text can have LaTeX or MathML label</para>
 508         <programlisting role="example"><![CDATA[
 509 // LaTeX
 510 f=figure();
 511 h=uicontrol(f,"style","pushbutton","string","$x^2$");
 512 // MathML
 513 hh=uicontrol(f,"style","pushbutton","string","<msup><mi>x</mi><mn>2</mn></msup>");
 514 hh.Position = h.Position + [50, 0, 0, 0];
 515 // Text
 516 h=uicontrol(f,"Style","text","string","$\Gamma(s)=\int_0^\infty t^{s-1}\mathrm{e}^{-t}\,\mathrm{d}t$");
 517 // If it is too little
 518 h.fontsize=20
 519  ]]></programlisting>
 520         <programlisting role="example"><![CDATA[
 521 // Include an editable table into a figure:
 522 // Building a table of data:
 523 params = [" " "Country" "Population [Mh]" "Temp.[Â°C]" ];
 524 towns = ["Mexico" "Paris" "Tokyo" "Singapour"]';
 525 country = ["Mexico" "France" "Japan" "Singapour"]';
 526 pop  = string([22.41 11.77 33.41 4.24]');
 527 temp = string([26 19 22 17]');
 528 table = [params; [ towns country pop temp ]]
 529
 530 f = gcf();
 531 clf
 532 as = f.axes_size;  // [width height]
 533 delete(ut)
 534 ut = uicontrol("style","table",..
 535                "string",table,..
 536                "position",[5 as(2)-100 300 87],.. // => @top left corner of figure
 537                "tooltipstring","Data from majors towns")
 538
 539 // Modify by hand some values in the table. Then get them back from the ui:
 540 matrix(ut.string,size(table))
 541  ]]></programlisting>
 542     </refsection>
 543     <refsection role="see also">
 544         <title>See Also</title>
 545         <simplelist type="inline">
 546             <member>
 547                 <link linkend="figure">figure</link>
 548             </member>
 549             <member>
 550                 <link linkend="set">set</link>
 551             </member>
 552             <member>
 553                 <link linkend="get">get</link>
 554             </member>
 555             <member>
 556                 <link linkend="uimenu">uimenu</link>
 557             </member>
 558             <member>
 559                 <link linkend="math_rendering_features_in_graphic">LaTeX and MathML</link>
 560             </member>
 561         </simplelist>
 562     </refsection>
 563 </refentry>