Combo Box


The component that combines editable field and a drop-down list. A user can select a value from the drop-down list. If you make the combo box editable, the combo box will include an editable field into which the user can type new values not present in the control by default.

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

If you want to allow a user to choose multiple items simultaneously, use the list box control.

 To add a combo box
  1. Drag the  Combo Box element from the  Controls palette into the graphical editor.
  2. Navigate to the Properties view.
  3. You can bind the combo box with a variable or a parameter of type String, double or int (on changing the value of the combo box, the linked parameter/variable immediately gets this value). To link the control to a parameter, 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 combo box is changed. Type the code you want to execute into the Action section (the current value of the combo box is available here as value (String variable, holding the label of the currently selected item)). 

Properties

General

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

Ignore – If selected, the combo 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.

Items – The table defining items that will appear in the drop-down list of the combo 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.

Editable – If selected, user will be allowed to specify any other values in addition to those present in the drop-down list. 

Link to – If you want to bind the combo box with a variable or a parameter of type String, double or int (on changing the value of the combo box, the linked parameter/variable immediately gets this value), select this checkbox and enter the name of the variable/parameter that you want to link to the combo 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 combo box by default.
As for instance, your combo box has Items called FirstOption and SecondOption. To make SecondOption the default value of the combo box, type the item name in inverted commas: "SecondOption"

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

Action

Here you can type the code to execute when the user selects another item of the combo 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 combo 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.
Background color is correctly displayed under Windows with Classic appearance. However, certain operating systems may not support combo boxes with user-defined background colors (Windows XP with XP-style appearance, Windows Vista with Windows Vista Basic or Windows Aero appearance).

Text color – The control specifies the color of the text that is shown inside the control. 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 that is shown inside the control. You can adjust the size of the text in the field to the right (pt.).

Italic – If selected, the text in the control will be italicized.

Bold – If selected, the text in the control 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 combo box will be considered as a part of the agent's icon.

Functions

Obtaining the currently selected value

Function

Description

String getValue()

Returns the currently selected text item. 

int getIntValue()

Returns the current int value of the combo box.
Function throws an exception when the value is not a number.

double getDoubleValue()

Returns the current double value of the combo box.
Function throws an exception when the value is not a number. 

int getValueIndex()

Returns the index of the currently selected text item or -1 when this is editable combo box and it doesn't contain entered value.

Setting new selected value

Function

Description

void setValue(double value)

Sets the numeric value of the combo box with value type ShapeControl.TYPE_DOUBLE or ShapeControl.TYPE_INT.

Doesn't execute user action code

Parameter:
value - the new value (double or int)

void setValue(double value, boolean callAction)

Sets the numeric value of the combo box with value type ShapeControl.TYPE_DOUBLE or ShapeControl.TYPE_INT.

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

Parameters:
value - the new value (double or int)
callAction - if true, user action code (if there is any) will be executed

void setValue(String text)

Sets the selected text item of the combo box.
Doesn't execute user action code

Parameter:
text - the new selected text item

void setValue(String text, boolean callAction)

Sets the selected text item of the combo box. Executes user action code (if there is any) if callAction parameter is true.
If value-type is numeric and the given text isn't a valid number, nothing will be changed

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

void setValueIndex(int valueIndex)

Selects the item with the given index.
Doesn't execute user action code

Parameter:
valueIndex - the item index

void setValueIndex(int valueIndex, boolean callAction)

Selects the item with the given index. 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 setValueToDefault()

Sets the text of the combo 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 combo box action programmatically

Function

Description

void action()

Executes the action associated with a combo box.

Accessing combo box items

Function

Description

String[] getItems()

Returns array of String items currently used in the combo box drop-down list
The returned array should not be changed by user 

Adding new combo box items

Function

Description

void setItems
(String[] items)

Sets new items for this combo box. This function preserves current combo box value:

  • if it is editable
  • if it is not-editable and current value is contained in new texts

This function doesn't execute user action code (even if current selection changes)
This function throws an exception if this combo box has numeric value-type (ShapeControl.TYPE_DOUBLE or ShapeControl.TYPE_INT) and some item(s) can't be parsed as a number.

Parameter:
items - the array of String items to be placed in the combo box drop-down list

void setItems
(String[] items,
boolean callAction)

Sets new items for this combo box. This function preserves current combo box value:

  • if it is editable
  • if it is not-editable and current value is contained in new texts


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 any exists) will be executed

Combo 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 combo box.

Parameter:
x - the new value of X coordinate

void setY(double y)

Sets the Y coordinate of the combo box.

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

Combo 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: ShapeComboBox Class