%M_POPUP

Process a pop‑up menu

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
status = %M_POPUP(col_id, [coordinate_flags], [coordinate_1, coordinate_2], [window_id]
&      [, input_string])

or

xcall M_POPUP(col_id, [coordinate_flags], [coordinate_1, coordinate_2], [window_id]
&     [, input_string])

Return value

status

True if a pop‑up menu entry was selected, otherwise false. (^VAL)

Arguments

col_id

The ID of the menu column to pop up. (n)

coordinate_flags

(optional) One or more of the following, which can be combined using .BOR. or the vertical bar (|) operator: (n)

Coordinate units:

D_POPUP_PIXEL

Coordinate_1 and coordinate_2 are pixels. (default)

D_POPUP_ROWCOL

Coordinate_1 and coordinate_2 are the ordinal row and column.

Horizontal alignment:

D_POPUP_LEFT

Align the left side of the pop‑up menu with the coordinates specified or with a default location. (default)

D_POPUP_HCENTER

Center the pop‑up menu horizontally over the coordinates specified or the default location.

D_POPUP_RIGHT

Align the right side of the pop‑up menu with the coordinates specified or the default location.

Vertical alignment:

D_POPUP_TOP

Align the top of the pop‑up menu with the coordinates specified or with a default location. (default)

D_POPUP_VCENTER

Center the pop‑up menu vertically over the coordinates specified or with a default location.

D_POPUP_BOTTOM

Align the bottom of the pop‑up menu with the coordinates specified or with a default location.

coordinate_1

(optional) The coordinate that determines the row or X position of the pop‑up menu. If the D_POPUP_PIXEL flag is specified, the value of this argument is interpreted in pixels. Otherwise, the value is interpreted to be the row number. (n)

coordinate_2

(optional) The coordinate that determines the column of Y position of the pop‑up menu. If the D_POPUP_PIXEL flag is specified, the value of this argument is interpreted in pixels. Otherwise, the value is interpreted to be the column number. (n)

window_id

(optional) The window ID used in the positioning of the pop‑up menu, or one of the following: (n)

WID_APP

The application window (excluding the border and caption).

WID_CONTAINER

The container window for the Synergy application (including the border and caption).

input_string

(optional) The “path” to follow to get to a specific pop‑up menu entry. (a)

Discussion

%M_POPUP enables applications to display and process pop‑up menus. The menu column you specify with col_id does not need to be loaded or placed.

The optional set of bit flags used by the coordinate_flags argument is grouped into three categories: coordinate units, and horizontal and vertical alignment. The bit values within each of these categories are mutually exclusive. If no bit flag is set or more than one bit flag is set in a category, then the default bit flag for that category is presumed.

If D_POPUP_PIXEL is specified, the coordinate_1 argument is the horizontal (X) coordinate, and the coordinate_2 argument is the vertical (Y) coordinate. If window_id is not passed, the pixel coordinates are used to determine the location of the top left corner of the pop‑up menu. On Windows platforms, if both the pixel coordinates are not passed, the current position of the mouse pointer is used to determine the position of the pop‑up menu. On UNIX and OpenVMS platforms, if the pixel coordinates are not passed, the center of the screen is used to determine the position of the pop‑up menu.

If D_POPUP_ROWCOL is specified, the coordinate_1 argument is the vertical (row) coordinate, and the coordinate_2 argument is the horizontal (column) coordinate. If window_id is not passed, the row and column coordinates are used to determine the location of the top, left corner of the pop‑up menu. If both row and column coordinates are not passed, the pop‑up menu is positioned in the center of the screen. When the row and column coordinate system is used on a Windows platform, the actual pixel position used for the pop‑up menu is the center of the specified character cell.

If window_id is specified, the coordinates passed are interpreted to be relative to window_id. If window_id is not passed, the screen is the presumed value. If window_id refers to a Synergy window that is not placed, a fatal error occurs.

The format of input_string is identical to the input_string optional parameter used by M_PROCESS. See M_PROCESS for more information on the input_string argument. For cross‑platform compatibility, an initial “<D>” in the string will always highlight the first item in the pop‑up menu.

The pop‑up menu is able to extend beyond the boundaries of the application window; however, it is limited to the boundaries of the screen.

On Windows, shortcuts are not available, and %M_POPUP recognizes the following reserved menu entries (which are documented in Appendix B: Reserved Menu Entries).

E_CLEAR

E_COPY

E_CUT

E_MARK

E_PASTE

On UNIX and OpenVMS, shortcuts are available while the pop‑up menu is displayed.

If a menu entry (other than one of those listed above for Windows) is selected from the pop‑up menu, g_select will be true and g_entnam will be the name of the menu entry selected. A menu entry can be selected by pressing enter when the entry is highlighted; pressing the entry’s quick‑select character (if unique); on Windows platforms, clicking the left or right mouse buttons; or on UNIX and OpenVMS platforms, pressing the entry’s shortcut.

If the user cancels the pop‑up menu, g_select will be false. On Windows platforms, the pop‑up menu can be canceled by clicking the mouse outside the pop‑up menu or by pressing esc or alt. On UNIX and OpenVMS platforms, pressing the key mapped to the drop‑down menu function (usually ctrl+p) will cancel the pop‑up menu.

If %M_POPUP is used in a direct callback function (such as a right‑click method for a window) and the user wants to return the menu entry out of that function, M_SIGNAL should be used to resignal the menu entry so that the current input loop will be interrupted. For example:

if (%m_popup(colid))
  xcall m_signal(g_entnam)

You can disable or enable an entry in a pop‑up menu by using the D_SUB qualifier for M_DISABLE or M_ENABLE. See M_DISABLE and M_ENABLE for information.

Examples

The following example pops up a menu centered over the application space.

xcall m_popup(colid, D_POPUP_ROWCOL .bor. D_POPUP_HCENTER .bor. 
&             D_POPUP_VCENTER,,, WID_APP)

The following example pops up a menu outside (just to the right of) a Synergy window, centered vertically relative to the window’s center.

xcall m_popup(colid, D_POPUP_ROWCOL .bor. D_POPUP_VCENTER,,
&             %w_info(WIF_DCOLSIZ, wndid) + 2, wndid)