CContextMenuManager Class
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
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.