Skip to main content
Version: 7.9

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.


NameDescriptionProperty TypeScriptingCategory
AntialiasDraw with antialias on? Makes text smoother.boolean.antialiasAppearance
Background ColorThe background color of the component.Color.backgroundAppearance
BorderThe border surrounding this component. Note that the border is unaffected by rotation.Border.borderCommon
CursorThe mouse cursor to use when hovering over this
DataThe 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 displayDataset.dataData
Data QualityThe data quality code for any tag bindings on this
Dropdown Display ModeChanges the dropdown's
EnabledIf disabled, a component cannot be used.boolean.componentEnabledCommon
FontFont of text on this component.Font.fontAppearance
Foreground ColorThe foreground color of the component.Color.foregroundAppearance
Hide Table Columns?A comma separated list of columns to hide from the dropdown table, eg. 0,2 (only used in table mode).String.hideTableColumnsAppearance
Horizontal AlignmentDetermines the alignment of the contents along the X
Max Row CountThe number of rows to display in the dropdown list before displaying a
Max Table HeightThe maximum height allowed for the dropdown table. (Only used in table mode).int.maxTableHeightAppearance
Max Table WidthThe maximum width allowed for the dropdown table. (Only used in table mode).int.maxTableWidthAppearance
Mouseover TextThe text that is displayed in the tooltip which pops up on mouseover of this component.String.toolTipTextCommon
NameThe name of this component.String.nameCommon
No Selection LabelThe label to display when nothing is selected.String.noSelectionLabelBehavior
No Selection StringThe string value when nothing is selected.String.noSelectionStringBehavior
No Selection ValueThe value when nothing is
Selected IndexThe index of the selected item. (Read only. Usable in bindings and scripting.)int.selectedIndexUncategorized
Selected LabelThe currently selected label.String.selectedLabelData
Selected String ValueThe currently selected value, if the value column is a string.String.selectedStringValueData
Selected ValueThe currently selected value.Integer.selectedValueData
Selection BackgroundThe background color of a selected cell in the dropdown list.Color.selectionBackgroundAppearance
Selection ModeThe 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
Show Table Header?Selects whether or not the dropdown table header is displayed. (only used in table mode)boolean.showTableHeaderAppearance
StylesContains the component's styles.Dataset.stylesAppearance
Vertical AlignmentDetermines the alignment of the contents along the Y
VisibleIf disabled, the component will be hidden.boolean.visibleCommon


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



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

  • 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 1Column 2
  • 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 1Column 2
  • 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

Code Snippet
#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 NameValue
Dropdown Display ModeTable
Show Table HeaderFalse