List

A list is a control that displays a list of items.

It can be used to send commands or set datapoints.

Attributes

Common

ID

Sets the object's ID.

The ID identifies the object and is used to reference it in UISet actions, allowing to change its attributes dynamically.

The ID is not unique, it can be shared among multiple objects to quickly change a common attribute.

IDs can't be changed with a UISet action, but they can have a Value Binding assigned to them. Value Bindings on IDs allow an object to be dinamically attached to a set of attribute values.

E.g. the following Value Binding switches the ID of the object between mybutton1 and mybutton2 based on the value of the UISet button.address:

Value binding: ="mybutton" + ui('button', 'address')

UISet: UISet('button', 'address', '1') switches the ID to mybutton1 UISet('button', 'address', '2') switches the ID to mybutton2

Position and Size

Position

Sets the object's position.

The default value is: x0y0.

Attribute Values

Value	Description	Example
x<left>y<top>	Specify left/top coordinates in pixels.	x10y20

Flex Grow

Specifies if the objects should grow to fill the available space.

The default value is: true.

Attribute Values

Value	Description
true	Default value. Objects expand to fill the available space.
false	Objects do not grow to fill the available space.

Flex Shrink

Specifies if the objects should shrink to fit the available space.

The default value is: true.

Attribute Values

Value	Description
true	Default value. Objects shrink to fit the available space.
false	Objects do not shrink to fit the available space.

Width

Sets the object's width in pixels.

Minimum value is 1.

Height

Sets the object's height in pixels.

Minimum value is 1.

Data

Data Mode

Specifies the mode of the data.

The default value is: items.

Attribute Values

Value	Description
items	Default value. Data is set with the UI attribute Items.
list	Data is a list of comma-separated values. Set in the List attribute.
datasource	Data is set by a linked datasource.

Items

Specifies the items.

List

Sets the items. An item with a label "---" (three hyphen-minus characters) is treated as a separator and its value is ignored.

Attribute Values

Value	Description	Example
<comma-separated list>	Items specified as a comma-separated list.	item1,item2,item3
<array>	Items specified as an array of strings.	["item1","item2","item3"]
<array of arrays>	Items specified as an array of arrays. Each item has an array of value and label.	[[1,"label1"],[2,"label2"],[3,"label3"]]
<array of arrays>	Items specified as an array of arrays. Each item has an array of values that can be recalled from the template attribute.	[[1,"label1","descr1"],[2,"label2","descr2"],[3,"label3","descr3"]]

Datasource ID

Specifies the ID of the datasource.

The datasource keys are used as values, while a column specified in Label Data Name is used as label.

Label Data Name

Specifies the name of the column containing the label.

The default value is: label.

Values

note

This attribute has been deprecated since ver. 4.0

Labels

note

This attribute has been deprecated since ver. 4.0

Template

Specifies the template for the items.

The template can contain placeholders for the values of the items. The placeholders are specified as %0;, %1;, %2;, etc.

For example, if the template is %0; - %1;, %2; and the item is ["value", "label", "descr"], the result is value - label, descr.

If the template is not specified, the items' labels are displayed.

Wrap

Specifies the wrap mode.

The default value is: breakword.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Attribute Values

Value	Description
none	No wrap.
breakword	Default value. Wrap at word boundaries.
breakall	Wrap at any character.

Action

Action

Specifies the action to be performed when an item is selected.

The action is associated with the item's value.

In datasource mode, the item's value is the key or the index, if the key is missing.

For actions that send a command, the command name is specified in the Name attribute.

The default value is: none.

Attribute Values

Value	Description
none	Default value. No action.
select	Selects the item. The comma-separated list of item values is sent as a command on a submit action or when it changes, if Auto Send it true.
link	Opens the link specified as the item's value.
command	Sends a command with the item's value.
download	Downloads the file with path specified as the item's value.

Selection Mode

Specifies the selection mode.

The default value is: single.

Attribute Values

Value	Description
single	Default value. Single selection.
multi	Multiple selection.
multi-key	Multiple selection with keys modifiers: Ctrl/Meta to toggle, Shift to select range.

Name

Specifies the command name that is sent to the server.

If the name starts with $, then the server will automatically set a variable with the same name as the command, containing the command's parameter.

The default value is: =id.

