CKeyboardManager 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 CKeyboardManager Class.
Manages shortcut key tables for the main frame window and child frame windows.
class CKeyboardManager : public CObject
Name | Description |
CKeyboardManager::CKeyboardManager | Constructs a CKeyboardManager object. |
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. |
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.
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();
Header: afxkeyboardmanager.h
Constructs a CKeyboardManager
object.
CKeyboardManager();
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.
Frees the CKeyboardManager
resources and clears all shortcut key mappings.
static void CleanUp();
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.
Retrieves the default shortcut key for the specified command and window.
static BOOL FindDefaultAccelerator(
UINT uiCmd,
CString& str,
CFrameWnd* pWndFrame,
BOOL bIsDefaultFrame);
[in] uiCmd
The command ID.
[out] str
A reference to a CString
object.
[in] pWndFrame
A pointer to a frame window.
[in] bIsDefaultFrame
Specifies whether the frame window is the default frame window.
Nonzero if the shortcut is found; otherwise 0.
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.
Determines whether the specified key is handled by the CKeyboardManager Class.
static BOOL __stdcall IsKeyHandled(
WORD nKey,
BYTE fVirt,
CFrameWnd* pWndFrame,
BOOL bIsDefaultFrame);
Parameter | Description |
[in] nKey |
The key to check. |
[in] fVirt |
Specifies the behavior of the shortcut key. For a list of possible values, see ACCEL Structure. |
[in] pWndFrame |
A frame window. This method determines whether a shortcut key is handled in this frame. |
[in] bIsDefaultFrame |
A Boolean parameter that indicates whether pWndFrame is the default frame window. |
TRUE
if the shortcut key is handled. FALSE
if the key is not handled or if pWndFrame
is NULL
.
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
.
Indicates whether a character is printable.
static BOOL __stdcall IsKeyPrintable(const UINT nChar);
Parameter | Description |
[in] nChar |
The character that this method checks. |
Nonzero if the character is printable, zero if it is not.
This method fails if a call to GetKeyboardState fails.
Indicates whether menus show all the shortcut keys associated with menu commands or only the default shortcut keys.
static BOOL IsShowAllAccelerators();
Nonzero if the application lists all the shortcut keys for menu commands; 0 if the application displays only default shortcut keys.
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.
Loads the shortcut key tables from the Windows registry.
BOOL LoadState(
LPCTSTR lpszProfileName = NULL,
CFrameWnd* pDefaultFrame = NULL);
[in] lpszProfileName
The registry path where CKeyboardManager
data is saved.
[in] pDefaultFrame
A pointer to a frame window to use as the default window.
Nonzero if the state was loaded successfully or 0 otherwise.
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.
Reloads the shortcut key tables from the application resource.
void ResetAll();
This function clears the shortcuts stored in the CKeyboardManager
instance. It will then reload the state of the keyboard manager from the application resource.
Saves the shortcut key tables to the Windows registry.
BOOL SaveState(
LPCTSTR lpszProfileName = NULL,
CFrameWnd* pDefaultFrame = NULL);
[in] lpszProfileName
The registry path for saving the CKeyboardManager
state.
[in] pDefaultFrame
A pointer to a frame window that becomes the default window.
Nonzero if the keyboard manager state was saved successfully, or 0 otherwise.
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.
Shows all the shortcut keys associated with menu commands.
static void ShowAllAccelerators(
BOOL bShowAll = TRUE,
LPCTSTR lpszDelimiter = _afxDefaultAcceleratorDelimiter);
[in] bShowAll
If true
, all the shortcut keys will be displayed. If false
, only the first shortcut key will be displayed.
[in] lpszDelimiter
A string to insert between shortcut keys. This delimiter has no effect if only one shortcut key is displayed.
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.
Converts a character to its upper register.
static UINT TranslateCharToUpper(const UINT nChar);
[in] nChar
The character to convert.
The character that is the upper register of the input parameter.
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);
[in] pTemplate
A pointer to a document template.
[in] lpAccel
A pointer to the new shortcut key.
[in] nSize
The size of the new shortcut table.
[in] pDefaultFrame
A pointer to the default frame window.
[in] hAccelNew
A handle to the new shortcut table.
Nonzero if the method is successful; otherwise 0.
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.
Hierarchy Chart
Classes
CWinAppEx Class
CWinAppEx::InitKeyboardManager
Keyboard and Mouse Customization