Class
DesktopPopupMenu
Description
Displays a list of items when clicked. The user can select one item from the list. The DesktopComboBox control is similar except that the user also has the option of typing an item instead of choosing one from the list of items.
Properties
Name |
Type |
Read-Only |
Shared |
|---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Name |
Parameters |
Returns |
Shared |
|---|---|---|---|
FileType As String |
|||
Type As String |
|||
items() As String |
|||
item As String |
|||
item As DesktopMenuItem |
|||
row As Integer, DesktopMenuItem |
|||
x As Integer, y As Integer, width As Integer, height As Integer, immediately As Boolean = False |
|||
Index As Integer |
|||
index As Integer |
|||
index As Integer |
|||
targetValue As Variant |
|||
targetValue As String |
|||
Events
Name |
Parameters |
Returns |
|---|---|---|
Base As DesktopMenuItem, x As Integer, y As Integer |
||
HitItem As DesktopMenuItem |
||
obj As DragItem, Action As DragItem.Types |
||
obj As DragItem, Action As DragItem.Types |
||
x As Integer, y As Integer, obj As DragItem, Action As DragItem.Types |
||
Obj As DragItem Action As DragItem.Types |
||
Key As String |
||
Key As String |
||
X As Integer, Y As Integer, DeltaX As Integer, DeltaY As Integer |
||
item As DesktopMenuItem |
Property descriptions
DesktopPopupMenu.Active
Active As Boolean
Indicates whether the control is active.
This property is read-only.
Active is False when the control's window is not in the foreground. When a DesktopWindow is deactivated, its controls are automatically deactivated unless AllowAutoDeactivate is set to False.
DesktopPopupMenu.AllowAutoDeactivate
AllowAutoDeactivate As Boolean
Determines whether the control should be deactivated (on macOS) when the parent window is deactivated. The default is True.
DesktopPopupMenu.AllowTabStop
AllowTabStop As Boolean
If True, the control is in the Tab Order and accepts the focus when the user tabs into it. The default is True. If False, the user cannot tab into it to give it the focus. However, the control can gain the focus by other means, such as the user's clicking on it or by setting the focus in code.
This example removes the control from the Tab Order:
Me.AllowTabStop = False
DesktopPopupMenu.Bold
Bold As Boolean
If True, applies the bold style to the items in the popup menu.
This example sets the text to Bold.
Me.Bold = True
DesktopPopupMenu.Enabled
Enabled As Boolean
Determines if the control should be enabled when the owning window is opened.
A disabled control cannot be clicked and cannot receive the focus.
This example disables the control.
Me.Enabled = False
DesktopPopupMenu.FontName
FontName As String
Name of the font used to display the item in the menu.
You can enter any font that is installed on the computer or the names of the two metafonts, "System" and "SmallSystem".
The System font is the font used by the system software as its default font. Different operating systems use different default fonts. If the system software supports both a large and small System font, you can also specify the "SmallSystem" font as your TextFont.
On macOS, "SmallSystem" specifies the OS's smaller system font and may make the control smaller in size as well. On Windows and Linux, "SmallSystem" is the same as "System".
This code sets the FontName property.
Me.FontName = "Helvetica"
DesktopPopupMenu.FontSize
FontSize As Single
Point size of the font used to display the menu items.
If you enter zero as the FontSize, your app will use the font size that works best for the platform on which it is running.
This code sets the font size to 16 points.
Me.FontSize = 16
DesktopPopupMenu.FontUnit
FontUnit As FontUnits
The units in which FontSize is measured.
DesktopPopupMenu.Handle
Handle As Ptr
Returns a handle to the control.
This property is read-only.
For interfacing with Mac APIs using Declares, DesktopControl.Handle returns NSViews (except for DesktopToolbar).
On Windows returns the HWND of the control.
On Linux it returns a GtkWidget.
The following gets a handle to the control.
Var p As Ptr = Me.Handle
DesktopPopupMenu.Height
Height As Integer
The height (in points) of the control.
This example sets the height of the control to 100:
Me.Height = 100
DesktopPopupMenu.Index
Index As Integer
If the control is used in a control set, this specifies the control's index in the set.
This property is read-only.
DesktopPopupMenu.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.
DesktopPopupMenu.Italic
Italic As Boolean
If True, applies the italic style to the items in the popup menu.
The following sets the Italic property for the control.
Me.Italic = True
DesktopPopupMenu.LastAddedRowIndex
LastAddedRowIndex As Integer
The number of the last row added with the AddRow, AddAllRows or AddRowAt method. If no rows have been added, LastAddedRowIndex will be -1.
This property is read-only.
This example displays the value of the last row added to the popup menu:
Var r As Integer = PopupMenu1.LastAddedRowIndex
System.Beep
MessageBox("The last value added was: " + PopupMenu1.RowTextAt(r))
DesktopPopupMenu.LastRowIndex
LastRowIndex As Integer
The number of the last row of the DesktopPopupMenu. Because, like nearly all of the Xojo framework, the DesktopPopupMenu is zero-based, this value will be 1 less than the RowCount.
This property is read-only.
DesktopPopupMenu.Left
Left As Integer
The distance from the left side of the control to the left side of its containing window or container.
The following example moves the control 100 points from the left side of the window:
Me.Left = 150
DesktopPopupMenu.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 window.
This property can be set in the control's Inspector. The following example sets it in code.
Me.LockBottom = True
DesktopPopupMenu.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 window.
LockLeft and Locktop default to True when you add a new control to a window. 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.
Me.LockLeft = True
DesktopPopupMenu.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 window.
This property can be set in the control's Inspector. The following example sets it in code.
Me.LockRight = True
DesktopPopupMenu.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 window.
LockTop and LockLeft default to True when you add a control to a window. 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.
Me.LockTop = True
DesktopPopupMenu.MouseCursor
MouseCursor As MouseCursor
The cursor to be displayed while the mouse is within the control and both the DesktopApplication and DesktopWindow class's MouseCursor properties are Nil.
If the DesktopApplication class's MouseCursor property is not Nil or the DesktopWindow's MouseCursor property is not Nil, then any control's MouseCursor property is ignored. You can use a cursor stored in the Cursors module. On Macintosh, you can also obtain a MouseCursor from a resource file.
This line in the Opening event of the control sets the default cursor to the finger pointer.
Me.MouseCursor = System.Cursors.FingerPointer
DesktopPopupMenu.Name
Name As String
The name of the control. Set the name of the control in the Inspector.
This property is read-only.
DesktopPopupMenu.PanelIndex
PanelIndex As Integer
If the control has been placed on a DesktopTabPanel or DesktopPagePanel control, this is the panel (page/tab) that the control is on. If the control is not on a panel, it returns -1.
The first panel is numbered zero. If the control has been placed on a panel of a DesktopTabPanel or DesktopPagePanel control, it returns the panel number. If the control is not on a DesktopPagePanel or DesktopTabPanel, it returns -1. If you change the PanelIndex to a nonexistent panel, the control will disappear until you give it a PanelIndex value that corresponds to a panel that exists.
If you are looking to change the currently selected panel (page/tab), use DesktopPagePanel.SelectedPanelIndex.
This code displays the panel index of the control that is on the page.
MessageBox(Me.SelectedPanelIndex.ToString)
DesktopPopupMenu.Parent
Parent As Object
Used to get and set the control's parent control or window.
If the control is on the window, the Parent will be the Window. If the control is on the container, the Parent will be the container. If the control is completed enclosed by another control, the Parent will be that control.
If you do not want the enclosing control to be the parent, set the Parent property of that control to Nil to make it the Window.
If the parent control is somehow in another window, an InvalidParentException will occur.
The following example sets the parent of the control to the window.
Me.Parent = Nil
DesktopPopupMenu.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.
MessageBox(FruitPopup.RowCount.ToString)
DesktopPopupMenu.Scope
Scope As Integer
Used to determine whether access to the control is Public (0) or Private (2). The default is Public.
This property is read-only.
Note
This is a designtime-only property and thus can only be set in the Inspector and is not accessible via code.
If the Scope of a control is set to Private, it cannot be accessed from outside its parent window.
DesktopPopupMenu.SelectedRowIndex
SelectedRowIndex As Integer
Used to get or set the selected item number. The first item is zero.
A value of -1 means no selection. 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.
The following example changes the selected item to the third item:
FruitMenu.SelectedRowIndex = 2
DesktopPopupMenu.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 DesktopTextField.
TextField1.Text = PopupMenu1.SelectedRowText
DesktopPopupMenu.TabIndex
TabIndex As Integer
The control's position in the Tab Order. The control with whose TabIndex is 0 will get the focus first.
On macOS, only controls where you enter data from the keyboard typically get the focus. In order to manually set focus to controls that don't allow keyboard entry, go to System Preferences, click on the Keyboard icon then on the Shortcuts tab and then check the Use keyboard navigation to move focus between controls checkbox.
This example sets the control's TabIndex.
Me.TabIndex = 2
DesktopPopupMenu.Tooltip
Tooltip As String
Text of help message displayed as a Windows or Linux "tooltip" or macOS help tag.
The tip/tag is displayed when the user hovers the mouse cursor over the control.
This example adds a tooltip to a control:
Me.Tooltip = "Click to bark."
DesktopPopupMenu.Top
Top As Integer
The distance from the top of the control to the top of its containing window or container.
This example sets the top of the control to 140 points from the top of the window:
Me.Top = 140
DesktopPopupMenu.Transparent
Transparent As Boolean
Determines whether the control is transparent on Windows. The default is False. Has no effect on macOS or Linux.
Transparent controls draw more slowly and use more memory in order to cache the background. Unless you absolutely require transparency, leave this set to False.
For projects that were created prior to 2018r1, this property defaults to True to emulate previous behavior. Consider changing it to False to improve performance if you do not require transparency.
DesktopPopupMenu.Underline
Underline As Boolean
If True, applies the underline style to the items in the popup menu.
macOS does not support underline for popup menus.
This code underlines the popup menu's items.
Me.Underline = True
DesktopPopupMenu.Visible
Visible As Boolean
Determines whether the control is visible when its owning window is opened. The default is True: the control is visible.
The following code makes the control invisible:
Me.Visible = False
DesktopPopupMenu.Width
Width As Integer
The width (in points) of the control.
The following example resizes the control:
Me.Width = 200
DesktopPopupMenu.Window
Window As DesktopWindow
The control's parent window.
This property is read-only.
This code gets the parent window's Title property.
MessageBox(Me.Window.Title)
Method descriptions
DesktopPopupMenu.AcceptFileDrop
AcceptFileDrop(FileType As String)
Permits documents of type FileType to be dropped on the control. FileType must be a file type that you defined in via the FileType class or the File Type Sets Editor.
This code in the Opening event makes it possible for the user to drop either a picture or a file that is a jpeg image. The File Type Sets editor was used to define the “image/jpeg” file type. It is one of the “Common File Types” that is available in the editor.
Me.AcceptPictureDrop
Me.AcceptFileDrop("image/jpeg")
To restrict file drops to just folders (and not files), you can put this code in the DragEnter event:
If Not obj.FolderItem.IsFolder Then Return True
DesktopPopupMenu.AcceptPictureDrop
AcceptPictureDrop
Permits pictures to be dropped on the control.
If a control should accept pictures in a drag and drop, then AcceptPictureDrop needs to be called prior to the drop. Typically, it is in the Opening event of the control itself. For example, the line:
Me.AcceptPictureDrop
in the Opening event of the control that will receive the dragged pictures is needed. When the picture is dropped, the DropObject event is called and this is where you will put your code to handle the drop.
Opening Event:
Me.AcceptPictureDrop
DropObject Event:
If obj.PictureAvailable Then
Me.Backdrop = obj.Picture
End If
DesktopPopupMenu.AcceptRawDataDrop
AcceptRawDataDrop(Type As String)
Permits data (of the Type specified) to be dropped on the control.
The following specfies a generic file type defined in the File Type Sets editor.
Me.AcceptRawDataDrop("????")
DesktopPopupMenu.AcceptTextDrop
AcceptTextDrop
Permits text to be dropped on the control.
This line in the Opening event of a control that can accept dragged text.
Me.AcceptTextDrop
DesktopPopupMenu.AddAllRows
AddAllRows(Items() As String)
Appends the elements of the array to the items in the pop-up menu.
You can add a "-" on macOS (instead of calling AddSeparator) to add a separator. Windows and Linux do not support separators within PopupMenus, so this adds a row with the text "-" that can be selectable by the user.
The following example adds two items to the menu. It is equivalent to the example for AddRow that calls AddRow repeatedly.
Me.AddAllRows("Banana", "Orange")
DesktopPopupMenu.AddRow
AddRow(Item As String)
Appends Item in a new row to the end of the list.
You can add a "-" on macOS (instead of calling AddSeparator) to add a separator. Windows and Linux do not support separators within PopupMenus, so this adds a row with the text "-" that can be selectable by the user.
The following example in the Opening event of the control adds two rows to the menu.
Me.AddRow("Banana")
Me.AddRow("Orange")
DesktopPopupMenu.AddRow
AddRow(item As DesktopMenuItem)
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.
Me.AddRow(New DesktopMenuItem("Banana"))
Me.AddRow(New DesktopMenuItem("Orange"))
DesktopPopupMenu.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.
PopupMenu1.AddRowAt(3, "Harry")
DesktopPopupMenu.AddRowAt
AddRowAt(row As Integer, item As DesktopMenuItem)
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.
PopupMenu1.AddRowAt(3, New DesktopMenuItem("Harry"))
DesktopPopupMenu.AddSeparator
AddSeparator
Adds a separator line to the popup menu.
Windows and Linux do not support separators within PopupMenus, so this adds a row with the text "-" that can be selected by the user.
The following example adds a separator between some values:
Me.AddRow("Banana")
Me.AddRow("Orange")
#If TargetMacOS Then
Me.AddSeparator
#Endif
Me.AddRow("Tomato")
DesktopPopupMenu.Close
Close
Closes a control.
Closing a control permanently removes the control from memory, making it impossible to access. You can close both non-indexed controls and indexed controls. When you close an indexed control, the indexes for the remaining controls will shift downward so that the indexes start with zero and are consecutive.
The following code closes the control. When this is executed from a visible control, the control disappears from the window.
Me.Close
DesktopPopupMenu.DrawInto
DrawInto(g As Graphics, x As Integer, y As Integer)
Draws the contents of the control into the specified Graphics context. The parameters x and y are the coordinates of the top, left corner.
Note
DrawInto will only work if the control is on a window or container.
This example draws the current control into the Graphics of a Picture and then displays it as the Backdrop of a Canvas:
Var p As New Picture(Me.Width, Me.Height)
Me.DrawInto(p.Graphics, 0, 0)
Canvas1.Backdrop = p
DesktopPopupMenu.Refresh
Refresh(immediately As Boolean = False)
Redraws the portion specified of the contents of the control the next time the OS redraws the control or immediately if True is passed.
If you are calling this so frequently that you experience a slowdown in your code, pass True for the immediately parameter.
Calling this method causes the Render event to fire.
Refresh the entire area immediately:
Me.Refresh(True)
DesktopPopupMenu.Refresh
Refresh(x As Integer, y As Integer, width As Integer, height As Integer, immediately As Boolean = False)
Redraws the portion specified of the contents of the control the next time the OS redraws the control or immediately if True is passed.
Refresh a portion of the area the next time the OS redraws the control:
Me.Refresh(100, 150, 200, 300)
DesktopPopupMenu.RemoveAllRows
RemoveAllRows
Removes all rows in the list.
The following example removes all the existing rows prior to adding new rows using AddAllRows.
Var names() As String
names.Add("Abbott")
names.Add("Costello")
names.Add("Frankenstein")
Me.RemoveAllRows
Me.AddAllRows(names)
DesktopPopupMenu.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.
Me.RemoveRowAt(2)
DesktopPopupMenu.RowTagAt
RowTagAt(index As Integer) As Variant
A "hidden" identifier associated with the item identified by the row 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.
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:
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:
TextField1.Text = PopupMenu1.RowTagAt(PopupMenu1.SelectedRowIndex)
DesktopPopupMenu.RowTextAt
RowTextAt(index As Integer) As String
Used to read the row text based on the index passed.
DesktopPopupMenu.SelectRowWithTag
SelectRowWithTag(targetValue As Variant)
Selects the first row whose tag matches the targetValue passed.
If value is not found, an InvalidArgumentException is raised.
DesktopPopupMenu.SelectRowWithText
SelectRowWithText(targetValue As String)
Selects the first row whose value matches the provided targetValue.
If value is not found, an InvalidArgumentException is raised.
DesktopPopupMenu.SetFocus
SetFocus
If applicable, sets the focus to the DesktopUIControl. KeyDown events are directed to the control.
If the control cannot get the focus on the platform on which the application is running, SetFocus does nothing. The SetFocus method of the DesktopWindow class or the ClearFocus method can be used to remove the focus from the control that currently has the focus, leaving no control with the focus.
Note
On the Mac you need Full Keyboard Access turned on in System Preferences (Keyboard->Shortcuts) in order to manually set focus to non-text controls.
The following example in the Opening event sets the focus to the that control. If another control has the focus when this line is executed, then the user sees this control gets the focus.
Me.SetFocus
Event descriptions
DesktopPopupMenu.Closing
Closing
The control is closing.
DesktopPopupMenu.ConstructContextualMenu
ConstructContextualMenu(Base As DesktopMenuItem, x As Integer, y As Integer) As Boolean
This event is called when it is appropriate to display a contextual menu for the control.
This event handler is the recommended way to handle contextual menus because this event figures out whether the user has requested the contextual menu, regardless of how they did it. Depending on platform, it might be in the MouseUp or MouseDown event and it might be a right+click or by pressing the contextual menu key on the keyboard, for example.
Base is analogous to the menu bar for the contextual menu. Any items you add to Base will be shown as menu items. If you return False, the event is passed up the parent hierarchy.
If you return True, the contextual menu is displayed. The parameters x and y are the mouse locations. If the event was fired because of a non-mouse event, then x and y are both set to -1. See the example of a contextual menu in the following section.
The following ConstructContextualMenu event handler builds a menu with three menu items plus a submenu with three additional menu items.
' Add some items
base.AddMenu(New DesktopMenuItem("Test 1"))
base.AddMenu(New DesktopMenuItem("Test 2"))
base.AddMenu(New DesktopMenuItem("Test 3"))
' Add a Separator
base.AddMenu(New DesktopMenuItem(DesktopMenuItem.TextSeparator))
' Add a sub menu
Var submenu As New DesktopMenuItem("SubMenu")
submenu.AddMenu(New DesktopMenuItem("SubMenu Test 1"))
submenu.AddMenu(New DesktopMenuItem("SubMenu Test 2"))
submenu.AddMenu(New DesktopMenuItem("SubMenu Test 3"))
base.AddMenu(submenu)
' Add a Separator
base.AddMenu(New DesktopMenuItem(DesktopMenuItem.TextSeparator))
Return True
DesktopPopupMenu.ContextualMenuItemSelected
ContextualMenuItemSelected(HitItem As DesktopMenuItem) As Boolean
Fires when a contextual menuitem selectedItem was selected but the MenuItemSelected event and the MenuHandler for the DesktopMenuItem did not handle the menu selection.
This event gives you a chance to handle the menu selection by inspecting the menuitem's Text or Tag properties to see which item was selected. Use this in conjunction with ConstructContextualMenu if you have not specified the MenuItemSelected event or the Menu Handler for the items on the contextual menu. See the example of a contextual menu in the examples for the DesktopUIControl class.
Return True if this event has handled the item the user chose from the contextual menu. Returning False will cause the control's parent to execute its ContextualMenuAction event. This can be handy if you have the same contextual menu for several controls who share the same Parent (several on the same window for example). By returning False you can handle them all in a single event.
This simple event handler displays the value of the selected menu item.
If selectedItem <> Nil Then MessageBox(selectedItem.Text)
Return True
DesktopPopupMenu.DragEnter
DragEnter(obj As DragItem, Action As DragItem.Types) As Boolean
Fires when the passed DragItem enters the DesktopUIControl.
Returns a Boolean. Return True from this event to prevent the drop from occurring.
The Action parameter specifies the type of drag action.
To restrict file drops to just folders (and not files), you can put this code in the DragEnter event:
If Not obj.FolderItem.IsFolder Then Return True
DesktopPopupMenu.DragExit
DragExit(obj As DragItem, Action As DragItem.Types)
Fires when the passed DragItem exits the DesktopUIControl.
The Obj parameter is the item being dragged. The Action parameter specifies the type of drag action.
DesktopPopupMenu.DragOver
DragOver(x As Integer, y As Integer, obj As DragItem, Action As DragItem.Types) As Boolean
Fires when the DragItem is over the DesktopUIControl.
The Obj parameter is the object being dragged. The coordinates x and y are relative to the DesktopUIControl. Returns a Boolean. Return True from this event to prevent the drop from occurring.
The Action parameter specifies the type of drag action, which is typically done by holding down a modifier key (Shift, Alt, Option, Command, etc.) while doing the drag.
DesktopPopupMenu.DropObject
DropObject(Obj As DragItem Action As DragItem.Types)
The item represented by Obj has been dropped on the control.
The Obj parameter is the object being dragged. The Action parameter specifies the type of drag action.
The following DropObject event handler can handle either a dropped picture or a dropped file. The type of file that it can handle needs to have been specified in a call to AcceptFileDrop prior to the drop, for example, in the Opening event.
If Obj.PictureAvailable Then
Me.Image = obj.Picture
ElseIf Obj.FolderItemAvailable Then
Me.Image = Picture.Open(obj.FolderItem)
End If
DesktopPopupMenu.FocusLost
FocusLost
The control has lost the focus.
Note
On macOS, controls other than text fields and lists will accept and lose focus only if the full keyboard access option is enabled in System Preferences/Keyboard.
DesktopPopupMenu.FocusReceived
FocusReceived
The control has received the focus and has a selection rectangle around it.
Note
On macOS, controls other than text fields and lists will accept focus only if the full keyboard access option is enabled in System Preferences/Keyboard.
DesktopPopupMenu.KeyDown
KeyDown(Key As String) As Boolean
The user has pressed the Key passed while the control has the focus.
Returning True prevents the KeyDown event on the parent control (usually the window) from executing. Returning False results in the execution of the KeyDown event of the parent control.
DesktopPopupMenu.KeyUp
KeyUp(Key As String)
Fires when the passed Key is released in the control that has the focus.
It is not guaranteed to be the same key that received the KeyDown event.
DesktopPopupMenu.MouseDown
MouseDown(X As Integer, Y As Integer) As Boolean
The mouse button was pressed inside the control's region at the location passed in to x, y.
This event fires repeatedly while the mouse button is being held down.
The coordinates x and y are local to the control, i.e. they represent the position of the mouse click relative to the upper-left corner or the control.
Return True if you are going to handle the MouseDown. In such a case:
The Pressed event, if any, will not execute and the state of the object will not change.
You will receive the MouseUp event.
If you return False, the system handles the MouseDown so the MouseUp event handler do not get called.
The MouseDown event uses the DragItem constructor when the user drags the contents of the control. It is:
Var d As DragItem
d = New DragItem(Self, Me.Left, Me.Top, Me.Width, Me.Height)
d.Picture = Me.Image
d.Drag ' Allow the drag
DesktopPopupMenu.MouseDrag
MouseDrag(X As Integer, Y As Integer)
The mouse button was pressed inside the control and moved (dragged) at the location local to the control passed in to x, y.
This event fires repeatedly while the mouse button is down regardless of whether or not the mouse coordinates are changing.
This event will not occur unless you return True in the MouseDown event.
DesktopPopupMenu.MouseEnter
MouseEnter
The mouse has entered the area of the control.
DesktopPopupMenu.MouseExit
MouseExit
The mouse has left the area of the control.
DesktopPopupMenu.MouseMove
MouseMove(X As Integer, Y As Integer)
The mouse has moved within the control to the coordinates passed. The coordinates are local to the control, not to the window.
DesktopPopupMenu.MouseUp
MouseUp(X As Integer, Y As Integer)
The mouse button was released. Use the x and y parameters to determine if the mouse button was released within the control's boundaries.
Note
This event will not occur unless you return True in the MouseDown event. The return value is ignored.
The parameters x and y are local coordinates, i.e. they represent the position of the mouse click relative to the upper-left corner or the control. Mouse clicks that are released to the left or above a control are negative.
DesktopPopupMenu.MouseWheel
MouseWheel(X As Integer, Y As Integer, DeltaX As Integer, DeltaY As Integer) As Boolean
The mouse wheel has been moved.
The parameters X and Y are the mouse coordinates relative to the control that has received the event. The parameters DeltaX and DeltaY hold the number of scroll lines the wheel has been moved horizontally and vertically, as defined by the operating system. DeltaX is positive when the user scrolls right and negative when scrolling to the left. DeltaY is positive when the user scrolls down and negative when scrolling up.
Returns a Boolean. Return True to prevent the event from propagating further.
DesktopPopupMenu.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.
If the control is supposed to handle drag and drop, you need to tell it which type of item it needs to be able to handle. The following example informs the control that pictures and files can be dropped on it. The type of the file it needs to support is specified via the File Types Editor.
Sub Opening()
Me.AcceptPictureDrop
Me.AcceptFileDrop("JPEG")
End Sub
DesktopPopupMenu.SelectionChanged
SelectionChanged(item As DesktopMenuItem)
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.
Notes
Use the constant NoSelection (-1) to indicate that no rows are selected.
Note
Changing the Height property has no effect for apps run on macOS. As a native control, macOS always draws the PopupMenu at its system-standard height.
Warning
The MouseDown and MouseUp event handlers are never called on Linux due to a limitation of the underlying GtkComboBox that is used.
Warning
ContextualMenus do not work with PopupMenu on macOS due to a limitation of the underlying macOS control that is used.
Note
When using the & character in the text of a row, you must double it (&&) for it to appear as this character is used to designate accelerator keys on Windows.
Sample code
This code in the Opening event handler populates a popup menu and sets the initial value to the current month:
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:
PopupMenu1.AddRow("October")
This code populates the RowTag identifier with a sequence number:
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:
Var recID As Integer
recID = PopupMenu1.RowTagAt(1)
Then compare recID to another Integer.
This code opens a new window when an item is chosen.
Sub SelectionChanged(item As String)
Var w As ListEditorWindow
If PopupMenu1.SelectedRowValue = "Edit List..." Then
w = New ListEditorWindow
End If
Changing the selected item in a PopupMenu:
PopupMenu1.SelectedRowIndex = 3 ' Selects the 4th row in the list (0-based)
Displaying the RowTag of the selected menu item:
TexField1.Text = PopupMenu1.RowTag(PopupMenu1.SelectedRowIndex)
Interfaces
This class implements the DataNotifier class interface.
Compatibility
Desktop projects on all supported operating systems.
See also
DesktopUIControl parent class; DesktopComboBox, DesktopTextField controls; DesktopUIControl class.