uicontrol properties

Description

These properties can be set using the set or uicontrol functions and their value can be obtained with the get.

Properties

BackgroundColor

[1,3] real vector or string

Background color of the uicontrol. A color is specified as Red, Green and Blue values. Those values are real in [0,1]. The color can be given as a real vector, ie [R,G,B] or a string where each value is separated by a "|", ie "R|G|B".

Setting this property to [-1 -1 -1] will let the look and feel set the default background color.

Border

A Border object.

Only used for frame style uicontrols, this object is created using createBorder.

Setting this value to [] removes the border of the frame.

Callback

String

Instruction evaluated by the Scilab interpreter when an uicontrol is activated (for example when you click on a button).

This property is not used for layer, frame and text style uicontrols.

Callback_Type

Scalar

The type of callback transmitted to the uicontrol (see example below).

-1

none (callback deactivated)

0 (by default)

non prioritary (or interruptible) Scilab instructions

1

Cor a Fortran function

2

non prioritary (or interruptible) Scilab function

10

prioritary (or non-interruptible) Scilab instructions

12

prioritary (or non-interruptible) Scilab function

Constraints

A Constraints object.

This object is created using createConstraints and describes the constraints on the position and size of the uicontrol regarding to its parent.

Setting this value to [] clears the constraints.

Enable

{on} | off

Enable or disable the uicontrol. If this property is set to "on" (default), the uicontrol is operational, but if this property is set to "off", the uicontrol will not respond to the mouse actions and will be grayed out.

FontAngle

{normal} | italic | oblique

For a control containing some text, this property sets the slant of the font.

FontSize

Scalar

For a control containing some text, this property sets the size of the font in FontUnits.

FontUnits

{points} | pixels | normalized

For a control containing some text, this property sets the units with which the FontSize is specified.

FontWeight

light | {normal} | demi | bold

For a control containing some text, this property sets the weight of the used font.

FontName

String

Used to choose the name of the font selected to display the text of the control.

ForegroundColor

[1,3] real vector or string

Foreground color of the uicontrol. A color is specified as Red, Green and Blue values. Those values are real in [0,1]. The color can be given as a real vector, ie [R,G,B] or a string where each value is separated by a "|", ie "R|G|B".

Setting this property to [-1 -1 -1] will let the look and feel set the default foreground color.

Groupname

String

Used for radiobutton and checkbox style uicontrols, this property allow to manage uicontrols of the same group as a whole. For example, checkbox uicontrols of a group will manage selection unicity automatically.

HorizontalAlignment

left | {center} | right

Set text horizontal alignment in the uicontrol.

Icon

String.

This property represents the relative (to Scilab working directory) or absolute path of the image file to be used as icon for a pushbutton or text uicontrol.

For frame uicontrols in tab uicontrols, the icon property sets the icon of its sheet.

Layout:

This property sets the layout used to dispose frame uicontrols children. See layout page for more information about available layouts.

Layout_options:

This property sets the options of the layout used to dispose frame children. See layout page for more information about available options.

ListboxTop

Scalar

Only used for listbox uicontrols, this property tells which item of the list appears on the first line of the visible area of the list.

Margins

[1,4] real vector.

Sets an empty space around the uicontrol under the form [top, left, bottom, right] (in pixels).

Max

Scalar

Specifies the largest value the "Value" property can be set to. It has however different meaning on each uicontrol:

• checkbox and radiobutton uicontrols: Max is the value the "Value" property take when control is checked.

• slider and spinner uicontrols: Maximum value of the component.

• listbox uicontrols: if (Max-Min)>1 the list allows multiple selection.

• edit uicontrols: if (Max-Min)>1 the edit allows multiple line edition.

Min

Scalar

Specifies the lowest value the "Value" property can be set to. It has however different meaning on each uicontrol:

• checkbox and radiobutton uicontrols: Min is the value the "Value" property take when control is unchecked.

• slider and spinner uicontrols: Minimum value of the component.

• listbox uicontrols: if (Max-Min)>1 the list allows multiple selection.

• edit uicontrols: if (Max-Min)>1 the edit allows multiple line edition.

Parent

Handle

Handle of the uicontrol parent. Changing this property allows to move a control from a figure to another.

Position

[x y w h] numerical vector (as stored) or a "x|y|w|h" string.

