CKeyboardManager Class
Manages shortcut key tables for the main frame window and child frame windows.
Syntax
class CKeyboardManager : public CObject
Members
Public Constructors
| Name | Description |
|---|---|
| CKeyboardManager::CKeyboardManager | Constructs a CKeyboardManager object. |
Public Methods
| Name | Description |
|---|---|
| CKeyboardManager::CleanUp | Clears the shortcut key tables. |
| CKeyboardManager::FindDefaultAccelerator | Retrieves the default shortcut key for the specified command and window. |
| CKeyboardManager::IsKeyHandled | Determines whether a key is handled by the accelerator table. |
| CKeyboardManager::IsKeyPrintable | Indicates whether a character is printable. |
| CKeyboardManager::IsShowAllAccelerators | Indicates whether menus show all shortcut keys for a command or only the default shortcut key. |
| CKeyboardManager::LoadState | Loads the shortcut key tables from the Windows registry. |
| CKeyboardManager::ResetAll | Reloads the shortcut key tables from the application resource. |
| CKeyboardManager::SaveState | Saves the shortcut key tables to the Windows registry. |
| CKeyboardManager::ShowAllAccelerators | Specifies whether the framework displays all the shortcut keys for all commands, or a single shortcut key for each command. This method does not affect commands that have only one associated shortcut key. |
| CKeyboardManager::TranslateCharToUpper | Converts a character to its upper register. |
| CKeyboardManager::UpdateAccelTable | Updates a shortcut key table with a new shortcut key table. |
Remarks
The members of this class enable you to save and load shortcut key tables to the Windows registry, use a template to update the short cut key tables, and find the default shortcut key for a command in a frame window. In addition, the CKeyboardManager object lets you control how shortcut keys are displayed to the user.
You should not create a CKeyboardManager object manually. It will be created automatically by the framework of your application. However, you should call CWinAppEx::InitKeyboardManager during the initialization process of your application. To get a pointer to the keyboard manager for your application, call CWinAppEx::GetKeyboardManager.
Example
The following example demonstrates how to retrieve a pointer to a CKeyboardManager object from a CWinAppEx class, and how to show all the shortcut keys associated with menu commands. This code snippet is part of the Custom Pages sample.
// The GetKeyboardManager method is inherited from the CWinAppEx class.
CKeyboardManager *cKeyboardManager = GetKeyboardManager();
cKeyboardManager->ShowAllAccelerators();
Inheritance Hierarchy
Requirements
Header: afxkeyboardmanager.h
CKeyboardManager::CKeyboardManager
Constructs a CKeyboardManager object.
CKeyboardManager();
Remarks
In most cases, you do not have to create a CKeyboardManager directly. By default, the framework creates one for you. To get a pointer to the CKeyboardManager, call CWinAppEx::GetKeyboardManager. If you do create one manually, you must initialize it with the method CWinAppEx::InitKeyboardManager.
CKeyboardManager::CleanUp
Frees the CKeyboardManager resources and clears all shortcut key mappings.
static void CleanUp();
Remarks
For more information about shortcut keys, see Keyboard and Mouse Customization.
You do not have to call this function when your application exits because the framework calls it automatically during application exit.
CKeyboardManager::FindDefaultAccelerator
Retrieves the default shortcut key for the specified command and window.
static BOOL FindDefaultAccelerator(
UINT uiCmd,
CString& str,
CFrameWnd* pWndFrame,
BOOL bIsDefaultFrame);
Parameters
uiCmd
[in] The command ID.
str
[out] A reference to a CString object.
pWndFrame
[in] A pointer to a frame window.
bIsDefaultFrame
[in] Specifies whether the frame window is the default frame window.
Return Value
Nonzero if the shortcut is found; otherwise 0.
Remarks
This method looks up the command specified by uiCmd and retrieves the default shortcut key. Then the method takes the string associated with this shortcut key and writes the value to the str parameter.
CKeyboardManager::IsKeyHandled
Determines whether the specified key is handled by the CKeyboardManager Class.
static BOOL __stdcall IsKeyHandled(
WORD nKey,
BYTE fVirt,
CFrameWnd* pWndFrame,
BOOL bIsDefaultFrame);
Parameters
nKey
[in] The key to check.
fVirt
[in] Specifies the behavior of the shortcut key. For a list of possible values, see ACCEL Structure.
pWndFrame
[in] A frame window. This method determines whether a shortcut key is handled in this frame.
bIsDefaultFrame
[in] A Boolean parameter that indicates whether pWndFrame is the default frame window.
Return Value
TRUE if the shortcut key is handled. FALSE if the key is not handled or if pWndFrame is NULL.
Remarks
The input parameters must match the entry in the accelerator table both for nKey and fVirt to determine whether a shortcut key is handled in pWndFrame.
CKeyboardManager::IsKeyPrintable
Indicates whether a character is printable.
static BOOL __stdcall IsKeyPrintable(const UINT nChar);
Parameters
nChar
[in] The character that this method checks.
Return Value
Nonzero if the character is printable, zero if it is not.
Remarks
This method fails if a call to GetKeyboardState fails.
CKeyboardManager::IsShowAllAccelerators
Indicates whether menus show all the shortcut keys associated with menu commands or only the default shortcut keys.
static BOOL IsShowAllAccelerators();
Return Value
Nonzero if the application lists all the shortcut keys for menu commands; 0 if the application displays only default shortcut keys.
Remarks
The application lists the shortcut keys for menu commands in the menu bar. Use the function CKeyboardManager::ShowAllAccelerators to control whether the application lists all the shortcut keys or just the default shortcut keys.
CKeyboardManager::LoadState
Loads the shortcut key tables from the Windows registry.
BOOL LoadState(
LPCTSTR lpszProfileName = NULL,
CFrameWnd* pDefaultFrame = NULL);
Parameters
lpszProfileName
[in] The registry path where CKeyboardManager data is saved.
pDefaultFrame
[in] A pointer to a frame window to use as the default window.
Return Value
Nonzero if the state was loaded successfully or 0 otherwise.
Remarks
If the lpszProfileName parameter is NULL, this method checks the default registry location for CKeyboardManager data. The default registry location is specified by the CWinAppEx Class. The data must be previously written with the method CKeyboardManager::SaveState.
If you do not specify a default window, the main frame window of your application will be used.
CKeyboardManager::ResetAll
Reloads the shortcut key tables from the application resource.
void ResetAll();
Remarks
This function clears the shortcuts stored in the CKeyboardManager instance. It will then reload the state of the keyboard manager from the application resource.
CKeyboardManager::SaveState
Saves the shortcut key tables to the Windows registry.
BOOL SaveState(
LPCTSTR lpszProfileName = NULL,
CFrameWnd* pDefaultFrame = NULL);
Parameters
lpszProfileName
[in] The registry path for saving the CKeyboardManager state.
pDefaultFrame
[in] A pointer to a frame window that becomes the default window.
Return Value
Nonzero if the keyboard manager state was saved successfully, or 0 otherwise.
Remarks
If the lpszProfileName parameter is NULL, this method will write the CKeyboardManager state to the default location specified by the CWinAppEx Class. If you specify a location, you can load the data later using the method CKeyboardManager::LoadState.
If you do not specify a default window, the main frame window will be used as the default window.
CKeyboardManager::ShowAllAccelerators
Shows all the shortcut keys associated with menu commands.
static void ShowAllAccelerators(
BOOL bShowAll = TRUE,
LPCTSTR lpszDelimiter = _afxDefaultAcceleratorDelimiter);
Parameters
bShowAll
[in] If TRUE, all the shortcut keys will be displayed. If FALSE, only the first shortcut key will be displayed.
lpszDelimiter
[in] A string to insert between shortcut keys. This delimiter has no effect if only one shortcut key is displayed.
Remarks
By default, if a command has more than one shortcut key associated with it, only the first shortcut key will be shown. This function enables you to list all the shortcut keys associated with all commands.
The shortcut keys will be listed next to the command in the menu bar. If all the shortcut keys are displayed, the string provided by lpszDelimiter will separate individual shortcut keys.
CKeyboardManager::TranslateCharToUpper
Converts a character to its upper register.
static UINT TranslateCharToUpper(const UINT nChar);
Parameters
nChar
[in] The character to convert.
Return Value
The character that is the upper register of the input parameter.
CKeyboardManager::UpdateAccelTable
Updates a shortcut key table with a new shortcut key table.
BOOL UpdateAccelTable(
CMultiDocTemplate* pTemplate,
LPACCEL lpAccel,
int nSize,
CFrameWnd* pDefaultFrame = NULL);
BOOL UpdateAccelTable(
CMultiDocTemplate* pTemplate,
HACCEL hAccelNew,
CFrameWnd* pDefaultFrame = NULL);
Parameters
pTemplate
[in] A pointer to a document template.
lpAccel
[in] A pointer to the new shortcut key.
nSize
[in] The size of the new shortcut table.
pDefaultFrame
[in] A pointer to the default frame window.
hAccelNew
[in] A handle to the new shortcut table.
Return Value
Nonzero if the method is successful; otherwise 0.
Remarks
Use this function to replace the existing shortcut table with new shortcut keys for several frame window objects. The function receives a document template as a parameter to obtain access to all frame window objects connected to the given document template.
See also
Hierarchy Chart
Classes
CWinAppEx Class
CWinAppEx::InitKeyboardManager
Keyboard and Mouse Customization
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for