| Navigation: Language Reference > 13 - Built-in Functions >====== POPUP (return popup menu selection) ====== |    |
POPUP( selections [, x ] [, y ] [, position ] )
| POPUP | Returns an integer indicating the user's choice from the menu. |
| selections | A string constant, variable, or expression containing the text for the menu choices. |
| x | An integer constant, variable, or expression that specifies the horizontal position of the menu's top left corner. If omitted, the menu appears at the current cursor position. |
| y | An integer constant, variable, or expression that specifies the vertical position of the menu's top left corner. If omitted, the menu appears at the current cursor position. |
| position | A BYTE value that if set to 1 specifies that the popup coordinates (2nd and 3rd parameters) are treated as relative to the upper left corner of the active window's client area. If set to 0 (the default), they are screen coordinates. |
The POPUP procedure returns an integer indicating the user's choice from the popup menu that appears when the procedure is invoked. If the user clicks outside the menu or presses ESC (indicating no choice), POPUP returns zero.
Within the selections string, each choice in the popup menu must be delimited by a vertical bar (|) character. The following rules apply:
·A set of vertical bars containing only a hyphen (|-|) defines a separator between groups of menu choices.
·A menu choice immediately preceded by a tilde (~) is disabled (it appears dimmed out in the popup menu).
·A menu choice immediately preceded by a plus sign (+) appears with a check mark to its left in the popup menu.
·A menu choice immediately preceded by a minus sign (-) appears without a check mark to its left in the popup menu.
·A menu choice immediately followed by a set of choices contained within curly braces (|SubMenu{{SubChoice 1|SubChoice 2}|) defines a sub-menu within the popup menu (the two beginning curly braces are required by the compiler to differentiate your sub-menu from a string repeat count).
·You may use the ASCII tab character (<;9>) in your selection string to right-align text.
·You may specify an icon for the menu item by preceding the menu choice with square brackets enclosing PROP:Icon and the name of the icon file in parens, like this:
POPUP('[' & PROP:Icon & '(MyIco.ICO)]MenuChoice')
Popup menus use the default menu style available from SYSTEM{PROP:MenuStyle}. You can retrieve the instance of IMenuStyle and set/change its font.
By default, the used font is the system font - in priority order (higher to lower):
- font uses the handle that is the lfMenuFont value of the NONCLIENTMETRICS structure
- font uses the handle that is the result of the GetStockObject(DEFAULT_GUI_FONT) call
- font uses the handle that is the result of the GetStockObject(SYSTEM_FONT) call
By default, the charset value SYSTEM{PROP:CharSet} is not applied to the font of the default menu style.
Each menu selection is numbered in ascending sequence according to its position within the selections string, beginning with one (1). Separators and selections that call a sub-menu are not included in the numbering sequence (which makes an EXECUTE structure the most efficient code structure to use with this procedure). When the user CLICKS or presses ENTER on a choice, the procedure terminates, returning the position number of the selected menu item.
Return Data Type: SIGNED
Example:
PopupString = 'First|+Second|Sub menu{{One|Two}|-|Third|~Disabled|' & |
'[' & PROP:Icon & '(MyIco.ICO)]Last Menu Choice'
ToggleChecked = 1
ACCEPT
CASE EVENT()
OF EVENT:AlertKey
IF KEYCODE() = MouseRight
EXECUTE POPUP(PopupString)
FirstProc !Call proc for selection 1
BEGIN !Code to execute for toggle selection 2
IF ToggleChecked = 1 !Check toggle state
SecondProc(Off) !Call proc to turn off something
PopupString[7] = '-' !Reset string so the check mark does not appear
ToggleChecked = 0 !Set toggle flag
ELSE
SecondProc(On) !Call proc to turn off something
PopupString[7] = '+' !Reset string so the check mark does appear
ToggleChecked = 1 !Set toggle flag
END
END !End Code to execute for toggle selection 2
OneProc !Call proc for selection 3
TwoProc !Call proc for selection 4
ThirdProc !Call proc for selection 5
DisabledProc !Selection 6 is dimmed so it cannot run this proc
IconProc !Selection 7 displays an icon in the menu
END
END
END
END
!The example below demonstrates the use of an API to get popup positioning !coordinates, and alert the Mouse Menu key along with the Mouse Right key
PROGRAM
INCLUDE('keycodes.clw')
RECT GROUP,TYPE
Left SIGNED
Top SIGNED
Right SIGNED
Bottom SIGNED
END
MAP
MODULE('Win32Api')
GetWindowRect(UNSIGNED hWnd, *RECT lpRect),BOOL,PASCAL,RAW,PROC
END
END
W WINDOW('GetWindowRect'),AT(,,156,110),ALRT(93),ALRT(MouseRight),SYSTEM,GRAY
BUTTON('GetWindowRect'),AT(23,21,75,14),USE(?GetWindowRectButton)
END
rcCtrl LIKE(RECT)
hWndControl LONG,AUTO
CODE
OPEN(W)
hWndControl = ?GetWindowRectButton{PROP:Handle}
ACCEPT
IF FIELD() = ?GetWindowRectButton
IF EVENT() = EVENT:Accepted
!Get the rect of the button control in screen coordinates
GetWindowRect(hWndControl, rcCtrl)
X# = POPUP('1|2|3', rcCtrl.Left, rcCtrl.Bottom)
END
END
IF KeyCode()=93 !Hit right mouse menu key, position the Popup based on that
GetWindowRect(hWndControl, rcCtrl)
x# = POPUP('Moe|Larry|Curly', rcCtrl.Left, rcCtrl.Bottom)
ELSIF KeyCode()=MouseRight
x# = POPUP('Moe|Larry|Curly')
END
END
See Also: PROP:MenuStyle, PROP:Handle