### 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:

  - Showing a menu on the display
  - Selecting a menu item in a menu
  - Removing a menu from the display

#### 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.

### 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.

~IPopUpMenu

      public:
      virtual ~IPopUpMenu()

  Destroys the pop-up menu object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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 .

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

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.

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

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

  -     virtual ~IMenu()

  -     virtual IMenu& add(IMenuItem& menuItem, Cursor& cursor)

  -     virtual IMenu&
          addAsNext( IMenuItem& menuItem,
                     Cursor& cursor )

  -     virtual IMenu&
          addBitmap( unsigned long newItemId,
                     const IResourceId& bitmapResId,
                     unsigned long intoSubmenuId = 0 )

  -     virtual IMenu&
          addBitmap( unsigned long newItemId,
                     unsigned long bitmapResId,
                     unsigned long intoSubmenuId = 0 )

  -     virtual IMenu&
          addBitmap( unsigned long newItemId,
                     const IBitmapHandle& itemBitmap,
                     unsigned long intoSubmenuId = 0 )

  -     virtual IMenu&
          addItem( IMenuItem& menuItem,
                   unsigned long intoSubmenuId = 0 )

  -     virtual IMenu&
          addSeparator( unsigned long newItemId,
                        unsigned long intoSubmenuId )

  -     virtual IMenu&
          addSeparator( unsigned long intoSubmenuId = 0 )

  -     virtual IMenu&
          addSubmenu( unsigned long itemId,
                      const IResourceId& submenuResId )

  -     virtual IMenu& addSubmenu(unsigned long itemId)

  -     virtual IMenu&
          addText( unsigned long newItemId,
                   const IResourceId& textResId,
                   unsigned long intoSubmenuId = 0 )

  -     virtual IMenu&
          addText( unsigned long newItemId,
                   const char* itemText,
                   unsigned long intoSubmenuId = 0 )

  -     virtual IMenu&
          checkItem( unsigned long itemId,
                     bool check = true )

  -     virtual unsigned long
          conditionalCascade( unsigned long itemWithSubmenuId )

  -     Cursor
          cursor( unsigned long itemId,
                  unsigned long inSubmenuId = 0 ) const

  -     static Style defaultStyle()

  -     virtual IMenu& deleteAt(Cursor& cursor)

  -     virtual IMenu& deleteItem(unsigned long itemId)

  -     virtual IMenu& disableItem(unsigned long itemId)

  -     virtual IMenu& disableUpdate()

  -     virtual IMenuItem elementAt(const Cursor& cursor) const

  -     virtual IMenu&
          enableItem( unsigned long itemId,
                      bool enable = true )

  -     virtual IMenu& enableUpdate(bool enableWindow = true)

  -     virtual IWindowHandle handle() const

  -     virtual IMenu& hide()

  -     IMenu(const IMenuHandle& menuHandle)

  -     virtual bool isFrameWindow() const

  -     bool isItemChecked(unsigned long itemId) const

  -     bool isItemEnabled(unsigned long itemId) const

  -     bool isShowing() const

  -     virtual bool isValid() const

  -     bool isVisible() const

  -     unsigned long itemHelpId(unsigned long menuItemId) const

  -     IDMItemProvider* itemProvider() const

  -     IRectangle itemRect(unsigned long itemId) const

  -     virtual IMenuHandle menuHandle() const

  -     IMenuItem menuItem(unsigned long itemId) const

  -     static IMenuHandle menuWithParent(IWindow& parent)

  -     unsigned long
          numberOfItems( unsigned long forSubmenuId = 0 ) const

  -     virtual IWindow* owner() const

  -     virtual IMenu&
          refresh( const IRectangle& invalidRectangle,
                   bool immediate = false )

  -     virtual IMenu&
          refresh( IWindow::RefreshType type = IWindow::paintAll )

  -     virtual IMenu&
          removeConditionalCascade( unsigned long itemWithSubmenuId )

  -     virtual IMenu&
          removeSubmenu( unsigned long itemWithSubmenuId )

  -     virtual IMenu& removeSubmenuAt(Cursor& cursor)

  -     virtual IMenu& selectItem(unsigned long itemId)

  -     virtual IMenu&
          setBitmap( unsigned long menuItemId,
                     const IResourceId& newBitmapResId )

  -     virtual IMenu&
          setBitmap( unsigned long menuItemId,
                     const IBitmapHandle& bitmapHandle )

  -     virtual IMenu&
          setBitmap( unsigned long menuItemId,
                     unsigned long newBitmapResId )

  -     virtual IMenu&
          setConditionalCascade( unsigned long itemWithSubmenuId,
                                 unsigned long defaultItemId )

  -     static void setDefaultStyle(const Style& aStyle)

  -     virtual IMenu& setItem(const IMenuItem& menuItem)

  -     virtual IMenu&
          setItemHelpId( unsigned long menuItemId,
                         unsigned long helpTopicId )

  -     IMenu& setItemProvider(IDMItemProvider* dragProvider)

  -     virtual IMenu&
          setSubmenu( unsigned long itemId,
                      const IResourceId& submenuResId )

  -     virtual IMenu&
          setText( unsigned long menuItemId,
                   const IResourceId& newTextResId )

  -     virtual IMenu&
          setText( unsigned long menuItemId,
                   const char* newText )

  -     virtual IMenu& uncheckItem(unsigned long itemId)

  -     virtual IWindow* window() const

  INotifier

  -     virtual ~INotifier()

  -     virtual INotifier& disableNotification() = 0

  -     virtual INotifier&
          enableNotification( bool enable = true ) = 0

  -     INotifier()

  -     virtual bool isEnabledForNotification() const = 0

  -     virtual INotifier&
          notifyObservers( const INotificationEvent& event ) = 0

  -     virtual INotifier&
          notifyObserversAsync( const INotificationEvent& event )

  -     const IThreadId& threadId() const

  IStandardNotifier

  -     virtual ~IStandardNotifier()

  -     virtual IStandardNotifier& disableNotification()

  -     virtual IStandardNotifier&
          enableNotification( bool enable = true )

  -     virtual bool isEnabledForNotification() const

  -     IStandardNotifier()

  -     IStandardNotifier(const IStandardNotifier& copy)

  -     virtual INotifierAddress notifierAddress() const

  -     virtual IStandardNotifier&
          notifyObservers( const INotificationEvent& anEvent )

  -     virtual IStandardNotifier&
          notifyObserversAsync( const INotificationEvent& anEvent )

  -     IStandardNotifier&
          operator =( const IStandardNotifier& aStandardNotifier )