Sets or gets the position and size of the component, the referential being

• .parent.axes_size, if .parent is a Figure
• .parent.position, if .parent is a uicontrol Frame.

The value is a vector [x y w h] where

• x is the horizontal position of the left side of the component with respect to the left edge of the referential.
• y is the vertical position of the bottom side of the component with respect to the bottom edge of the referential.
• w and h are the width and height of the uicontrol component.

x, y, w, h can as well be set through a "x|y|w|h" single string with "|" used as separator.

The unit is set by the .Units property.

For sliders: w > h sets the slider horizontally, and vertically otherwise.

Relief

{default} | flat | groove | raised | ridge | solid | sunken

Appearance of the border of the uicontrol. "default" means that the application look and feel will be used to set the relief.

When using the deprecated skin for uicontrols, default values are related to uicontrol style:

• pushbutton uicontrols: the default value for "Relief" property is "raised".

• edit uicontrols: the default value for "Relief" property is "sunken".

• Other uicontrols: the default value for "Relief" property is relief by default provided by java language.

Scrollable

Boolean.

Used for frame and edit style uicontrols, this property indicates if the uicontrol must have scrolling capabilities (%T) or not (default %F).

For frame this value must be set at creation.

SliderStep

[1,2] real vector

[small big], the small step represents the movement achieved when clicking on the slider trough or tapping on the keyboard arrows (when the slider has focus); the big step is the amount moved when using Ctrl-keyboard-arrows. If the big step is omitted, it is defaulted to 1/10 of the scale.

For spinner uicontrol, the first value of this property is used as fixed step.

SnapToTicks

on | {off}

If SnapToTicks is "on", the Slider knob will always snap to the closest position associated to a value given by the "Min" property plus an integer multiple of small step (see SliderStep above). The default value of this property is "off".

String

String.

This property represents the text appearing in a uicontrol (Except for Frame, Slider, and Spinner styles). For tables, the value is a string matrix. For ListBoxes and PopupMenus, the value can be a vector of string or a string where the items are separated by a "|". For Text uicontrols, this string can contain HTML code to format the text.

• For pushbutton or text uicontrols, if the text is enclosed between two $ (dollar sign), then it will be considered as a LaTeX expression, and if it is enclosed between < and >, it will be considered as a MathML one.

• For layer and tab uicontrols, the value specifies the tag of the selected child.

• For image uicontrols, the value specifies the path of the image file.

• For table uicontrols, the value specifies the ole table data: [IGNORED COL1-HEADER...COLN-HEADER;ROW1-HEADER, ROW1COL1-DATA, ROW1COLN-DATA;...;ROWM-HEADER, ROWMCOL1-DATA, ROWMCOLN-DATA].

• For listbox and popupmenu uicontrols which manage colors selection, icons, background and foreground colors, the String property can be set to a matrix matching the format: ["#color1", "Item1", "#background1", "#foreground1"; "#color2", "Item2", ..., ...] ["icon1", "Item1", "#background1", "#foreground1"; "icon2", "Item2", ..., ...] with "#color1", "#background1" and "#foreground1" in HTML format #XXXXXX. Then the component will display a colored box or icon on the left of the associated string, and different background/foreground colors for items.

Tag

String

This property is generally used to identify the control. It allows to give it a "name". Mainly used in conjunction with findobj().

Title_position

{top} | left | bottom | right

The position of the tabs of a tab style uicontrol.

Title_scroll

Boolean

Indicates whether the tabs of a tab style uicontrol must be wrapped (title_scroll=%F) or scrolled (title_scroll=%T).

TooltipString

String or String vector

This property represents the text of the uicontrol tooltip appearing when the mouse is over the uicontrol.

Units

{points} | pixels | normalized

Set the units used to specify the "Position" property. Normalized positions and sizes are in [0, 1]:

• If .parent is a "figure", they are within and refer to the .parent.axes_size area.
• If .parent is an uicontrol of style "frame", they are within and refer to the .parent.position area.

Userdata

Scilab data

This can be used to associate some Scilab objects (string,string matrix, matrix mxn) to an uicontrol.

Value

Scalar or vector

Value of the uicontrol. The exact meaning depends on the style of the uicontrol:

• checkbox and radiobutton uicontrols: value is set to Max (see above) when on and Min when off.

