Vision - Dropdown List
Component Palette Icon
The Dropdown component displays a list of choices in a limited amount of space. The list of choices is stored in a dataset, which can be manually typed in the Designer or populated dynamically from a property binding, often a SQL Query binding.
You may want to display choices to the user that are mapped to a different value internally, such as a numeric code. The columns in your dataset will determine which strings are visible to the end user (Selected Label) and which integers or strings are stored as the component's Selected Value or Selected String Value. There are three ways to configure a dropdown dataset:
Scenario 1: One column dataset with a set of string values​
| Column1 |
|---|
| Apples |
| Oranges |
| Bananas |
- Dropdown 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 dataset with an integer and a string column​
| Column1 | Column2 |
|---|---|
| 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 dataset with two string columns​
| Column1 | Column2 |
|---|---|
| APL | Apples |
| ORN | Oranges |
| BAN | Bananas |
- Dropdown displays values from the second column
- Selected Value is undefined
- Selected String Value represents value from first column
- Selected Label represents value from second column
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​
| Property | Description | Property Type | Scripting | Category |
|---|---|---|---|---|
| Background Color | The background color of the component. | Color | .background | Appearance |
| Border | The border surrounding this component. Options are: No border, Etched (Lowered), Etched (Raised), Bevel (Lowered), Bevel (Raised), Bevel (Double), Field Border, and Line Border. Note: The border is unaffected by rotation. Changed in 8.1.21 As of 8.1.21, the "Button Border" and "Other Border" options are removed. | Border | .border | Common |
| Cursor | The mouse cursor to use when hovering over this component. Options are: Default, Crosshair, Text, Wait, Hand, Move, SW Resize, or SE Resize. | int | .cursorCode | Common |
| Data | The dataset containing the list of choices in the dropdown. Either a one-column or two-column dataset. The first column is always the stored value, and the second column (if present) will be what is displayed to the user. | Dataset | .data | 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, for example, "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). Changed in 8.1.12 If Max Table Height is negative, the table popup will auto size to fill contents. | int | .maxTableHeight | Appearance |
| Max Table Width | The maximum width allowed for the dropdown table (only used in table mode). Changed in 8.1.12 If Max Table Width is negative, the table popup will auto size to fill contents. | 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 |
| Quality | The data quality code for any Tag bindings on this component. | QualityCode | .quality | Data |
| Row Height | Determines the height of each item in the dropdown list. The default is -1 pixels, which causes the row height to be determined automatically by the current font. | int | .rowHeight | Appearance |
| 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 if users can type into the component. | 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 |
Deprecated Properties​
| Property | Description | Property Type | Scripting | Category |
|---|---|---|---|---|
| Data Quality | The data quality code for any Tag bindings on this component. | int | .dataQuality | Deprecated |
Scripting​
Component Functions​
This component does not have component 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​
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 |