CContextMenuManager Class
The CContextMenuManager object manages shortcut menus, also known as context menus.
class CContextMenuManager : public CObject
| Name | Description |
|---|---|
| CContextMenuManager::CContextMenuManager | Constructs a CContextMenuManager object. |
CContextMenuManager::~CContextMenuManager |
Destructor. |
| 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. |
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);
CContextMenuManager
Header: afxcontextmenumanager.h
Adds a new shortcut menu to the CContextMenuManager.
BOOL AddMenu(
UINT uiMenuNameResId,
UINT uiMenuResId);
BOOL AddMenu(
LPCTSTR lpszName,
UINT uiMenuResId);
uiMenuNameResId
[in] A resource ID for a string that contains the name for the new menu.
uiMenuResId
[in] The menu resource ID.
lpszName
[in] A string that contains the name for the new menu.
Nonzero if the method was successful; 0 if the method fails.
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();
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;
nMenuResId
[in] The resource ID for the menu.
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;
lpszName
[in] A string that contains the name of the menu to retrieve.
puiOrigResID
[out] A pointer to an UINT. This parameter contains the resource ID of the specified menu, if found.
A handle to the menu that matches the name that was specified by lpszName. NULL if there is no menu called lpszName.
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;
listOfNames
[out] 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);
lpszProfileName
[in] A string that contains the relative path of a registry key.
Nonzero if the method is successful; otherwise 0.
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();
TRUE if the method is successful; FALSE if a failure occurs.
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);
lpszProfileName
[in] A string that contains the relative path of a registry key.
Nonzero if the method is successful; otherwise 0.
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);
bSet
[in] 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.
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);
uiMenuResId
[in] The resource ID of the menu that this method will display.
x
[in] The horizontal offset for the shortcut menu in client coordinates.
y
[in] The vertical offset for the shortcut menu in client coordinates
pWndOwner
[in] A pointer to the parent window of the shortcut menu.
bOwnMessage
[in] A Boolean parameter that indicates how messages are routed. If bOwnMessage is FALSE, standard MFC routing is used. Otherwise, pWndOwner receives the messages.
hmenuPopup
[in] The handle of the menu that this method will display.
bAutoDestroy
[in] A Boolean parameter that indicates whether the menu will be automatically destroyed.
bRightAlign
[in] 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.
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.
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);
hmenuPopup
[in] The handle of the shortcut menu that this method displays.
x
[in] The horizontal offset for the shortcut menu in client coordinates.
y
[in] The vertical offset for the shortcut menu in client coordinates.
pWndOwner
[in] A pointer to the parent window of the shortcut menu.
bRightAlign
[in] 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.
The menu command ID of the command that the user chooses; 0 if the user closes the shortcut menu without selecting a menu command.
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.