Share via

CContextMenuManager Class

  • Article

 

The latest version of this topic can be found at CContextMenuManager Class.

The CContextMenuManager object manages shortcut menus, also known as context menus.

Syntax

class CContextMenuManager : public CObject

Members

Public Constructors

Name Description
CContextMenuManager::CContextMenuManager Constructs a CContextMenuManager object.
CContextMenuManager::~CContextMenuManager Destructor.

Public Methods

Name Description
CContextMenuManager::AddMenu Adds a new shortcut menu.
CContextMenuManager::GetMenuById Returns a handle to the menu associated with the provided resource ID.
CContextMenuManager::GetMenuByName Returns a handle to the menu that matches the provided menu name.
CContextMenuManager::GetMenuNames Returns a list of menu names.
CContextMenuManager::LoadState Loads shortcut menus stored in the Windows registry.
CContextMenuManager::ResetState Clears the shortcut menus from the context menu manager.
CContextMenuManager::SaveState Saves shortcut menus to the Windows registry.
CContextMenuManager::SetDontCloseActiveMenu Controls whether the CContextMenuManager closes the active shortcut menu when it shows a new shortcut menu.
CContextMenuManager::ShowPopupMenu Displays the specified shortcut menu.
CContextMenuManager::TrackPopupMenu Displays the specified shortcut menu. Returns the index of the selected menu command.

Remarks

CContextMenuManager manages shortcut menus and makes sure that they have a consistent appearance.

You should not create a CContextMenuManager object manually. The framework of your application creates the CContextMenuManager object. However, you should call CWinAppEx::InitContextMenuManager when your application is initialized. After initializing the context manager, use the method CWinAppEx::GetContextMenuManager to obtain a pointer to the context manager for your application.

You can create shortcut menus at runtime by calling AddMenu. If you want to show the menu without first receiving user input, call ShowPopupMenu. TrackPopupMenu is used when you want to create a menu and wait for user input. TrackPopupMenu returns the index of the selected command or 0 if the user exited without selecting anything.

The CContextMenuManager can also save and load its state to the Windows registry.

Example

The following example demonstrates how to add a menu to a CContextMenuManager object, and how not to close the active pop-up menu when the CContextMenuManager object displays a new pop-up menu. This code snippet is part of the Custom Pages sample.

 // The GetContextMenuManager method is inherited from the CWinAppEx class.
    GetContextMenuManager()->AddMenu (_T("My menu"), IDR_CONTEXT_MENU);
    GetContextMenuManager()->SetDontCloseActiveMenu(true);

Inheritance Hierarchy

CObject

CContextMenuManager

Requirements

Header: afxcontextmenumanager.h

CContextMenuManager::AddMenu

Adds a new shortcut menu to the CContextMenuManager.

BOOL AddMenu(
    UINT uiMenuNameResId,  
    UINT uiMenuResId);

 
BOOL AddMenu(
    LPCTSTR lpszName,  
    UINT uiMenuResId);

Parameters

[in] uiMenuNameResId
A resource ID for a string that contains the name for the new menu.

[in] uiMenuResId
The menu resource ID.

[in] lpszName
A string that contains the name for the new menu.

Return Value

Nonzero if the method was successful; 0 if the method fails.

Remarks

This method fails if uiMenuResId is invalid or if another menu with the same name already is in the CContextMenuManager.

CContextMenuManager::CContextMenuManager

Constructs a CContextMenuManager object.

CContextMenuManager();

Remarks

In most cases, you should not create a CContextMenuManager manually. The framework of your application creates the CContextMenuManager object. You should call CWinAppEx::InitContextMenuManager during the initialization of your application. To get a pointer to the context manager, call CWinAppEx::GetContextMenuManager.

CContextMenuManager::GetMenuById

Returns a handle to the menu associated with a given resource ID.

HMENU GetMenuById(UINT nMenuResId) const;

Parameters

[in] nMenuResId
The resource ID for the menu.

Return Value

A handle to the associated menu or NULL if the menu is not found.

CContextMenuManager::GetMenuByName

Returns a handle to a specific menu.

HMENU GetMenuByName(
    LPCTSTR lpszName,  
    UINT* puiOrigResID = NULL) const;

Parameters

[in] lpszName
A string that contains the name of the menu to retrieve.

[out] puiOrigResID
A pointer to an UINT. This parameter contains the resource ID of the specified menu, if found.

Return Value

A handle to the menu that matches the name that was specified by lpszName. NULL if there is no menu called lpszName.

Remarks

If this method finds a menu that matches lpszName, GetMenuByName stores the menu resource ID in the parameter puiOrigResID.

CContextMenuManager::GetMenuNames

Returns the list of menu names added to the CContextMenuManager.

void GetMenuNames(CStringList& listOfNames) const;

Parameters

[out] listOfNames
A reference to a CStringList parameter. This method writes the list of menu names to this parameter.

CContextMenuManager::LoadState

Loads information associated with the CContextMenuManager Class from the Windows registry.

virtual BOOL LoadState(LPCTSTR lpszProfileName = NULL);

Parameters

[in] lpszProfileName
A string that contains the relative path of a registry key.

Return Value

Nonzero if the method is successful; otherwise 0.

Remarks

The lpszProfileName parameter is not the absolute path for a registry entry. It is a relative path that is added to the end of the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

Use the method CContextMenuManager::SaveState to save the shortcut menus to the registry.

CContextMenuManager::ResetState

Clears all items from the shortcut menus associated with the CContextMenuManager Class.

virtual BOOL ResetState();

Return Value

TRUE if the method is successful; FALSE if a failure occurs.

Remarks

This method clears the pop-up menus and removes them from the CContextMenuManager.

CContextMenuManager::SaveState

Saves information associated with the CContextMenuManager Class to the Windows registry.

virtual BOOL SaveState(LPCTSTR lpszProfileName = NULL);

Parameters

[in] lpszProfileName
A string that contains the relative path of a registry key.

Return Value

Nonzero if the method is successful; otherwise 0.

Remarks

The lpszProfileName parameter is not the absolute path for a registry entry. It is a relative path that is added to the end of the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

Use the method CContextMenuManager::LoadState to load the shortcut menus from the registry.

CContextMenuManager::SetDontCloseActiveMenu

Controls whether the CContextMenuManager closes the active pop-up menu when it displays a new pop-up menu.

void SetDontCloseActiveMenu (BOOL bSet = TRUE);

Parameters

[in] bSet
A Boolean parameter that controls whether to close the active pop-up menu. A value of TRUE indicates the active pop-up menu is not closed. FALSE indicates that the active pop-up menu is closed.

Remarks

By default, the CContextMenuManager closes the active pop-up menu.

CContextMenuManager::ShowPopupMenu

Displays the specified shortcut menu.

virtual BOOL ShowPopupMenu(
    UINT uiMenuResId,  
    int x,  
    int y,  
    CWnd* pWndOwner,  
    BOOL bOwnMessage = FALSE,  
    BOOL bRightAlign = FALSE);

 
virtual CMFCPopupMenu* ShowPopupMenu(
    HMENU hmenuPopup,  
    int x,  
    int y,  
    CWnd* pWndOwner,  
    BOOL bOwnMessage = FALSE,  
    BOOL bAutoDestroy = TRUE,  
    BOOL bRightAlign = FALSE);

Parameters

[in] uiMenuResId
The resource ID of the menu that this method will display.

[in] x
The horizontal offset for the shortcut menu in client coordinates.

[in] y
The vertical offset for the shortcut menu in client coordinates

[in] pWndOwner
A pointer to the parent window of the shortcut menu.

[in] bOwnMessage
A Boolean parameter that indicates how messages are routed. If bOwnMessage is FALSE, standard MFC routing is used. Otherwise, pWndOwner receives the messages.

[in] hmenuPopup
The handle of the menu that this method will display.

[in] bAutoDestroy
A Boolean parameter that indicates whether the menu will be automatically destroyed.

[in] bRightAlign
A Boolean parameter that indicates how the menu items are aligned. If bRightAlign is TRUE, the menu is right-aligned for right-to-left reading order.

Return Value

The first method overload returns nonzero if the method shows the menu successfully; otherwise 0. The second method overload returns a pointer to CMFCPopupMenu if the shortcut menu displays correctly; otherwise NULL.

Remarks

This method resembles the method CContextMenuManager::TrackPopupMenu in that both methods display a shortcut menu. However, TrackPopupMenu returns the index of the selected menu command.

If the parameter bAutoDestroy is FALSE, you must manually call the inherited DestroyMenu method to release memory resources. The default implementation of ShowPopupMenu does not use the parameter bAutoDestroy. It is provided for future use or for custom classes derived from the CContextMenuManager Class.

CContextMenuManager::TrackPopupMenu

Displays the specified shortcut menu and returns the index of the selected shortcut menu command.

virtual UINT TrackPopupMenu(
    HMENU hmenuPopup,  
    int x,  
    int y,  
    CWnd* pWndOwner,  
    BOOL bRightAlign = FALSE);

Parameters

[in] hmenuPopup
The handle of the shortcut menu that this method displays.

[in] x
The horizontal offset for the shortcut menu in client coordinates.

[in] y
The vertical offset for the shortcut menu in client coordinates.

[in] pWndOwner
A pointer to the parent window of the shortcut menu.

[in] bRightAlign
A Boolean parameter that indicates how menu items are aligned. If bRightAlign is TRUE, the menu is right-aligned for right-to-left reading order. If bRightAlign is FALSE, the menu is left-aligned for left-to-right reading order.

Return Value

The menu command ID of the command that the user chooses; 0 if the user closes the shortcut menu without selecting a menu command.

Remarks

This method functions as a modal call to display a shortcut menu. The application will not continue to the following line in code until the user either closes the shortcut menu or selects a command. An alternative method that you can use to display a shortcut menu is CContextMenuManager::ShowPopupMenu. That method is not a modal call and will not return the ID of the selected command.

See Also

Hierarchy Chart
Classes
CWinAppEx Class