Construct 3 icon

Construct 3

Documentation

List

Published 24 Aug, 2017
916 words
~4-6 mins

The List object creates either a dropdown list or list box form control. A dropdown list only shows one item but can be expanded to show the full list; a list box shows multiple items at once. The image below shows a dropdown list on the left (which has been expanded), and a list box on the right.

List typesList types

Form controls are actual HTML elements floating above the game canvas in the HTML page. Therefore, nothing can be displayed on top of a form control, apart from other form controls.

Form controls position themselves according to the layer parallax, scale and so on. However they are not truly "in the game" (since they float above), so it is recommended to avoid using scrolling, parallax and layer scaling with form controls, otherwise the end result can feel unnatural.

Styling List objects

List form controls can be customised in a huge number of ways via CSS (Cascading Style Sheets). Rather than adding actions to set all of the possible properties, the List object exposes a Set CSS style action. Knowing CSS will of course be an advantage here, but it is simple to use for simple properties. A few examples are listed below.

Make the text red: Set "color" to "red"

Make the background yellow: Set "background-color" to "yellow"

Make the border a thick light grey: Set "border" to "3px solid #AAAAAA"

Make the font bigger: Set "font-size" to "2em"

Make a dashed red border: Set "border" to "2px dashed red"

List properties

Items

A list of the initial items to display in the list, with one item per line. Click the button to the right of the property to open a multi-line text box in a dialog to edit this more conveniently. The property field cannot show line breaks,

so instead represents lines with the special \n escape sequence.

Tooltip

A tooltip that appears in most browsers if the user hovers the mouse over the button and waits. Leave blank for no tooltip.

Initially visibile

Whether or not the control is initially visible in the layout.

Enabled

Whether the control is initially enabled. If disabled, the control will appear greyed out and the selection cannot be modified.

Type

Choose between the List box and Dropdown list control styles. An image displaying the two types is shown above.

Multi-select

Allow more than one item to be selected when Type is List box. This has no effect for dropdown lists.

Auto font size

Automatically set the font-size property of the element according to the layout and layer scale. This will prevent the font-size CSS property being manually set with the Set CSS style action. Disable if you intend to use Set CSS style to adjust the font-size property.

ID Optional

An optional id attribute for the element in the DOM (Document Object Model). This can be useful for accessing the element's value from external scripts, or styling with CSS in the HTML page.

List conditions

Compare item text at

Compare the text of a given item in the list.

Compare selected item text

Compare the text of the currently selected item in the list.

Compare selection

Compare the zero-based index of the currently selected item.

On clicked

Triggered when the control is clicked.

On double-clicked

Triggered when the control is double-clicked.

On selection changed

Triggered whenever the chosen selection in the control is changed. This can be by any means of input (such as a mouse click, keyboard press, or touch input on mobile).

List actions

Set CSS style

Set a CSS (Cascading Style Sheets) style on the list element. For more information, see the section Styling List objects. Note that if the Auto font size property is enabled, any changes to the font-size property will be overridden.

Add item

Append a new item to the end of the list of available choices.

Add item at

Insert a new item to the list of available choices at a certain zero-based index.

Clear

Remove all the available choices from the list.

Remove

Delete an item at a specific index.

Set item text

Change the text of an item at a specific index.

Set selection

Set the item at a specific index as selected.

Set enabled

Enable or disable the control. If disabled, it will appear greyed out and the selection cannot be modified.

Set tooltip

Set the Tooltip property of the object, displayed by most browsers when hovering the mouse over the control.

Set focused

Set unfocused

Either set or unset the input focus to this control. When focused, keyboard input affects the control.

List expressions

ItemCount

The current number of items in the list.

ItemTextAt

Return the text of an item at a zero-based index in the list.

SelectedCount

The number of currently selected items. This will always be either 0 or 1 unless a list box with Multi-select enabled is used.

SelectedIndex

The zero-based index of the currently selected item. For multi-select lists, use SelectedIndexAt instead.

SelectedIndexAt

The index of a selected item out of all the selected items. In other words, SelectedIndexAt with numbers 0 to SelectedCount - 1 gives the indices of all the selected items.

SelectedText

The text of the currently selected item. For multi-select lists, use SelectedTextAt instead.

SelectedTextAt

The text of a selected item out of all the selected items. In other words, SelectedTextAt with numbers 0 to SelectedCount - 1 gives the text of each selected item.