List box

Properties
Functions

The List Box control displays a list of elements and allows you to select one or several of them. For longer lists, you might need to use the vertical scroll bar on the right to access all the elements.

You can link this control to a String variable or parameter. In this case, when you select an element from the list box, the linked variable or parameter immediately takes the element’s name as its value.

To add a list box

In the Controls palette, find the List Box element and drag it into the graphical editor.
Navigate to the Properties section on the right.
If you want to link the list box with a String variable or parameter, select the respective element from the drop-down list in the Link to field or using the Select on canvas feature. To switch to the Dynamic value mode, click the button to the left of the Link to field.
On choosing an element from the list box, the linked variable or parameter immediately gets this value. You can also easily link a control to a parameter of a flowchart block. To learn more about linking controls to parameters, see Linking controls to parameters.
You can also define an action to execute each time the value of the list box changes. Type the corresponding code into the Action section. The current value of the list box is available here as value, a String variable that holds the label of the selected item.

Properties

General

Name — The name of the list box. It is used to identify and access the control from code.

Show name — If selected, the list box name is shown next to the element.

Lock — Specifies if the list box is fixed on the canvas. You cannot move or select a locked element in the graphical editor.

Ignore — If selected, the list box is excluded from the model.

Multiple selection — [Visible if Link to is empty] This feature allows you to select two or more list box items at the same time.

Items — The table defining items that will appear in the list box.
You can rearrange the items by dragging them using the button. To remove an item, select the corresponding row in the table and click the button.

Link to — The field links the list box to a String variable or parameter. Select the respective element from the drop-down list in the Link to field or use the Select on canvas feature. In order to switch to the Dynamic value mode, click the button on the left. On choosing an element from the list box, the linked variable or parameter immediately gets this value.
You can also easily link a control to a parameter of a flowchart block. To learn more about linking controls to parameters, see Linking controls to parameters.

Default value — [Visible if the Link to field is empty] The field for assigning an item to be selected in the list box by default.
For instance, your list box has Items named red and green. To make green selected by default, enter the item name in quotation marks: "green".

Action — The code to execute when the user uploads or downloads a file through the file chooser. The relative name of a selected file is available here as a local String variable named value.

Appearance

Enabled — Specifies whether the file chooser is active during runtime using a Boolean expression or a check box.

Background color — Defines the background color for the dialog box. Click the control and pick a color from a range of the most popular ones or choose a custom color using the Colors dialog box.

Text color — This control specifies the color of the text displayed inside the list box. Click inside the control and pick a color from a range of the most popular ones or choose a custom color using the Colors dialog box.

Font — Allows you to adjust the size of the text inside the list box using a drop-down menu.

Italic — If selected, the text inside the list box will be italicized.

Bold — If selected, the text inside the list box will be emphasized in bold.

Position and size

Level — The level this control belongs to.

X — The X-coordinate of the control’s upper left corner.

Y — The Y-coordinate of the control’s upper left corner.

Width — The width of the control (in pixels).

Height — The height of the control (in pixels).

Visibility and presentation

Visible — If selected, the list box is shown during runtime. To introduce a dynamic value, click the button and enter the code in the input field. The control will be visible when the specified expression evaluates to true.

Agent presentation — If selected, the control is included in the agent presentation. This means that if the agent hosting this control is embedded in another agent, the control will remain visible.

Agent icon — If selected, the list box will be considered a part of the agent’s icon.

Expert

Replication — The number of copies of this control that you want created. If this field is left empty, only one control will be created. This field can be set to a dynamic expression.

Functions

Obtaining values and indices

Function	Description
String getValue()	Returns the value for the only selected item or for the first item in the selection. Returns null if no items are selected.
int getValueIndex()	Returns the index for the only selected item or for the first item in the selection. If there is no selection, returns -1.
String[] getValues()	Returns an array of selected items. If there is no selection, returns an empty array.
int[] getValuesIndices()	Returns an array of indices for the item selection. If there is no selection, returns an empty array.
String[] getItems	Returns an array of values for the entire list box. If there is no selection, returns an empty array. Due to internal restrictions, the array should not be changed manually.

Assigning new values