#### Inherited Public Data

  INotifier

  -     static INotificationId const allChangesId

  -     static INotificationId const deleteId

  IMenu

  -     static const Style classDefaultStyle

  -     static const Style noStyle

  -     static const Style visible

#### Inherited Protected Functions

  IStandardNotifier

  -     virtual IStandardNotifier&
          addObserver( IObserver& observer,
                       const IInterest& interest )

  -     virtual IStandardNotifier&
          notifyObservers( const INotificationId& nId )

  -     virtual IObserverList&
          observerList( const IInterest* anInterest = 0 ) const

  -     virtual IStandardNotifier& removeAllObservers()

  -     virtual IStandardNotifier&
          removeObserver( IObserver& observer )

  -     virtual IStandardNotifier&
          removeObserver( IObserver& observer,
                          const IInterest& interest )

  INotifier

  -     virtual INotifier&
          addObserver( IObserver& observer,
                       const IInterest& interest )

  -     virtual INotifier&
          notifyObservers( const INotificationId& id ) = 0

  -     virtual IObserverList&
          observerList( const IInterest* anInterest = 0 ) const = 0

  -     virtual INotifier& removeAllObservers() = 0

  -     virtual INotifier& removeObserver(IObserver& observer) = 0

  -     virtual INotifier&
          removeObserver( IObserver& observer,
                          const IInterest& interest )

  IMenu

  -     IMenu()

  -     void setWindow(IWindow* window)

#### Inherited Protected Data

  - None