|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
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:
Coordinate_1 and coordinate_2 are pixels. (default)
Coordinate_1 and coordinate_2 are the ordinal row and column.
Horizontal alignment:
Align the left side of the pop-up menu with the coordinates specified or with a default location. (default)
Center the pop-up menu horizontally over the coordinates specified or the default location.
Align the right side of the pop-up menu with the coordinates specified or the default location.
Vertical alignment:
Align the top of the pop-up menu with the coordinates specified or with a default location. (default)
Center the pop-up menu vertically over the coordinates specified or with a default location.
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)
The application window (excluding the border and caption).
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.
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)
