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  

Public Constructors

NameDescription
CKeyboardManager::CKeyboardManagerConstructs a CKeyboardManager object.

Public Methods

NameDescription
CKeyboardManager::CleanUpClears the shortcut key tables.
CKeyboardManager::FindDefaultAcceleratorRetrieves the default shortcut key for the specified command and window.
CKeyboardManager::IsKeyHandledDetermines whether a key is handled by the accelerator table.
CKeyboardManager::IsKeyPrintableIndicates whether a character is printable.
CKeyboardManager::IsShowAllAcceleratorsIndicates whether menus show all shortcut keys for a command or only the default shortcut key.
CKeyboardManager::LoadStateLoads the shortcut key tables from the Windows registry.
CKeyboardManager::ResetAllReloads the shortcut key tables from the application resource.
CKeyboardManager::SaveStateSaves the shortcut key tables to the Windows registry.
CKeyboardManager::ShowAllAcceleratorsSpecifies 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::TranslateCharToUpperConverts a character to its upper register.
CKeyboardManager::UpdateAccelTableUpdates 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();

CObject

CKeyboardManager

Header: afxkeyboardmanager.h

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.

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.

Retrieves the default shortcut key for the specified command and window.

static BOOL FindDefaultAccelerator(
    UINT uiCmd,  
    CString& str,  
    CFrameWnd* pWndFrame,  
    BOOL bIsDefaultFrame);

Parameters

[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.

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.

Determines whether the specified key is handled by the CKeyboardManager Class.

static BOOL __stdcall IsKeyHandled(
    WORD nKey,  
    BYTE fVirt,  
    CFrameWnd* pWndFrame,  
    BOOL bIsDefaultFrame);

Parameters

ParameterDescription
[in] nKeyThe key to check.
[in] fVirtSpecifies the behavior of the shortcut key. For a list of possible values, see ACCEL Structure.
[in] pWndFrameA frame window. This method determines whether a shortcut key is handled in this frame.
[in] bIsDefaultFrameA 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.

Indicates whether a character is printable.

static BOOL __stdcall IsKeyPrintable(const UINT nChar);

Parameters

ParameterDescription
[in] nCharThe 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.

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.

Loads the shortcut key tables from the Windows registry.

BOOL LoadState(
    LPCTSTR lpszProfileName = NULL,  
    CFrameWnd* pDefaultFrame = NULL);

Parameters

[in] lpszProfileName
The registry path where CKeyboardManager data is saved.

[in] pDefaultFrame
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.

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.

Saves the shortcut key tables to the Windows registry.

BOOL SaveState(
    LPCTSTR lpszProfileName = NULL,  
    CFrameWnd* pDefaultFrame = NULL);

Parameters

[in] lpszProfileName
The registry path for saving the CKeyboardManager state.

[in] pDefaultFrame
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.

Shows all the shortcut keys associated with menu commands.

static void ShowAllAccelerators(
    BOOL bShowAll = TRUE,  
    LPCTSTR lpszDelimiter = _afxDefaultAcceleratorDelimiter);

Parameters

[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.

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.

Converts a character to its upper register.

static UINT TranslateCharToUpper(const UINT nChar);

Parameters

[in] nChar
The character to convert.

Return Value

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

Parameters

[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.

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.

Hierarchy Chart
Classes
CWinAppEx Class
CWinAppEx::InitKeyboardManager
Keyboard and Mouse Customization

Show: