CContextMenuManager Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

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

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

class CContextMenuManager : public CObject  

Public Constructors

NameDescription
CContextMenuManager::CContextMenuManagerConstructs a CContextMenuManager object.
CContextMenuManager::~CContextMenuManagerDestructor.

Public Methods

NameDescription
CContextMenuManager::AddMenuAdds a new shortcut menu.
CContextMenuManager::GetMenuByIdReturns a handle to the menu associated with the provided resource ID.
CContextMenuManager::GetMenuByNameReturns a handle to the menu that matches the provided menu name.
CContextMenuManager::GetMenuNamesReturns a list of menu names.
CContextMenuManager::LoadStateLoads shortcut menus stored in the Windows registry.
CContextMenuManager::ResetStateClears the shortcut menus from the context menu manager.
CContextMenuManager::SaveStateSaves shortcut menus to the Windows registry.
CContextMenuManager::SetDontCloseActiveMenuControls whether the CContextMenuManager closes the active shortcut menu when it shows a new shortcut menu.
CContextMenuManager::ShowPopupMenuDisplays the specified shortcut menu.
CContextMenuManager::TrackPopupMenuDisplays the specified shortcut menu. Returns the index of the selected menu command.

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.

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);

CObject

CContextMenuManager

Header: afxcontextmenumanager.h

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Hierarchy Chart
Classes
CWinAppEx Class

Show: