Xojo Documentation Xojo Documentation

Popup Menu Library Icon

Popup Menu controls are useful when you have a single column of data to present in a limited amount of space. It presents a list of items and the user can choose one item. On macOS, when the user displays the Popup Menu’s items, the selected item is indicated by a checkmark.

Use the Set Default Value feature to add the default values that will appear in the list, one value per line.

Refer to PopupMenu in the Language Reference for details on all its events, properties and methods.

Below are the commonly used events, properties and methods.

Events

Change

Called when the selected item in the popup menu has changed.

Properties

RowValueAt

This property takes one parameter: an index of the row. It returns the text of the item in the popup menu specified by the index parameter. If the index does not exist, then an OutOfBoundsException is raised.

RowCount As Integer

An Integer containing the number of rows in the popup menu.

SelectedRowIndex As Integer

An Integer used to get or set the currently selected row in the popup menu.

SelectedRowValue As String

Contains the text of the currently selected row.

Methods

PopupMenu.AddRow, PopupMenu.AddAllRows

Takes as a parameter a string or an array of strings to add a row or rows to the Popup Menu.

AddSeparator

Adds a separator line (macOS only).

RemoveAllRows

Removes all rows from the Popup Menu.

AddRowAt

Takes as a parameter the row and name of item to insert into the Popup Menu.

RemoveRowAt

Takes as a parameter the number of the row to remove.

RowTag

Takes as a parameter the number of the row to which to assign the tag. The tag can be any value or class (variant).

Handling Focus

On Windows, when a PopupMenu receives the focus if the currently selected item is highlighted. It responds to the up and down arrow keys and provides the type selection functionality. For example, if the user types an “O” while the PopupMenu has the focus, the first entry with an “O” in it is highlighted. When a PopupMenu gets the focus on Linux, the currently selected item is highlighted. You can change the selected menu item with the up and down arrow keys.

Usage

This code in the Popup Menu Open event handler adds map directions to it:

Me.AddRow("North")
Me.AddRow("South")
Me.AddRow("East")
Me.AddRow("West")

This code in the Change event handler displays the selected direction:

If Me.SelectedRowIndex >= 0 Then
MessageBox(Me.SelectedRowValue)
End If

This could also be written more simply as:

MessageBox(Me.SelectedRowValue)

However, in this simplified version, if no value is selected, Me.SelectedRowValue will return an empty string. However, popup menus are not supposed to ever be displayed with no value selected.

See Also

PopupMenu class; UserGuide:Desktop Combo Box topic