List Box

This control displays a list of elements and allows a user to choose one (or several) elements. If certain elements do not fit in the allotted area, you can use the vertical scroll bar on the right to see all the elements of the list.

You can link this control to a variable or a parameter of type String. In this case when the user chooses another element from the list box, the linked variable/parameter immediately takes element's name as its value.

 To add a list box
  1. Drag the List Box element from the  Controls palette into the graphical editor.
  2. Navigate to the Properties view.
  3. If you want to bind the list box with a variable or a parameter of type String (on changing the value of the list box, the linked variable/parameter immediately gets this value), you should select the Link to checkbox and choose the name of the parameter from the drop-down list to the right. You can also easily link a control to a parameter of a flowchart block. Linking controls to parameters is thoroughly described here.
  4. You can also define any action to be executed each time the value of the list box is changed. Type the code you want to execute in this case into the Action section (the current value of the list box is available here as value (String variable, holding the label of the currently selected item)). 

Properties

General

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

Ignore – If selected, the list box will be excluded from the model.

Visible on upper level – If selected, the control will be also visible on the upper level where this agent lives.

Multiple selection –  [Enabled if the Link to checkbox is not selected] If selected, a user will be allowed to select multiple items at the same time.

Items – The table defining items that will appear in the list box. 
To remove an item, select the corresponding row in the table and click the "cross" button. Items can be rearranged using arrow keys to the right of the table.

Link to – If you want to bind the list box with a variable or a parameter of type String (on choosing another element from the list box, the linked variable/parameter immediately gets element's name as its value), select this checkbox and enter the name of the variable/parameter you want to link to the list box.

Default value – [Visible if the Link to checkbox is not selected] Expression evaluating String name of the item that will be chosen in the list box by default.
For instance, your list box has Items called red and green. To make green selected by default, type here the item name in inverted commas: "green"

Enabled – Here you can specify Boolean expression determining whether the list box is enabled or disabled.

Action

Here you can type the code to execute when user selects another item of the list box. The currently selected item is available here as value  (String variable, holding the label of the item).

Appearance

Background color – The control specifies the background color for the list box. Click inside the control and choose a color from the set of most used ones, or choose some custom color using the Colors dialog box.

Text color – The control specifies the color of the text displayed inside the list box. Click inside the control and choose a color from the set of the most used ones, or choose a custom color using the Colors dialog box.

Font – Specifies the font family for the text displayed inside the list box. You can adjust the size of the text In the field to the right (pt.).

Italic – If checked, the text displayed inside the list box will be italicized.

Bold – If checked, the text displayed inside the list box will be emphasized in bold.

Position and size

X – X-coordinate of the control's upper left corner.

Y – 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).

Advanced

Visible – The control's visibility. The control is visible when the specified expression evaluates to true, otherwise it is not visible.

Replication – Here you specify the number of copies of this control you want to be created. If you leave this field empty, only one such control will be created.

Show name – If selected, the name of the control will be displayed on a presentation diagram.

Icon – If selected, the list box will be considered as a part of the agent's icon.

Functions

Obtaining the currently selected value(s)

Function

Description

String getValue()

Returns the currently selected text item if in single-selection mode, or the first selected text item if in multiple-selection mode.

Returns null if there is no selection.

int getValueIndex()

Returns the index of the currently selected text item or -1 when there is no selection.

Returns the first selected text item if in multiple-selection mode.

String[] getValues()

Returns an array of selected text items (for use in multiple-selection mode).

Returns empty array if there is no selection.

int[] getValuesIndices()

Returns an array of selected items' indices (for use in multiple-selection mode).

Returns empty array if there is no selection 


Setting new selected value(s)

Function

Description

void setValue
(String text)

Sets the selected text item of the list box.
Clears list box selection if text is null.
Doesn't execute user action code.

Parameter:
text - the new selected text item or null

void setValue
(String text,
boolean callAction)

