Creates a pop-up menu.
r = PopUp(entries$, x, y, i)
PopUp entries$, x, y, i, (OUT) r
| entries$ | : string |
| r, x, y, i | : integer |
As opposed to Menu Bars, pop-up menus are not permanent, have one main column and can be deployed anywhere within a form - the best example of a pop-up menu is one that is produced when you use the right mouse button to click on a certain object to get further options.
Similar to Menu Bars, pop-up menus can be created either through a GB32 command - in this instance PopUp - or through calling Windows' internal APIs, which has the added advantages of allowing sub-menus to be created and custom ID numbers to be assigned to menu items; unlike Menu Bars, due to its brief existence and the structure of the PopUp command/function, a pop-up menu can not be created by using both methods.
Creating Pop-Up Menus using PopUp Show
PopUp can be used as either a function or a command as shown in the Syntax section above: in both instances, however, the parameters passed are identical and the selection made (or -1 if none was made) is returned in the r value. Note that, when using the command version, the r parameter must be a pre-defined variable, preferably an integer.
The menu items on a pop-up menu are defined in the entries$ parameter which is a string expression where each entry is separated by a vertical bar (the OR - "|" - symbol). Be careful not to leave spaces after this bar unless one is required.
As with Menu Bars, so called "hotkeys" can be used when the designated key is prefixed by an ampersand "&" or an underscore "_". To use the & and _ in the text of an entry, use the character twice (&& and __). A single entry can also be set as disabled (gray) by adding a - (minus) in front of the text of the entry, and/or checked by placing a + (plus) in front of the text. If both are used, first specify +, and then -. In addition, two separate text strings, one left- and the other right-justified, can be shown in the same menu entry by separating them with the Tab character (#9 or Chr(9)).
Unlike with items on Menu Bars, the PopUp command does not allow personalised ID numbers but automatically assigns to each entry its position number in entries$ minus one. Hence the first item will have an ID of 0, the second of 1, and so on.
Finally, a horizontal divide will be added if the menu item text is a minus sign ("-") by itself.
x and y specify the coordinates of the upper left corner of the popup menu relative to the upper left corner of the screen.
i is a flag with the following meaning:
The following example shows how to use both the command and function versions of PopUp to produce the same pop-up menu. To display the menu, right-click on one of the two labels.
OpenW 1, 100, 100, 300, 300, ~15
Ocx Label lbl(1) = "PopUp Command", 10, 10, 120, 20 : lbl(1).BorderStyle = 1 : lbl(1).Alignment = 2
Ocx Label lbl(2) = "PopUp Function", 10, 50, 120, 20 : lbl(2).BorderStyle = 1 : lbl(2).Alignment = 2
Do : Sleep : Until Win_1 Is Nothing
Sub lbl_MouseDown(Index%, Button&, Shift&, x!, y!)
Local a%
If Button& = 2 // Right Button clicked
Select Index%
Case 1 // Command
// Pop up menu appear with its bottom right corner at the mouse position (i = -3)
PopUp "O&pen...|+&New|-|-&Save|+-Save _As..|-|&End", 0, 0, -3, a%
Case 2 // Function
// Pop up menu appear with its top left corner at the mouse position
// In addition, selections can be made with the right mouse button (i = -17).
a% = PopUp("O&pen...|+&New|-|-&Save|+-Save _As..|-|&End", 0, 0, -17)
EndSelect
Print AT(1, 10); "Selection:"; a%; " "
If a% = 6 Then MsgBox "The window will now be closed." : CloseW 1
EndIf
EndSub
Creating Pop-Up Menus using APIs Show
While there are numerous APIs you could use to create a pop-up menu, this article will cover the four most important ones, which are:
The meanings of the parameters are:
The attributes defining content or type are:
In addition to these, the following affect the state of the menu entry.
The meanings of the parameters are:
The followings constants position the menu horizontally and/or vertically in relation to the values in x and y:
The following two flags control discovery of the user selection without having to set up a parent window for the menu:
These flags specify which mouse button activates the menu selection:
There are further constants dealing with menu animation, but these are beyond the scope of this article. For more information, see here.
The following simple example shows how to create a short pop-up menu with one sub-menu; note that it is also possible to give the menu items unique ID numbers using this method.
OpenW # 1, 100, 100, 300, 300, ~15
Ocx Label lbl(1) = "PopUp Thru' API", 10, 10, 120, 20 : lbl(1).BorderStyle = 1 : lbl(1).Alignment = 2
Do : Sleep : Until Win_1 Is Nothing
Sub lbl_MouseDown(Index%, Button&, Shift&, x!, y!)
If Button& = 2 // Right Button clicked
Dim mh% = CreatePopupMenu() // Pop-up Menu
Dim sm% = CreatePopupMenu() // Sub-menu
~AppendMenu(mh%, MF_STRING, 10, "O&pen")
~AppendMenu(mh%, MF_STRING | MF_CHECKED, 11, "&New")
~AppendMenu(mh%, MF_SEPARATOR, 12, "")
~AppendMenu(mh%, MF_POPUP, sm%, "&Save")
~AppendMenu(sm%, MF_STRING | MF_DISABLED, 20, "&Save"#9"Ctrl-S")
~AppendMenu(sm%, MF_STRING | MF_CHECKED | MF_DISABLED, 21, "Save _As..."#9"Ctrl-A")
~AppendMenu(mh%, MF_SEPARATOR, 13, "")
~AppendMenu(mh%, MF_STRING, 14, "&End")
Dim retval% = TrackPopupMenu(mh%, TPM_RETURNCMD, MouseSX, MouseSY, Null, Win_1.hWnd, Null)
Print AT(1, 10); "Selection:"; retval%; " "
~DestroyMenu(mh%) : ~DestroyMenu(sm%)
If retval% = 14 Then MsgBox "The window will now be closed." : CloseW 1
EndIf
End Sub
For a fuller example, see the example on Peter Heinzig's excellent site here; the file you are looking for is 'PopUp per API'.
{Created by Sjouke Hamstra; Last updated: 17/08/2020 by James Gaite}