| **Navigation:**  [[introduction.htm|Language Reference]] > 13 - Built-in Functions >====== POPUP (return popup menu selection) ====== | [[popastrings.htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[post  post user defined event .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

{{newc7.jpg|NewC7.jpg}}

**POPUP( **//selections //[,// x //] [,// y //] [,// position //]**// //****)**

{{blk2blue.jpg|blk2blue.jpg}}

| **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('[' &amp; PROP:Icon &amp; '(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|' &amp; |**

**              '[' &amp; PROP:Icon &amp; '(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.htm|PROP:MenuStyle]], [[prop handle.htm|PROP:Handle]]