Function	Description
void setValue(String text)	Assigns a new value to the selected text item. If text is null, clears list box selection. Does not execute the user action code. text — the selected text item or null.
void setValue(String text, boolean callAction)	Assigns a new value to the selected text item. Clears the selection if text is null. If the callAction parameter is true, executes the action code (if there is any). text — the newly selected text item or null. callAction — if true, the user action code (if there is any) will be executed.
void setValueIndex(int valueIndex)	Selects the item with the given index. If valueIndex is negative, clears the list box selection. Does not execute the user action code. valueIndex — the item index.
void setValueIndex(int valueIndex, boolean callAction)	Selects the item with the given index. Clears the list box selection if valueIndex is negative. If callAction parameter is true, executes the user action code (if there is any). valueIndex — the item index. callAction — if true, the user action code (if there is any) will be executed.
void setValues(String[] texts)	Assigns new values to the selected text items. Clears the selection if texts is null or empty. Does not execute the user action code. texts — the new selected text items or null.
void setValues(String[] texts, boolean callAction)	Assigns new values to the selected text items. Clears the selection if texts is null or empty. Executes the user action code (if there is any) if the callAction parameter is true. texts — the new selected text items or null. callAction — if true, the user action code (if there is any) will be executed.
void setValuesIndices(int[] valuesIndices)	Selects items with the given indices in the multiple selection mode. Clears the selection if valuesIndices is null or empty. Does not execute the user action code. valuesIndices — the list of item indices.
void setValuesIndices(int[] valuesIndices, boolean callAction)	Selects items with the given indices in the multiple selection mode. Clears the selection if valuesIndices is null or empty. Executes the user action code (if there is any), if callAction parameter is true. valuesIndices — the item index. callAction — if true, the user action code (if there is any) will be executed.
void setValueToDefault()	Assigns a default value to the list box. Does not execute the user action code.

Selecting items and assigning values

Function	Description
void setValueIndex (int valueIndex)	Selects the item at the given index. Clears the selection if valueIndex is negative. Does not execute the action code. valueIndex — the item index.
void setValueIndex (int valueIndex, boolean callAction)	Selects the item at the given index and executes the action code. valueIndex — the item index. callAction — if true, user action code (if any) will be executed.
void setValue (String text)	Assigns a value to the selected item. Clears the selection if text is null. Does not execute the user action code. text — the new selected text item or null. callAction — if true, user action code (if any exists) will be executed.
void setValuesIndices (int[] valuesIndices)	Returns the value for the only selected item or for the first item in the selection. When there is no selection, returns null. valuesIndices — the item index.
void setValuesIndices(int[] valuesIndices, boolean callAction)	Returns the value for the only selected item or for the first item in the selection. When there is no selection, returns null. valuesIndices — the item index. callAction — if true, user action code (if any exists) will be executed.
void setValues(String[] texts)	Assigns values to the selected items. Clears the selection if texts is null. Does not execute the user action code. texts — the new selected text items or null.
void setValues(String[] selectedTexts, boolean callAction)	Assigns values to the selected items. Clears the selection if texts is null. Executes the user action code. selectedTexts — the new selected text items or null. callAction — if true, user action code (if any exists) will be executed.
setItems(String[] items)	Returns an array of values for the entire list box. If there is no selection, returns an empty array. items — the array of String items to be placed in this list box. Due to internal restrictions, the array should not be changed manually.
setItems(String[] items, boolean callAction)	Returns an array of values for the entire list box. If there is no selection, returns an empty array. items — the array of String items to be placed in the list box. callAction — if true and selection changes, user action code (if any exists) will be executed. Due to internal restrictions, the array should not be changed manually.
String[] getItems()	Returns an array of String items currently used in the list box. The returned array is the same as the one passed to setItems(String[]), and may be null. The returned array should not be changed by user.

Adding new items

Function	Description
void setItems(String[] items)	Assigns values to the new items. This function preserves current values if they are contained in new items. This function does not execute the user action code (even if the current selection changes). items — the array of String items to be placed in this list box. Due to internal restrictions, the array should not be changed manually.
void setItems(String[] items, boolean callAction)	Assigns values to the new items. This function preserves current list box values if they are contained in new items. This function does not execute the user action code (even if current selection changes). items — the array of String items to be placed in the drop-down list. callAction — if true and the selection changes, the user action code (if there is any) will be executed.

Enabling and disabling

Function	Description
boolean isEnabled()	Tests if the control is enabled (returns true) or disabled (returns false).
void setEnabled(boolean yes)	Sets the control as enabled or disabled in runtime. yes — The list box will be enabled if true and disabled if false.

Executing the action

Function	Description
void action()	Executes the action associated with the list box.

Position

Function	Description
double getX()	Returns the X-coordinate of the control (upper left corner).
double getY()	Returns the Y-coordinate of the control (upper left corner).
void setX(double x)	Assigns the X-coordinate to the control (upper left corner). x — the new X-coordinate value.
void setY(double y)	Assigns the Y-coordinate to the control (upper left corner). y — the new Y-coordinate value.
void setPos(double x, double y)	Assigns new coordinates to the control (upper left corner). x — the new X-coordinate value. y — the new Y-coordinate value.

Visibility

Function	Description
boolean isVisible()	Returns the visibility of the control.
void setVisible(boolean v)	Sets the visibility of the control. v — visibility: if true, the control is set to be visible, if false, it is not.

Group

Function	Description
ShapeGroup getGroup()	Returns the group containing this control.

Level

Function	Description
Level getLevel()	Returns the level on which this control is located.

How can we improve this article?