Attribute Values

Value	Description	Example
<string>	A command name.
$[variable name]	A command name that sets a variable.	$myvar
$[variable name]!	A command name that sets a persistent variable.	$myvar!

Value

Specifies the value of the selected item.

Attribute Values

Value	Description	Example
<comma-separated list>	The values of the selected items.	value1,value2

Repeat

If enabled, the command will be repeated every second. Instead of a single command on the button press event, multiple commands are sent with the following suffixes:

• <command name>/down: on mouse down or touch down events
• <command name>/repeat: if the button is still pressed, a repeat command is sent every second
• <command name>/up: on mouse up or touch up events, for a short press (less than a second, so no repeat commands have been sent yet)
• <command name>/stop: on mouse up or touch up events, for a long press (more than a second, so at least a repeat command has been sent)

The default value is: false.

Attribute Values

Value	Description
false	Default value. Repeat mode is disabled.
true	Repeat mode is enabled.

Auto Send

Specifies whether the value is automatically sent on change or is sent through a button with submit action.

The default value is: false.

Attribute Values

Value	Description
auto	The value is sent only if there's no buttons with submit action in the same or a parent container.
true	The value is sent automatically on change.
false	Default value. The value is not automatically sent.

Required

Specifies if the field is required when submitting multiple fields with a submit button. If true, an empty/null value is considered not valid. When there are non valid fields, the submit button focuses the first non valid field instead of sending data to the server, to prompt the user to fill in the required fields.

The default value is: false.

Attribute Values

Value	Description
false	Default value. The field is not required.
true	The field is required.

Filter

Filter

Displays an input field for filtering the items. After typing a value in the field or setting the Filter Value attribute, any item that does not match the input will be hidden. A match occurs when the filter value is found anywhere within any item's fields ('value', 'label', etc).

The default value is: false.

Attribute Values

Value	Description
true	Display the filter field.
false	Default value. Hides the filter field.

Filter Placeholder

Specifies a short hint that is displayed in the filter field before the user enters a value. Describes the expected value of an input field (e.g. a sample value or a short description of the expected format)

Attribute Values

Value	Description
<string>	A short hint.

Filter Value

Specifies a string used as filter value. It's applied even if the filter field is hidden.

Attribute Values

Value	Description	Example
<string>	The filter string.	Jan 2015

Panel

Panel

Shows a panel that frames the object. Its style can be modified.

The default value is: true.

Attribute Values

Value	Description
true	Default value. Shows the panel.
false	Hides the panel.

Panel Color

Specifies the panel color.

The default value is: default.

Attribute Values

Value	Description
default	Default value. Default color.
primary	Primary color, used to highlight important areas.
warning	Warning color, used to highlight warning areas.
success	Success color, used to highlight success areas.
error	Error color, used to highlight error areas.
red,blue,yellow,green,yellow,purple,orange,green	Palette colors.
custom	Custom color, defined in the "Custom Color" attribute.

Panel Custom Color

Specifies the panel custom color.

Attribute Values

Value	Description	Example
<html color>	Color in any html accepted format.	#ff0000

Typography

Font Family

Specifies the font family.

The default value is: default.

Font Size

