Dropdown List
Component Palette Icon
The dropdown component is a great way to display a list of choices in a limited amount of space. The current selection is shown, and the choices are only presented when the user clicks on the dropdown button. The choices that are shown depend on the data property. This is a dataset, which can be typed in manually in the Designer, or (more commonly) it can be populated dynamically from a property binding, often a SQL Query binding.
It is often the case that you want to display choices to the user that are 'dressed up' versions of the actual choices. For instance, suppose that you are selecting choices for a downtime tracking entry. The choices might be: "Operator Error", "Machine Malfunction", and "Other". But, you really want to map these choices to some numeric code which is how the choice is stored. So, for instance, when the user chooses "Other" you really want to get the number 3. The dropdown component is perfect for such a use. The data property can be set up in one of three fashions, which control how the "selected values" properties change.
The dropdown component can operate in one of three Selection Modes. These modes affect how the dropdown's current selection (defined by the values of its Selected Value, Selected String Value, and Selected Label properties) behave when the selection properties are set to values not present in the choice list, or conversely, when the choice list is set to a new dataset that doesn't contain the current selection:
Strict: Selected values must always correlate to an option in the list defined by the Data property. If an invalid selection is set (via a binding or a script), the selection will be set to the values defined by the No Selection properties. If the Data property is set to a list that does not contain the current selection, the current selection will be reset to the No Selection values.
Lenient: (default) Selected values are independent of the list defined by the Data property. This mode is useful to avoid race conditions that can cause problems in Strict mode when both the Data and the Selected Value properties are bound. If the current selection is not present in the Data list, the read-only property Selected Index will be -1.
Editable: The same selection rules as defined by Lenient mode, except that the dropdown itself becomes editable, allowing a user to type in their own arbitrary value. This value will be set as the dropdown's Selected Label.
Properties
| Name | Description | Property Type | Scripting | Category |
|---|---|---|---|---|
| Antialias | Draw with antialias on? Makes text smoother. | boolean | .antialias | Appearance |
| Background Color | The background color of the component. | Color | .background | Appearance |
| Border | The border surrounding this component. Note that the border is unaffected by rotation. | Border | .border | Common |
| Cursor | The mouse cursor to use when hovering over this component. | int | .cursorCode | Common |
| Data | The data which fills up the combo box. Either a 1 or 2 column DataSet, with the first column being the value, and the second being the display | Dataset | .data | Data |
| Data Quality | The data quality code for any tag bindings on this component. | int | .dataQuality | Data |
| Dropdown Display Mode | Changes the dropdown's display. | int | .mode | Appearance |
| Enabled | If disabled, a component cannot be used. | boolean | .componentEnabled | Common |
| Font | Font of text on this component. | Font | .font | Appearance |
| Foreground Color | The foreground color of the component. | Color | .foreground | Appearance |
| Hide Table Columns? | A comma separated list of columns to hide from the dropdown table, eg. 0,2 (only used in table mode). | String | .hideTableColumns | Appearance |
| Horizontal Alignment | Determines the alignment of the contents along the X axis. | int | .horizontalAlignment | Layout |
| Max Row Count | The number of rows to display in the dropdown list before displaying a scrollbar. | int | .maximumRowCount | Appearance |
| Max Table Height | The maximum height allowed for the dropdown table. (Only used in table mode). | int | .maxTableHeight | Appearance |
| Max Table Width | The maximum width allowed for the dropdown table. (Only used in table mode). | int | .maxTableWidth | Appearance |
| Mouseover Text | The text that is displayed in the tooltip which pops up on mouseover of this component. | String | .toolTipText | Common |
| Name | The name of this component. | String | .name | Common |
| No Selection Label | The label to display when nothing is selected. | String | .noSelectionLabel | Behavior |
| No Selection String | The string value when nothing is selected. | String | .noSelectionString | Behavior |
| No Selection Value | The value when nothing is selected. | int | .noSelectionValue | Behavior |
| Selected Index | The index of the selected item. (Read only. Usable in bindings and scripting.) | int | .selectedIndex | Uncategorized |
| Selected Label | The currently selected label. | String | .selectedLabel | Data |
| Selected String Value | The currently selected value, if the value column is a string. | String | .selectedStringValue | Data |
| Selected Value | The currently selected value. | Integer | .selectedValue | Data |
| Selection Background | The background color of a selected cell in the dropdown list. | Color | .selectionBackground | Appearance |
| Selection Mode | The selection mode determines the behavior of the dropdown: whether its selected value must strictly be in the underlying set of choices, whether it is flexible, or even user-editable. | int | .selectionMode | Behavior |
| Show Table Header? | Selects whether or not the dropdown table header is displayed. (only used in table mode) | boolean | .showTableHeader | Appearance |
| Styles | Contains the component's styles. | Dataset | .styles | Appearance |
| Vertical Alignment | Determines the alignment of the contents along the Y axis. | int | .verticalAlignment | Layout |
| Visible | If disabled, the component will be hidden. | boolean | .visible | Common |
Scripting
Scripting Functions
This component does not have scripting functions associated with it.
Extension Functions
This component does not have extension functions associated with it.
Event Handlers
Event handlers allow you to run a script based off specific triggers. See the full list of available event handlers on the Component Events page
Customizers
Examples
Setting up Datasets
The three ways to set up the data dataset and the corresponding behavior are as follows:
Scenario 1: One column with a set of string values
| Column |
|---|
| Apples |
| Oranges |
| Bananas |
- Drop down displays values from the first column
- Selected value is undefined
- Selected String Value represents value from first column
- Selected Label represents value from first column
Scenario 2: Two column with an integer and string column
| Column 1 | Column 2 |
|---|---|
| 201 | Apples |
| 202 | Oranges |
| 203 | Bananas |
- Dropdown displays values from the second column
- Selected Value represents a value from the first column
- Selected String Value represents value from second column
- Selected Label represents value from second column
Scenario 3: Two column with two string columns
| Column 1 | Column 2 |
|---|---|
| APL | Apples |
| ORN | Oranges |
| BAN | Bananas |
- Dropdown displays values from second column
- Selected Value is undefined
- Selected String Value represents value from first column
- Selected Label represents value from second column
Display Multiple Columns in Dropdown
#The following code will return the first column value of the selection.
#This code would be on a button in the same container as the dropdown.
selRow = event.source.parent.getComponent('Dropdown').selectedIndex
pyData = system.dataset.toPyDataSet(event.source.parent.getComponent('Dropdown').data)
code = pyData[selRow][0]
print code
| Property Name | Value |
|---|---|
| Dropdown Display Mode | Table |
| Show Table Header | False |