IPopUpMenu

The IPopUpMenu class creates a pop-up menu. The Open Class Library supports the creation of pop-up menus on demand using IMenuHandler::makePopUpMenu and ICnrMenuHandler::makePopUpMenu.

ICommandEvents do not specify whether they are for a menu bar or pop-up menu. If you need to tell the difference, you must use different identifiers for the menu items to distinguish whether they are on the menu bar or the pop-up menu. For example, you might need to apply different actions to a menu item object when the user selects it from the menu bar as opposed to the pop-up menu.

AIX Considerations

The Open Class Library adds a Motif callback routine to all pop-up menus to enable processing of the following menu events:

Windows Considerations

To support menus loaded from a resource file, IPopUpMenu classes have the following requirements:


IPopUpMenu - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class. You cannot copy or assign IPopUpMenu objects because the copy constructor and assignment operator are private functions.


[view class]
~IPopUpMenu
public:
virtual ~IPopUpMenu()

Destroys the pop-up menu object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IPopUpMenu


Overload 1
public:
IPopUpMenu(const IResourceId& menuResId, IWindow* owner)

Creates a pop-up menu object from a menu resource ID and window owner.

When you create a pop-up menu for an IContainerControl or an IContainerObject object, specify the container control as the owner of the pop-up menu. If you need to use an IMenuHandler or an ICnrMenuHandler, attach it to the container window, also.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

To support menus loaded from a resource file, IPopUpMenu classes have the following requirements:

  • Menu resources must be defined using the MENUEX keyword.
  • Unique IDs must be provided for all pop-up menu items, indicated by the POPUP keyword.


Overload 2
public:
IPopUpMenu( IWindow* owner, unsigned long menuWindowId, const Style& style = defaultStyle ( ) )

Creates an empty pop-up menu using a window ID, owner window, and styles.

When you create a pop-up menu for an IContainerControl or an IContainerObject object, specify the container control as the owner of the pop-up menu. If you need to use an IMenuHandler or an ICnrMenuHandler, attach it to the container window, also.

Exception

IInvalidParameter owner is 0. You must provide a valid owner window to create an IPopUpMenu object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event-Handling Implementation

Event-handling implementation members perform processing needed to allow handlers to properly receive GUI events and to route these events.


[view class]
id
public:
virtual unsigned long id() const

Returns the menu identifier of the menu.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Due to implementation details, a special implementation of this method unique for IPopUpMenu is necessary on Motif platforms.

OS/2 Considerations

The inherited version of this method should be used on OS/2. See id .

Windows Considerations

The inherited version of this method should be used on Win32. See id .


[view class]
isAutoDeleteObject
public:
bool isAutoDeleteObject() const

If the IPopUpMenu object is deleted when it's underlying window system menu is destroyed, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAutoDeleteObject
public:
void setAutoDeleteObject(bool autoDelete = true)

If you call this method with an argument of TRUE (the default), &IOC. will delete this IPopUpMenu object automatically for you when the popup menu is dismissed. If you call this method with FALSE, you are responsible for deleting this IPopUpMenu object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

If you call IPopUpMenu::setAutoDeleteObject(true), the IPopUpMenu object will be automatically deleted when the menu is ended (unmapped).

OS/2 Considerations

If you call IPopUpMenu::setAutoDeleteObject(true), the IPopUpMenu object will be automatically deleted when the menu is ended (dismissed).

Windows Considerations

If you call IPopUpMenu::setAutoDeleteObject(true), the IPopUpMenu object will be automatically deleted on return from the IPopUpMenu::show method.


Visibility

You cause the pop-up menu to become visible by specifying the location on the screen where it is to be placed.


[view class]
show
public:
virtual IPopUpMenu& show( const IPoint& atLocation, ETrackButton trackButton = kNoTracking )

Displays the pop-up menu at the specified location. You can optionally specify which mouse button the popup menu tracks; this parameter applies to Windows operating systems only, it is ignored elsewhere. Specify atLocation using the window coordinates where you want the pop-up menu to appear. If you are showing the pop-up from within a menu handler, obtain the coordinates using IMenuEvent::mousePosition. If you call IPopUpMenu::setAutoDeleteObject(true), the IPopUpMenu object is deleted for you automatically.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

The behavior of this method is slightly different on Windows systems. On Windows, this method returns after the popup menu has been dismissed. If you have set "autoDeleteObject" to TRUE, this IPopUpMenu object will have been deleted by the time this method returns. If you have not set "autoDeleteObject", or have set it to FALSE, you may delete this IPopUpMenu object yourself immediately on return from this method or at some later time.


IPopUpMenu - Enumerations


[view class]
ETrackButton
enum ETrackButton { kLeftButton, 
                    kRightButton, 
                    kNoTracking }

Used to specify which mouse button the popup menu tracks; this parameter applies to Windows operating systems only, it is ignored elsewhere.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Ignored on Motif systems.

OS/2 Considerations

Ignored on OS/2.


IPopUpMenu - Inherited Member Functions and Data

Inherited Public Functions

IMenu
INotifier
IStandardNotifier

Inherited Public Data

INotifier
IMenu

Inherited Protected Functions

IStandardNotifier
INotifier
IMenu

Inherited Protected Data