• listbox and popupmenu uicontrols: value is a vector of indexes corresponding to the indexes of the selected entries in the list. 1 is the first item of the list.

• slider and spinner uicontrols: numerical value indicated by the component.

• layer and tab uicontrols: index of displayed component.

• image uicontrols: value is used to set some image properties [X-Scale Y-Scale X-Shear Y-Shear RotationAngle]

Verticalalignment

top | {middle} | bottom

Set text vertical alignment in the uicontrol. This property has only effect with Text and CheckBoxes styles.

Visible

{on} | off

Set the visibility of the uicontrol. If this property is set to "on" (default), the uicontrol is visible, but if this property is set to "off", the uicontrol will not appear in its parent figure.

Example for callback_type property

function counter_start()
    // Callback called after a click on start pushbutton
    global Stop
    Stop=%f;
    while %t
        i = evstr(get("count", "string"));
        set("count", "string", string(i+1));
        if Stop then
            break
        end
    end
endfunction

function counter_stop()
    // Callback called after a click on stop pushbutton
    global Stop
    Stop=%t
endfunction

function counter_reinit()
    // Callback called after a click on reset pushbutton
    Stop=%t
    set("count", "string", "0");
endfunction

counter_main_fig = figure( ...
"dockable", "off", ...
"infobar_visible", "off", ...
"toolbar_visible", "off", ...
"toolbar", "none", ...
"menubar_visible", "off", ...
"menubar", "none", ...
"layout", "none", ...
"visible", "off", ...
"resize", "off", ...
"figure_position", [0 0], ...
"axes_size", [400, 150], ...
"figure_name", "Counter", ...
"layout", "gridbag", ...
"tag", "counter_main_figure");

// Counter frame
counter_frame = uicontrol(counter_main_fig, ...
"layout", "gridbag", ...
"style", "frame", ...
"constraints", createConstraints("gridbag", [1, 1, 1, 1], [1, 0.5], "both"));

uicontrol(counter_frame, ...
"style", "text", ...
"string", "Counter : ", ...
"constraints", createConstraints("gridbag", [1, 1, 1, 1], [0.5, 1], "horizontal", "center"), ...
"margins", [5 5 5 5], ...
"horizontalAlignment", "center");

uicontrol(counter_frame, ...
"style", "text", ...
"string", "0", ...
"constraints", createConstraints("gridbag", [2, 1, 1, 1], [1, 1], "horizontal", "center"), ...
"tag", "count", ...
"margins", [5 5 5 5]);

// Buttons frame
buttons_frame = uicontrol(counter_main_fig, ...
"layout", "gridbag", ...
"style", "frame", ...
"constraints", createConstraints("gridbag", [1, 2, 1, 1], [1, 1], "both"));

// The associated callback needs to be interruptible (when clicking on stop or reset for example)
uicontrol("parent", buttons_frame, ...
"Style"     , "pushbutton", ...
"String"    , "Start", ...
"callback"  , "counter_start()", ...
"margins", [5 5 5 5], ...
"constraints", createConstraints("gridbag", [1, 1, 1, 1], [1, 1], "horizontal", "center"));

// The associated callback needs to have priority in order to interrupt the current callback (in other words to stop the counter)
uicontrol("parent", buttons_frame, ...
"Style"     , "pushbutton", ...
"String"    , "Stop", ...
"callback"  , "counter_stop()", ...
"callback_type", 10, ...
"constraints", createConstraints("gridbag", [2, 1, 1, 1], [1, 1], "horizontal", "center"), ...
"margins", [5 5 5 5]);

// The same for the callback which reset the counter: it must have the priority over the callback which has started the counter
uicontrol("parent", buttons_frame, ...
"Style"     , "pushbutton", ...
"String"    , "Reset", ...
"callback"  , "counter_reinit()", ...
"callback_type", 10, ...
"constraints", createConstraints("gridbag", [3, 1, 1, 1], [1, 1], "horizontal", "center"), ...
"margins", [5 5 5 5]);

counter_main_fig.visible = "on";

See also

• uicontrol — create a Graphic User Interface object
• hidden handles / properties — Description of console object properties.
• set — set properties of some graphic objects or uimenus or uicontrol interactive components
• get — Retrieve a property value from a graphics entity or an User Interface object.

History