Specifies the font size in pixels or percentage (relative to the project's font size).

The default value is: 14.

Attribute Values

Value	Description	Example
<integer>	Font size in pixels.
<percentage>%	Relative font size in percentage.	90%

Font Color

Specifies the text CSS color.

Attribute Values

Value	Description	Example
<html color>	Color in any html accepted format.	#ff0000

Font Weight

Specifies the weight of the font.

The default value is: normal.

Attribute Values

Value	Description
normal	Default value. Normal.
bold	Bold.
bolder	Bolder.
lighter	Lighter.

Italic

Show the text in italics.

The default value is: false.

Attribute Values

Value	Description
false	Default value. Normal.
true	Italics.

Small Caps

Sets the font to small caps.

The default value is: false.

Attribute Values

Value	Description
false	Default value. Normal.
true	Small caps.

Decoration

Specifies the text decoration.

The default value is: none.

Attribute Values

Value	Description
none	Default value. No decoration.
underline	Underline.
overline	Overline.
line-through	Line through.

Text Align

Sets the horizontal alignment of the text.

The default value is: none.

Attribute Values

Value	Description
none	Default value. No alignment.
left	Left alignment.
right	Right alignment.
center	Center alignment.
justify	Justified alignment.

Line Height

Sets the line height of the text.

The default value is: 1.0.

Attribute Values

Value	Description
<float>	Specify the line height as a multiple of the font size.

Layout

Auto Scroll

Scrolls to the bottom of the list automatically, unless the user has scrolled up.

The default value is: false.

Attribute Values

Value	Description
false	Default value. False.
true	True.

Horizontal Borders

Displays horizontal borders.

The default value is: false.

Attribute Values

Value	Description
false	Default value. False.
true	True.

Striped

Adds zebra-striping to rows.

The default value is: false.

Attribute Values

Value	Description
false	Default value. False.
true	True.

Highlight Selected

Specifies wether the selected items are highlighted.

The default value is: true.

Attribute Values

Value	Description
true	Default value. Highlight.
false	No highlight.

CSS Style

note

This attribute has been deprecated since ver. 4.0

View

Visible

Sets the object's visibility.

The default value is: true.

Attribute Values

Value	Description
true	Default value. Visible.
false	Hidden.

Enabled

Specifies if the object is enabled or disabled. A disabled object appears as grayed out and can't be interacted with.

The default value is: true.

Attribute Values

Value	Description
true	Default value. Enabled.
false	Disabled.

Blink

Blinks the object at the specified speed.

The default value is: false.

Attribute Values

Value	Description
false	Default value. Not blinking.
slow	Blinks slowly.
fast	Blinks fast.

Transition

Specifies the transition effect when the object is shown or hidden.

The default value is: none.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Attribute Values

Value	Description
none	Default value. No transition.
fade	Fade in/out.
fade-left	Slide from left and fade in/out.
fade-right	Slide from right and fade in/out.
fade-up	Slide from top and fade in/out.
fade-down	Slide from bottom and fade in/out.
slide-left	Slide from left.
slide-right	Slide from right.
slide-up	Slide from top.
slide-down	Slide from bottom.
zoom-in	Zoom in.
zoom-out	Zoom out.
3d-flip-left	3D flip from left.
3d-flip-right	3D flip from right.

Transition Duration

Specifies the transition duration in milliseconds.

The default value is: 300.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Attribute Values

Value	Description
<integer>	Duration in milliseconds.

Transition Delay

Specifies the transition delay in milliseconds.

The default value is: 0.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Attribute Values

Value	Description
<integer>	Delay in milliseconds.

Opacity

Sets the object's opacity. Opacity is the degree to which content behind an object is hidden.

The default value is: 1.0.

Attribute Values

Value	Description
0	The object is fully transparent.
>0.0, <1.0	The object is translucent (content behind the element can be seen).
1.0	Default value. The object is fully opaque.

Rotation

Specifies the degrees by which the object is rotated. A positive number rotates it clockwise, while a negative value rotates it counter-clockwise.

The default value is: 0.

CSS Class

Specifies a CSS Class that applies to the object, useful to customize its appearance. Custom CSS Classes are specified within the custom.css file.

Margin

Specifies the margin of the object. The margin is the space outside the object's border.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Attribute Values

Value	Description	Example
<int>	Specify the margin in pixels for all sides of the object.
<top> <right> <bottom> <left>	Specify the margin in pixels for each side of the object.	10 20 30 40

View Scale

Specifies the scale of the object. The scale is the ratio between the object's size and the size of the view it is contained in.

The default value is: 1.0.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Attribute Values

Value	Description
<float>	Specify the scale for both width and height of the object.

Meta

Comment

Specifies a comment, visible only in the Project Editor. It can be used to add a note or a tag to the object. The filter in the object's SELECT panel applies to the comment as well.

note

This attribute is static. Its value can't be changed dynamically with a uiSet command or with a value binding.

Exclude

Excludes the object from the UI. Useful to temporarily hide an object without deleting it. Different from the "Visible" attribute, which hides the object in the UI but keeps it in the project, allowing it to be shown again with a UISet.

The default value is: false.

note

This attribute is static. Its value can't be changed dynamically with a uiSet command or with a value binding.

Attribute Values

Value	Description
false	Default value. Object is included in the UI.
true	Object is excluded from the UI.