Sets the selected text item of the list box. Clears list box selection if text is null. Executes user action code (if there is any), if callAction parameter is true.

Parameters:
text - the new selected text item or null
callAction - if true, user action code (if there is any) will be executed

void setValueIndex
(int valueIndex)

Selects the item with the given index.
Clears list box selection if valueIndex is negative.
Doesn't execute user action code.

Parameter:
valueIndex - the item index

void setValueIndex
(int valueIndex,
boolean callAction)

Selects the item with the given index. Clears list box selection if valueIndex is negative.

Executes user action code (if there is any) if callAction parameter is true.

Parameters:
valueIndex - the item index
callAction - if true, user action code (if there is any) will be executed

void setValues
(String[] texts)

Sets the selected text items of the list box (in the multiple-selection mode)

Clears list box selection if texts is null or empty

Doesn't execute user action code

Parameter:
texts - the new selected text items or null

void setValues
(String[] texts,
boolean callAction)

Sets the selected text items of the list box (in the multiple-selection mode).

Clears list box selection if texts is null or empty.

Executes user action code (if there is any) if callAction parameter is true.

Parameters:
texts - the new selected text items or null
callAction - if true, 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 list box selection if valuesIndices is null or empty.

Doesn't execute user action code.

Parameter:
valuesIndices - the item index

void setValuesIndices
(int[] valuesIndices,
boolean callAction)

Selects items with the given indices (in the multiple-selection mode)

Clears list box selection if valuesIndices is null or empty.

Executes user action code (if there is any), if callAction parameter is true.

Parameters:
valuesIndices - the item index
callAction - if true, user action code (if there is any) will be executed

void setValueToDefault()

Sets the text of the list box to what was provided as the default one.

Doesn't execute user action code.


Enabling/disabling the control

Function

Description

boolean isEnabled()

Tests if the control is enabled or disabled. Returns true if enabled, otherwise false.

void setEnabled
(boolean yes)

Sets the control enabled or disabled.

Parameter:
yes - If true, the control will be enabled, if false - disabled. 


Executing the list box action programmatically

Function

Description

void action()

Executes the action associated with a list box.


Accessing list box items

Function

Description

String[] getItems()

Returns array of String items currently used in this list box.

Note that returned array is the same as has been passed to setItems(String[]), and may be null.

The returned array should not be changed by user 


Adding new list box items

Function

Description

void setItems
(String[] items)

Sets new items for this list box. This function preserves current list box values if current values are contained in new items. This function doesn't execute user action code (even if current selection changes). 

Note that provided array is used internally and shouldn't be changed by user after this function is called.

Parameter:
items - the array of String items to be placed in this list box

void setItems
(String[] items,
boolean callAction)

Sets new items for this list box. This function preserves current list box values if current values are contained in new items. This function doesn't execute user action code (even if current selection changes). 

Note that provided array is used internally and shouldn't be changed by user after this function is called.

Parameters:
items - the array of String items to be placed in the combo box drop-down list
callAction - if true and selection changes, user action code (if there is any) will be executed


List box position

Function

Description

double getX()

Returns the X coordinate of the control (namely, the X coordinate of its upper left corner).

double getY()

Returns the Y coordinate of the control (namely, the Y coordinate of its upper left corner).

void setX(double x)

Sets the X coordinate of the control.

Parameter:
x - the new value of X coordinate

void setY(double y)

Sets the Y coordinate of the control.

Parameter:
y - the new value of Y coordinate

void setPos(double x,
double y)

Sets new coordinates for the control.

Parameters:
x - the new value of x coordinate
y - the new value of y coordinate


List box visibility

Function

Description

boolean isVisible()

Returns the visibility of the control.

void setVisible(boolean v)

Sets the visibility of the control.

Parameter:
v - visibility: if true - the control is set to be visible, if false - not visible.


Related topics

 Aligning shapes

 API reference: ShapeListBox class