Implements Windows pop-up menu functionality and extends it by adding features such as tear-off menus and tooltips. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

class CMFCPopupMenu : public CMiniFrameWnd

Normally, MFC creates pop-up menus automatically. If you want to create a CMFCPopupMenu object manually, allocate one on the heap and then call CMFCPopupMenu::Create.

The following example demonstrates how to configure a pop-up menu object. The example shows how to set the logo and the sound of the pop-up menu, set the animation speed and type, draw menu shadows when the pop-up menu appears outside the main frame, set the maximum width, and set the right menu alignment of the pop-up menu. This code snippet is part of the Custom Pages sample.

[!code-cppNVC_MFC_CustomPages#2]

CObject

CCmdTarget

CWnd

CFrameWnd

CMiniFrameWnd

CMFCPopupMenu

Header: afxpopupmenu.h

static BOOL __stdcall ActivatePopupMenu(
    CFrameWnd* pTopFrame,
    CMFCPopupMenu* pPopupMenu);

[in] pTopFrame
[in] pPopupMenu

Sets whether a pop-up menu is enabled to show empty entries for user-defined tools.

static void AlwaysShowEmptyToolsEntry(BOOL bShow = TRUE);

bShow
[in] TRUE if the pop-up menu can display empty entries; FALSE otherwise.

BOOL AreAllCommandsShown() const;

Determines the location of a point relative to the pop-up menu.

MENUAREA_TYPE CheckArea(const CPoint& ptScreen) const;

ptScreen
[in] A point, in screen coordinates.

A MENUAREA_TYPE parameter that indicates where the point is relative to the pop-up menu.

A MENUAREA_TYPE parameter can have any one of the following values.

• OUTSIDE - ptScreen is outside the pop-up menu.

• LOGO - ptScreen is over a logo area.

• TEAROFF_CAPTION - ptScreen is over the tear-off caption.

• SHADOW_BOTTOM - ptScreen is over the bottom shadow of the pop-up menu.

• SHADOW_RIGHT - ptScreen is over the right shadow of the pop-up menu.

• MENU - ptScreen is over a command.

void CloseMenu(BOOL bSetFocusToBar = FALSE);

[in] bSetFocusToBar

Constructs a CMFCPopupMenu object.

CMFCPopupMenu(
    CMFCToolBarsMenuPropertyPage* pCustPage,
    LPCTSTR lpszTitle);

pCustPage
[in] A pointer to a customization page.

lpszTitle
[in] A string that contains the menu caption.

This method allocates the resources for a CMFCPopupMenu. To create the pop-up menu item, call CMFCPopupMenu::Create.

Creates a pop-up menu and attaches it to a CMFCPopupMenu object.

virtual BOOL Create(
    CWnd* pWndParent,
    int x,
    int y,
    HMENU hMenu,
    BOOL bLocked = FALSE,
    BOOL bOwnMessage = FALSE);

pWndParent
[in] The parent window for the CMFCPopupMenu.

x
[in] The horizontal screen coordinate for the location of the pop-up menu

y
[in] The vertical screen coordinate for the location of the pop-menu.

hMenu
[in] A handle to a menu resource.

bLocked
[in] A Boolean parameter that indicates whether the menu is customizable. FALSE indicates that the pop-up menu is customizable.

bOwnMessage
[in] A Boolean parameter that indicates how the framework routes the menu messages. See the Remarks section for more details.

TRUE if the method is successful; otherwise FALSE.

If bOwnMessage is TRUE, the framework routes any menu messages to pWndParent. pWndParent must not be NULL if bOwnMessage is TRUE. If bOwnMessage is FALSE, the framework routes the menu messages to the parent pop-up menu.

The following example demonstrates how to use the Create method of the CMFCPopuMenu class. This code snippet is part of the Custom Pages sample.

[!code-cppNVC_MFC_CustomPages#1]

virtual CPane* CreateTearOffBar(
    CFrameWnd* pWndMain,
    UINT uiID,
    LPCTSTR lpszName);

[in] pWndMain
[in] uiID
[in] lpszName

virtual BOOL DefaultMouseClickOnClose() const;

Initializes the logo for a pop-up menu.

void EnableMenuLogo(
    int iLogoSize,
    LOGO_LOCATION nLogoLocation = MENU_LOGO_LEFT);

iLogoSize
[in] The size of the logo, in pixels.

nLogoLocation
[in] An enumerated data type that indicates the location of the logo.

To display the logo, implement the method CFrameWndEx::OnDrawMenuLogo in the main frame window.

The possible values for nLogoLocation are MENU_LOGO_LEFT, MENU_LOGO_RIGHT, MENU_LOGO_TOP, and MENU_LOGO_BOTTOM.

Enables menu sound.

static void EnableMenuSound(BOOL bEnable = TRUE);

bEnable
[in] TRUE to enable sound, FALSE otherwise.

If you enable sound, the framework calls the PlaySound method when a user opens a pop-up menu or selects a menu command. By default, this feature is enabled.

void EnableResize(CSize sizeMinResize);

[in] sizeMinResize

void EnableScrolling(BOOL = TRUE);

[in] BOOL

void EnableVertResize(int nMinResize);

[in] nMinResize

CMFCToolBarMenuButton* FindSubItemByCommand(UINT uiCmd) const;

[in] uiCmd

Returns the currently active menu.

static CMFCPopupMenu* GetActiveMenu();

A pointer to the active pop-up menu, or NULL if no pop-up menu is currently active.

Each application can have at most one active pop-up menu.

Returns the animation speed for pop-up menus.

static UINT GetAnimationSpeed();

An integer that indicates the time, in milliseconds, that a pop-up menu animation takes to finish.

The animation speed is a global value. Use CMFCPopupMenu::SetAnimationSpeed to change the animation speed for pop-up menus.

Returns the current type of pop-up animation.

static CMFCPopupMenu::ANIMATION_TYPE GetAnimationType(BOOL bNoSystem = FALSE);

bNoSystem
[in] A Boolean parameter that indicates whether this method checks the global value. FALSE if you want this method to return the animation style for this instance of the CMFCPopupMenu Class.

An enumerated value that describes the animation type.

The style of animation for pop-up menus is global for your application. Use CMFCPopupMenu::SetAnimationType to set the animation style.

The following table lists the possible animation types.

DROP_DIRECTION GetDropDirection() const;

Indicates whether the focus is returned to the menu bar when a pop-up menu is displayed.

static BOOL GetForceMenuFocus();

TRUE if the input focus is returned to the menu bar when a pop-up menu is displayed; FALSE if the pop-up menu retains the focus.

By default, your application does not return focus to the menu bar. To change this setting, use CMFCPopupMenu::SetForceMenuFocus.

static BOOL __stdcall GetForceShadow();

Returns a handle to the attached menu resource.

HMENU GetHMenu();

Returns the CMFCPopupMenuBar embedded inside the pop-up menu.

virtual CMFCPopupMenuBar* GetMenuBar();

A pointer to the embedded CMFCPopupMenuBar.

The pop-up menu has an embedded CMFCPopupMenuBar object. You must override this method in a derived class if you are using a different embedded class.

Returns a pointer to the menu item at the specified index.

CMFCToolBarMenuButton* GetMenuItem(int iIndex) const;

iIndex
[in] The zero-based index of a menu item.

A pointer to a menu item. NULL if the index is invalid.

Menu items are represented by the CMFCToolBarMenuButton Class. When you call this method, it returns a pointer to the appropriate CMFCToolBarMenuButton.

Returns the number of items in a pop-up menu.

int GetMenuItemCount() const;

The number of items in the menu.

Returns a pointer to the window where the framework routes the pop-up menu messages.

CWnd* GetMessageWnd() const;

A pointer to the window that receives the pop-up menu messages; NULL if there is no window.

When you use the method CMFCPopupMenu::Create to create a pop-up menu, you specify what window receives the menu messages.

virtual CWnd* GetParentArea(CRect& rectParentBtn);

[in] rectParentBtn

Returns a pointer to the parent toolbar button.

CMFCToolBarMenuButton* GetParentButton() const;

A pointer to the parent toolbar button. NULL if the pop-up menu has no parent toolbar button.

A CMFCPopupMenu can be associated with a button on the menu. In this scenario, the pop-up menu appears when a user selects the parent toolbar button.

If the pop-up menu is a shortcut menu, it will have no parent toolbar button.

Returns a pointer to the parent pop-up menu.

CMFCPopupMenu* GetParentPopupMenu() const;

A pointer to the parent CMFCPopupMenu object; NULL if there is no parent pop-up menu.

A pop-up menu has a parent CMFCPopupMenu object only if it is a submenu.

CMFCRibbonBaseElement* GetParentRibbonElement() const;

Returns a pointer to the parent toolbar.

CMFCToolBar* GetParentToolBar() const;

A pointer to the parent toolbar. NULL if the pop-up menu has no parent toolbar.

If the CMFCPopupMenu is a shortcut menu, then it has no parent toolbar.

QUICK_CUSTOMIZE_TYPE GetQuickCustomizeType() const;

Returns a pointer to the currently selected menu command.

CMFCToolBarMenuButton* GetSelItem();

A pointer to the currently selected menu command; NULL if no item is selected.

The menu commands on a pop-up menu are represented by the CMFCToolBarMenuButton Class, or a class derived from CMFCToolBarMenuButton.

BOOL HasBeenResized() const;

Indicates whether the pop-up menu can hide rarely used commands.

BOOL HideRarelyUsedCommands() const;

TRUE if the pop-up menu can hide the rarely used commands; otherwise FALSE.

This method specifies only whether a pop-up menu can hide rarely used commands, not if that configuration is enabled. A pop-up menu can hide rarely used commands if it has a parent button and the parent window is derived from the CMFCMenuBar Class. Use CMFCMenuBar::SetRecentlyUsedMenus to enable this feature and CMFCMenuBar::IsRecentlyUsedMenus to determine if this feature is currently enabled. You must call both of these methods for the parent window.

virtual BOOL InCommand();

Inserts a new item into the pop-up menu at the specified location.

int InsertItem(
    const CMFCToolBarMenuButton& button,
    int iInsertA = -1);

button
[in] A reference to the menu item to add.

iInsertAt
[in] The zero-based index for the new item. If iInsertAt is -1, the item is added to the end of the menu.

The zero-based index of the position where the item was inserted. -1 if the method fails.

This method will fail if you provide an invalid value for iInsertAt, such as an integer larger than the number of items currently on the pop-up menu.

Inserts a separator into the pop-up menu at the specified location.

int InsertSeparator(int iInsertAt = -1);

iInsertAt
[in] The zero-based index of the position where this method will insert the separator.

The zero-based index of the position where the separator was inserted. -1 if this method fails.

A value of -1 for iInsertAt means this method will add the separator to the end of the pop-up menu.

This method fails if iInsertAt is an invalid value.

virtual BOOL IsAlwaysClose() const;

static BOOL __stdcall IsAlwaysShowEmptyToolsEntry();

Indicates whether the pop-up menu is functioning as a QuickCustomizePane.

BOOL IsCustomizePane();

TRUE if the pop-up is a QuckCustomizePane; otherwise FALSE.

Use the QuickCustomizePane to enable the user to directly customize the pop-up menu. The QuickCustomizePane is a CMFCPopupMenu that appears when the user clicks on a toolbar button to edit it directly.

Your application should call this method during CMDIFrameWndEx::OnShowCustomizePane.

BOOL IsEscClose();

Indicates whether a pop-up menu is currently idle.

virtual BOOL IsIdle() const;

TRUE if the pop-up menu is in idle mode; otherwise FALSE.

By default, a pop-up menu is in idle mode if the display animation is complete and the user is not scrolling the pop-up menu.

static UINT __stdcall IsMenuSound();

Determines whether the associated CMFCToolBarMenuButton Class is in QuickCustomize mode.

BOOL IsQuickCustomize();

TRUE if the associated menu button is in QuickCustomize mode; otherwise FALSE. This method will also return FALSE if the pop-up menu is not associated with a CMFCToolBarMenuButton.

In QuickCustomize mode the user selects a button on a toolbar to customize the button directly.

BOOL IsResizeble() const;

Indicates whether the menu is right-aligned or left-aligned.

BOOL IsRightAlign() const;

TRUE if the menu is right-aligned; FALSE if the menu left-aligned.

You can use CMFCPopupMenu::SetRightAlign to set the menu alignment. By default, pop-up menus use left-alignment.

Menu alignment is not a global setting and can vary between pop-up menus.

BOOL IsScrollable() const;

Indicates whether the framework notifies the parent frame when the user selects a command from the pop-up menu.

static BOOL IsSendMenuSelectMsg();

TRUE if the framework notifies the parent frame; otherwise FALSE.

The framework notifies the parent frame by sending it the WM_MENUSELECT message when a used selects a menu command.

Indicates whether the pop-up menu is currently visible.

BOOL IsShown() const;

TRUE if a pop-up menu is visible; otherwise FALSE.

void MoveTo(const CPoint& pt);

[in] pt

virtual void OnChangeHot(int nHot);

[in] nHot

virtual void OnChooseItem(UINT uidCmdID);

[in] uidCmdID

virtual BOOL OnCmdMsg(
    UINT nID,
    int nCode,
    void* pExtra,
    AFX_CMDHANDLERINFO* pHandlerInfo);

[in] nID
[in] nCode
[in] pExtra
[in] pHandlerInfo

BOOL PostCommand(UINT uiCommandID);

[in] uiCommandID

virtual BOOL PreTranslateMessage(MSG* pMsg);

[in] pMsg

virtual void RecalcLayout(BOOL bNotify = TRUE);

[in] bNotify

Clears all the items from a pop-up menu.

void RemoveAllItems();

Removes the specified item from the pop-up menu.

BOOL RemoveItem(int iIndex);

iIndex
[in] The zero-based index of the item to delete.

TRUE if the method is successful; otherwise FALSE.

This method automatically arranges any separators that are affected by the removal of an item. For more information about how the framework rearranges separators, see CMFCToolBar::RemoveButton.

virtual void SaveState();

Sets the animation speed for pop-up menus.

static void SetAnimationSpeed(UINT nElapse);

nElapse
[in] The new animation speed, in milliseconds.

The animation speed is a global value and affects all the pop-up menus in the application. This value specifies how long it takes for the animation for a pop-up menu to finish.

By default, this parameter is set to 30 milliseconds. The range of valid values for nElapse is from 0 to 200.

Sets the animation type for this pop-up menu.

static void SetAnimationType(CMFCPopupMenu::ANIMATION_TYPE type);

type
[in] An enumerated data type that specifies the type of animation.

See CMFCPopupMenu::GetAnimationType for a list of valid values for type.

void SetAutoDestroy(BOOL bAutoDestroy = TRUE);

[in] bAutoDestroy

Sets the default command for the pop-up menu.

void SetDefaultItem(UINT uiCmd);

uiCmd
[in] The menu command ID of the new default command.

The default command in the pop-up menu is the command that is selected when the pop-up menu appears.

Forces the input focus to return to the menu bar when a pop-up menu is displayed.

static void SetForceMenuFocus(BOOL bValue);

bValue
[in] TRUE if you want the framework to force the input focus to the menu bar when a pop-up menu is displayed. FALSE if you want the pop-up menu to retain the focus.

This method sets a flag that is global for all pop-up menus in the application. By default, this feature is not enabled.

Forces the framework to draw menu shadows when pop-up menus appear outside the main frame.

static void SetForceShadow(BOOL bValue);

bValue
[in] TRUE if you want the framework to draw menu shadows, FALSE otherwise.

When you call this method, it sets a global flag in your application. This flag affects all pop-up menus in your application.

Set the maximum width for the pop-up menu.

void SetMaxWidth(int iMaxWidth);

iMaxWidth
[in] The maximum width for the pop-up menu, in pixels.

If the text associated with a menu command will not fit in the maximum width, it is truncated and the part that does not fit is replaced by three dots.

void SetMessageWnd(CWnd* pMsgWnd);

[in] pMsgWnd

void SetParentRibbonElement(CMFCRibbonBaseElement* pElem);

[in] pElem

void SetQuickCustomizeType(QUICK_CUSTOMIZE_TYPE Type);

[in] Type

void SetQuickMode();

Sets the menu alignment for pop-up menus.

void SetRightAlign(BOOL bRightAlign = TRUE);

bRightAlign
[in] A Boolean that indicates the menu alignment. TRUE indicates right alignment, FALSE indicates left alignment.

By default, all pop-up menus are left-aligned.

Sets a flag that controls whether the pop-up menu notifies its parent frame when the user selects a command.

static void SetSendMenuSelectMsg(BOOL bSet = TRUE);

bSet
[in] TRUE if the pop-up menu notifies its parent frame, FALSE otherwise.

This is a global option for all the pop-up menus in an application. If it is enabled, the pop-up menus will send a WM_MENUSELECT message to the parent frame when the user selects a command.

Forces the pop-up menu to display all commands.

void ShowAllCommands();

This is not a global setting and affects only the current pop-up menu.

void TriggerResize();

Updates the shadows for all opened pop-up menus.

static void UpdateAllShadows(LPRECT lprectScreen = NULL);

lprectScreen
[in] A rectangle that specifies the region to update, in screen coordinates.

This method is useful when pop-up menus are displayed over animated controls or other windows that have dynamic content.

Updates the shadow for the pop-up menu.

void UpdateShadow(LPRECT lprectScreen = NULL);

lprectScreen
[in] A rectangle, in screen coordinates, that specifies the boundaries of the region to update.

Call this method when a pop-up menu that has a shadow overlaps an animated image.

Hierarchy Chart
Classes
CMFCPopupMenuBar Class