Class
# MobilePopupMenu
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
## Description
Displays a list of items when clicked. The user can select one item from the list.
## Properties
table-centered_columns_3_and_4
| Name | Type | Read-Only | Shared |
|----------------------------------------------------------|---------------------------------------------------------------|-----------|--------|
| `AccessibilityHint` | `String` | | |
| `AccessibilityLabel` | `String` | | |
| `ControlCount` | `Integer` | ✓ | |
| `Enabled` | `Boolean` | | |
| `Height` | `Integer` | | |
| `InitialValue` | `String` | ✓ | |
| `LastAddedRowIndex` | `Integer` | ✓ | |
| `LastRowIndex` | `Integer` | ✓ | |
| `Left` | `Integer` | | |
| `LockBottom` | `Boolean` | | |
| `LockLeft` | `Boolean` | | |
| `LockRight` | `Boolean` | | |
| `LockTop` | `Boolean` | | |
| `Name` | `String` | ✓ | |
| `Parent` | `MobileUIControl` | ✓ | |
| `RowCount` | `Integer` | ✓ | |
| `SelectedRowIndex` | `Integer` | | |
| `SelectedRowText` | `String` | ✓\` | |
| `Top` | `Integer` | | |
| `Visible` | `Boolean` | | |
| `Width` | `Integer` | | |
## Methods
table-centered_column_4
| Name | Parameters | Returns | Shared |
|--------------------------------------------------------|-------------------------------------------------------------------------------------------|---------------------------------------------|--------|
| `AddAllRows` | items() As `String` | | |
| | `ParamArray` items As `String` | | |
| `AddRow` | item As `String` | | |
| `AddRowAt` | rowNumber As `Integer`, item As `String` | | |
| `ClearFocus` | | | |
| `Handle` | | `Ptr` | |
| `Refresh` | | | |
| `RemoveAllRows` | | | |
| `RemoveRowAt` | index As `Integer` | | |
| `RowTagAt` | index As `Integer` | `Variant` | |
| `RowTextAt` | index As `Integer` | `String` | |
| `SelectRowWithTag` | value As `Variant` | | |
| `SelectRowWithText` | value As `String` | | |
| `SetFocus` | | | |
## Events
table-centered_column_4
| Name | Parameters | Returns |
|------------------------------------------------------|------------|---------|
| `Closing` | | |
| `Opening` | | |
| `SelectionChanged` | | |
## Property descriptions
forsearch
MobilePopupMenu.AccessibilityHint
**AccessibilityHint** As `String`
> The accessibility hint is a longer description that is read aloud when VoiceOver is enabled.
>
> ``` xojo
> Me.AccessibilityHint = "Click to calculate the value and display the next screen."
> ```
forsearch
MobilePopupMenu.AccessibilityLabel
**AccessibilityLabel** As `String`
> The accessibility label of of a control is a short name that is read aloud when VoiceOver is enabled.
>
> ``` xojo
> Me.AccessibilityLabel = "Calculate the value."
> ```
forsearch
MobilePopupMenu.ControlCount
**ControlCount** As `Integer`
> The number of child controls in the control.
>
> This property is read-only.
forsearch
MobilePopupMenu.Enabled
**Enabled** As `Boolean`
> Indicates whether the control is enabled or disabled.
>
> Disable the popupmenu:
>
> ``` xojo
> PopupMenu1.Enabled = False
> ```
forsearch
MobilePopupMenu.Height
**Height** As `Integer`
> The height of the control.
forsearch
MobilePopupMenu.InitialValue
**InitialValue** As `String`
> A list of the default items separated by returns.
>
> This property is read-only.
>
> This property is unreadable at runtime because the list is removed from memory once the control is created. You can set a default value for the control by populating the pop-up with *InitialValue* and setting the default value with *SelectedRowIndex*.
forsearch
MobilePopupMenu.LastAddedRowIndex
**LastAddedRowIndex** As `Integer`
> The number of the last row added with the AddRow or AddRowAt method.
>
> This property is read-only.
>
> If no rows have been added, LastAddedRowIndex will be -1.
forsearch
MobilePopupMenu.LastRowIndex
**LastRowIndex** As `Integer`
> The index of the last row of the MobilePopupMenu.
>
> This property is read-only.
forsearch
MobilePopupMenu.Left
**Left** As `Integer`
> The left position of the control.
forsearch
MobilePopupMenu.LockBottom
**LockBottom** As `Boolean`
> Determines whether the bottom edge of the control should stay at a set distance from the bottom edge of the parent control, if there is one, or the owning screen.
>
> This property can be set in the control's Inspector. The following example sets it in code.
>
> ``` xojo
> Me.LockBottom = True
> ```
forsearch
MobilePopupMenu.LockLeft
**LockLeft** As `Boolean`
> Determines whether the left edge of the control should stay at a set distance from the left edge of the parent control, if there is one, or the owning screen.
>
> LockLeft and Locktop default to `True` when you add a new control to a screen. Existing controls will be altered only if LockRight and/or LockBottom are not set. *LockLeft* has no effect unless *LockRight* is `True`.
>
> This property can be set in the control's Inspector. The following example sets it in code.
>
> ``` xojo
> Me.LockLeft = True
> ```
forsearch
MobilePopupMenu.LockRight
**LockRight** As `Boolean`
> Determines whether the right edge of the control should stay at a set distance from the right edge of the parent control, if there is one, or the owning screen.
>
> This property can be set in the control's Inspector. The following example sets it in code.
>
> ``` xojo
> Me.LockRight = True
> ```
forsearch
MobilePopupMenu.LockTop
**LockTop** As `Boolean`
> Determines whether the top edge of the control should stay at a set distance from the top edge of the parent control, if there is one, or the owning screen.
>
> LockTop and LockLeft default to `True` when you add a control to a screen. Existing controls will be altered only if LockRight and/or LockBottom are not set. *LockTop* has no effect unless *LockBottom* is `True`.
>
> This property can be set in the control's Inspector. The following example sets it in code.
>
> ``` xojo
> Me.LockTop = True
> ```
forsearch
MobilePopupMenu.Name
**Name** As `String`
> The name of the control.
>
> This property is read-only.
forsearch
MobilePopupMenu.Parent
**Parent** As `MobileUIControl`
> The parent (sometimes called a "Super") class of the control.
>
> This property is read-only.
forsearch
MobilePopupMenu.RowCount
**RowCount** As `Integer`
> The number of rows in the popup menu.
>
> This property is read-only.
>
> This example displays the number of rows in the popup menu.
>
> ``` xojo
> MessageBox(FruitPopup.RowCount.ToString)
> ```
forsearch
MobilePopupMenu.SelectedRowIndex
**SelectedRowIndex** As `Integer`
> Used to get or set the selected item number. The first item is zero.
>
> SelectedRowIndex may be set using the Properties pane to set the default value of PopupMenu control. If you use the InitialValue property to populate the PopupMenu control and set a value of SelectedRowIndex that corresponds to a default item, that item will be displayed in the IDE.
>
> MobilePopupMenu requires a selection, so setting SelectedRowIndex to -1 does not clear the selection. If you need a way to indicate nothing has been selected, consider adding a row that says “No Selection” and check for that.
>
> The following example changes the selected item to the third item:
>
> ``` xojo
> FruitMenu.SelectedRowIndex = 2
> ```
forsearch
MobilePopupMenu.SelectedRowText
**SelectedRowText** As `String`
> The text of the currently selected row.
>
> This property is read-only.
>
> This example displays the text of the currently selected item in a `MobileTextField`.
>
> ``` xojo
> TextField1.Text = PopupMenu1.SelectedRowText
> ```
forsearch
MobilePopupMenu.Top
**Top** As `Integer`
> The top position of the control.
forsearch
MobilePopupMenu.Visible
**Visible** As `Boolean`
> Indicates whether the control is visible.
>
> Make the control invisible:
>
> ``` xojo
> PopupMenu1.Visible = False
> ```
forsearch
MobilePopupMenu.Width
**Width** As `Integer`
> The width of the control.
## Method descriptions
forsearch
MobilePopupMenu.AddAllRows
**AddAllRows**(items() As `String`)
> Appends the elements of the array to the items in the pop-up menu.
>
> The following example adds two items to the menu. It is equivalent to the example for `AddRow` that calls AddRow repeatedly.
>
> ``` xojo
> Me.AddAllRows("Banana", "Orange")
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
**AddAllRows**(`ParamArray` items As `String`)
> Adds all *items* passed to the pop-up menu.
forsearch
MobilePopupMenu.AddRow
**AddRow**(item As `String`)
> Appends *item* in a new row to the end of the list.
>
> The following example in the Opening event of the control adds two rows to the menu.
>
> ``` xojo
> Me.AddRow("Banana")
> Me.AddRow("Orange")
> ```
forsearch
MobilePopupMenu.AddRowAt
**AddRowAt**(rowNumber As `Integer`, item As `String`)
> Creates a new row at *index* (moving the existing rows down). The first row is numbered 0.
>
> The following example adds a row at the 4th position.
>
> ``` xojo
> PopupMenu1.AddRowAt(3, "Harry")
> ```
forsearch
MobilePopupMenu.ClearFocus
**ClearFocus**
> Removes the focus from the control.
>
> ``` xojo
> PopupMenu1.ClearFocus
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
MobilePopupMenu.Handle
**Handle** As `Ptr`
> The handle to the underlying native OS control.
forsearch
MobilePopupMenu.Refresh
**Refresh**
> Marks the control so that it will be redrawn during the next event loop.
>
> Call Refresh to force a PopupMenu to redraw itself:
>
> ``` xojo
> PopupMenu1.Refresh
> ```
forsearch
MobilePopupMenu.RemoveAllRows
**RemoveAllRows**
> Removes all rows in the list.
>
> The following example removes all the existing rows prior to adding new rows using `AddAllRows`.
>
> ``` xojo
> Var names() As String
> names.Add("Abbott")
> names.Add("Costello")
> names.Add("Frankenstein")
>
> Me.RemoveAllRows
> Me.AddAllRows(names)
> ```
forsearch
MobilePopupMenu.RemoveRowAt
**RemoveRowAt**(index As `Integer`)
> Removes the specified row. The first row is numbered zero.
>
> The following example removes the third item (index position 2) from the popup menu.
>
> ``` xojo
> Me.RemoveRowAt(2)
> ```
forsearch
MobilePopupMenu.RowTagAt
**RowTagAt**(index As `Integer`) As `Variant`
> A "hidden" identifier associated with the item identified by the *index* parameter.
>
> If you want to compare the value of row tag to another value, you should first convert the `Variant` to it actual data type.
>
> This example populates the RowTagAt identifier with a sequence number.
>
> ``` xojo
> Var nItems As Integer
> nItems = Me.RowCount - 1
> For i As Integer = 0 To nItems
> Me.RowTagAt(i) = i
> Next
> ```
>
> Since a row tag is a `Variant`, you must first convert it to an `Integer` if you want to compare it to another Integer. Do this with an assignment statement such as:
>
> ``` xojo
> Var recID As Integer
> recID = PopupMenu1.RowTagAt(1) ' ComboBox inherits from PopupMenu so it also inherits the RowTagAt method
> ```
>
> You can also use the `CType` function to do an explicit conversion to any other datatype. Then compare recID to another `Integer`: Displaying the row tag of the selected menu item:
>
> ``` xojo
> TextField1.Text = PopupMenu1.RowTagAt(PopupMenu1.SelectedRowIndex)
> ```
forsearch
MobilePopupMenu.RowTextAt
**RowTextAt**(index As `Integer`) As `String`
> Used to read the row text based on the *index* passed.
forsearch
MobilePopupMenu.SelectRowWithTag
**SelectRowWithTag**(value As `Variant`)
> Selects the first row whose tag matches the *value* passed.
>
> If *value* is not found, an `InvalidArgumentException` is raised.
forsearch
MobilePopupMenu.SelectRowWithText
**SelectRowWithText**(value As `String`)
> Selects the first row whose value matches the provided *value*.
>
> If *value* is not found, an `InvalidArgumentException` is raised.
forsearch
MobilePopupMenu.SetFocus
**SetFocus**
> Sets the focus to the control.
>
> ``` xojo
> PopupMenu1.SetFocus
> ```
## Event descriptions
forsearch
MobilePopupMenu.Closing
**Closing**
> The control is closing.
forsearch
MobilePopupMenu.Opening
**Opening**
> The control is about to be displayed. Use this event to initialize a control.
>
> The Opening event is called after the Constructor.
>
> Be warned that initializing control property values using the Constructor instead of the Opening event may result in those property values being overwritten by what is set in the Inspector. For best results, use the Opening event for control initialization rather than the control Constructor.
forsearch
MobilePopupMenu.SelectionChanged
**SelectionChanged**
> The selected item has changed.
>
> The *item* parameter is the newly selected item from the PopupMenu. Alternatively, use the `SelectedRowIndex` property to get the index of the newly selected value.
>
> The item is a copy of the menu item from the control therefore changing the item itself will have no impact on the original.
## Sample code
This code in the Opening event handler populates a popup menu and sets the initial value to the current month:
``` xojo
Var months() As String = Array("January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December")
For Each m As String In months
Me.AddRow(m)
Next
Var d As DateTime = DateTime.Now
Me.SelectedRowIndex = d.Month - 1 ' Select current month
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Examine the value of SelectedRowIndex in the SelectionChanged event handler to determine which item was selected.
This code adds an item to PopupMenu:
``` xojo
PopupMenu1.AddRow("October")
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This code populates the RowTag identifier with a sequence number:
``` xojo
For i As Integer = 0 To Me.LastRowIndex
Me.RowTag(i) = i
Next
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Since RowTagAt is a `Variant`, you must first convert it to an `Integer` if you want to compare it to another integer. Do this with a simple assignment statement such as:
``` xojo
Var recID As Integer
recID = PopupMenu1.RowTagAt(1)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Then compare recID to another `Integer`.
This code opens a screen called ListEditor when the "Edit List..." item is chosen.
``` xojo
Sub SelectionChanged()
If PopupMenu1.SelectedRowText = "Edit List..." Then
ListEditor.Show
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Changing the selected item in a PopupMenu:
``` xojo
PopupMenu1.SelectedRowIndex = 3 ' Selects the 4th row in the list (0-based)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Displaying the RowTag of the selected menu item:
``` xojo
TexField1.Text = PopupMenu1.RowTag(PopupMenu1.SelectedRowIndex)
```
## Compatibility
| | |
|-----------------------|---------|
| **Project Types** | Mobile |
| **Operating Systems** | Android |
`MobileUIControl` parent class