WinPopupMenu

This function causes a pop-up menu to be presented.

Syntax

WinPopupMenu(hwndParent, hwndOwner, hwndMenu, x, y, idItem, fs)

Parameters

hwndParent (HWND) - input

Parent-window handle.

hwndOwner (HWND) - input

Owner-window handle.

The owner window receives all the notification messages generated by the pop-up menu.

hwndMenu (HWND) - input

Pop-up menu-window handle.

The pop-up menu must have been created, by use of either the WinCreateMenu or WinLoadMenu functions.

x (LONG) - input

x-coordinate of the pop-up menu position.

The value is in window coordinates relative to the origin of the parent window.

The x-coordinate of the origin of the pop-up menu can be affected, if either of the PU_POSITIONONITEM or PU_HCONSTRAIN values of the fs parameter is also set.

y (LONG) - input

y-coordinate of the pop-up menu position.

The value is in window coordinates relative to the origin of the parent window.

The y-coordinate of the origin of the pop-up menu can be affected, if either of the PU_POSITIONONITEM or PU_VCONSTRAIN values of the fs parameter is also set.

idItem (LONG) - input

Item identity.

This is used if either the PU_POSITIONONITEM or PU_SELECTITEM of the fs parameter is also set. It must be greater or equal to 0 and less or equal to 0xFFFF.

fs (ULONG) - input

Options.

Position

Pop-up menu position.

PU_POSITIONONITEM

Position the pop-up menu so that the item identified by the idItem parameter of the top-level menu specified by the hwndMenu parameter lies directly under the x \ y coordinates.

The position of the pop-up menu can be affected, if either the PU_HCONSTRAIN or or PU_VCONSTRAIN values of the fs parameter is also set.

This value also causes the pop-up menu item identified by the idItem to be selected.

Restrain

Pop-up menu position constraints.

These options allow the application to ensure that the pop-up menu is visible on the desktop.

PU_HCONSTRAIN

Constrain the pop-up menu so that its width is wholly visible on the desktop.

If necessary the position of the pop-up menu will be adjusted so that its left edge is coincident with the left edge of the desktop or that its right edge is coincident with the right edge of the desktop.

PU_VCONSTRAIN

Constrain the pop-up menu so that its height is wholly visible on the desktop.

If necessary the position of the pop-up menu will be adjusted so that its top edge is coincident with the top edge of the desktop or that its bottom edge is coincident with the bottom edge of the desktop.

InitialState

Initial input state of the pop-up menu.

This allows the user interaction which caused the application to summon the pop-up menu to be carried through as the initial user interaction with the pop-up menu.

For example, this permits the application to support the user interface in which mouse button 1 can be depressed to cause the pop-up menu to be presented and held down while moving the mouse over the menu in order to select another menu item and then released to dismiss the menu.

Only one of the following values can be selected:

PU_MOUSEBUTTON1DOWN

The pop-up menu is initialized with mouse button 1 depressed. PU_MOUSEBUTTON2DOWN

The pop-up menu is initialized with mouse button 2 depressed. PU_MOUSEBUTTON3DOWN

The pop-up menu is initialized with mouse button 3 depressed. PU_NONE

The pop-up menu is to be presented uninfluenced by the user interaction which caused it to be summoned.

This is the default value.

Select

Item selection.

PU_SELECTITEM

The item identified by idItem is to be selected. This is only valid if PU_NONE is set in the InitialState parameter.

If the identified item is in a submenu of the pop-up menu, then all the previous submenus in the menu hierarchy are presented with the correct path to the identified item.

Usage Input device usage.

The window procedure controlling the pop-up menu must be informed of which input devices are available for interaction with the pop-up menu.

These options are independent to those of the InitialState parameter. Therefore, if an application indicates in the InitialState parameter that the pop-up menu is to be initialized with a particular user interaction, then the mechanism which permits that user interaction would usually be specified in this parameter. In this way the user's expectation, that once a device has been employed for the manipulation of the pop-up menu then that device can continue to be used for that purpose, is fulfilled.

It is valid to specify a user interaction as an initialization of the pop-up menu by an input mechanism which is not identified as available for interaction with the pop-up menu. This implies that the user cannot necessarily complete the interaction with the pop-up menu with that input mechanism.

For example, if a pop-up menu is initialized with a mouse button depressed but that mouse button is not identified as available for manipulating the pop-up menu, then that mouse button can manipulate the pop-up menu until it is released. Assuming that the pop-up menu is not dismissed when that mouse button is released, then the mouse button cannot be used for further interaction with the pop-up menu, since it is not identified as available for that use.

The following list shows the input device valid for interaction with the pop-up menu with each option:

PU_KEYBOARD

The keyboard. PU_MOUSEBUTTON1

Mouse button 1. PU_MOUSEBUTTON2

Mouse button 2. PU_MOUSEBUTTON3

Mouse button 3.

Returns

rc (BOOL) - returns

Pop-up menu invoked indicator.

This function returns as soon as the pop-up menu has been invoked, which might be before the user has completed interacting with the pop-up menu.

TRUE

Pop-up menu successfully invoked

FALSE

Pop-up menu not successfully invoked.

Remarks

A pop-up menu is the unanchored equivalent of a pull-down menu, that is it can be positioned anywhere rather than being associated with an action bar. Typically, pop-up menus are related to specific objects, such as an icon, or with a particular area of the application's presentation space.

Once invoked, a pop-up menu behaves in exactly the same way as a pull-down menu.

Example Code

This example presents a pop-up menu (loaded from RES.DLL by WinLoadMenu) with the following characteristics: located at (0,50); initialized with mouse button 1 depressed; allowing keyboard and mouse button 1 interaction.

#define INCL_WINWINDOWMGR       /* Window Manager Functions     */
#define INCL_WINMENUS           /* Window Menu Functions        */
#include <os2.h>

HWND    hwndMenu;       /* menu window                          */
HWND    hwndOwner;      /* owner window                         */
HMODULE hmodDLL;        /* resource handle                      */
ULONG   idMenuid;       /* resource menu id                     */
BOOL    fSuccess;       /* success indicator                    */
HWND    hwndParent;     /* parent window                        */
ULONG   flOptions;      /* pop-up menu options                  */

if (DosQueryModuleHandle("RES.DLL",&hmodDLL))
   hwndMenu = WinLoadMenu(hwndOwner, hmodDLL, idMenuid);

flOptions = PU_MOUSEBUTTON1DOWN | PU_KEYBOARD | PU_MOUSEBUTTON1;
fSuccess = WinPopupMenu(hwndParent, hwndOwner, hwndMenu, 0, 50, 0, flOptions);

Related Functions

• WinCreateMenu
• WinLoadMenu