CHotKeyCtrl 类

项目
10/19/2023

提供 Windows 公共热键控件的功能。

语法

class CHotKeyCtrl : public CWnd

成员

公共构造函数

名称	描述
CHotKeyCtrl::CHotKeyCtrl	构造 `CHotKeyCtrl` 对象。

公共方法

名称	描述
CHotKeyCtrl::Create	创建热键控件并将其附加到 `CHotKeyCtrl` 对象。
CHotKeyCtrl::CreateEx	创建具有指定 Windows 扩展样式的热键控件，并将其附加到 `CHotKeyCtrl` 对象。
CHotKeyCtrl::GetHotKey	从热键控件中检索热键的虚拟键代码和修饰符标志。
CHotKeyCtrl::GetHotKeyName	检索本地字符集中分配给热键的键名称。
CHotKeyCtrl::GetKeyName	检索本地字符集中分配给指定虚拟键代码的键名称。
CHotKeyCtrl::SetHotKey	设置热键控件的热键组合。
CHotKeyCtrl::SetRules	定义热键控件的无效组合和默认修饰符组合。

备注

“热键控件”是使用户能够创建热键的窗口。 “热键”是一个键组合，用户可以按下该组合快速执行操作。（例如，用户可以创建一个热键来激活给定窗口并将其置于 Z 顺序的顶层。）热键控件显示用户的选择并确保用户选择有效的键组合。

此控件（以及 CHotKeyCtrl 类）仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。

当用户选择键组合时，应用程序可以从控件中检索指定的键组合，并使用 WM_SETHOTKEY 消息在系统中设置热键。每当用户从系统的任何部分按下热键时，WM_SETHOTKEY 消息中指定的窗口都会接收指定 SC_HOTKEY 的 WM_SYSCOMMAND 消息。此消息会激活接收它的窗口。热键始终有效，直到调用 WM_SETHOTKEY 的应用程序退出为止。

此机制不同于依赖于 WM_HOTKEY 消息以及 Windows RegisterHotKey 和 UnregisterHotKey 函数的热键支持。

有关使用 CHotKeyCtrl 的详细信息，请参阅控件和使用 CHotKeyCtrl。

继承层次结构

CObject

CCmdTarget

CWnd

CHotKeyCtrl

要求

标头： afxcmn.h

CHotKeyCtrl::CHotKeyCtrl

构造 CHotKeyCtrl 对象。

CHotKeyCtrl();

CHotKeyCtrl::Create

创建热键控件并将其附加到 CHotKeyCtrl 对象。

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

参数

dwStyle
指定热键控件的样式。应用控件样式的任意组合。有关详细信息，请参阅 Windows SDK 中的通用控件样式。

rect
指定热键控件的大小和位置。它可以是 CRect 对象或 RECT 结构。

pParentWnd
指定热键控件的父窗口，通常为 CDialog。不得为 NULL。

nID
指定热键控件的 ID。

返回值

如果初始化成功，则返回非零值；否则返回 0。

备注

请分两步构造 CHotKeyCtrl 对象。首先，调用构造函数，然后调用 Create，这将创建热键控件并将其附加到 CHotKeyCtrl 对象。

如果要将扩展窗口样式与控件一起使用，请调用 CreateEx 而不是 Create。

CHotKeyCtrl::CreateEx

调用此函数可以创建控件（子窗口）并将其与 CHotKeyCtrl 对象相关联。

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

参数

dwExStyle
指定要创建的控件的扩展样式。有关扩展 Windows 样式的列表，请参阅 Windows SDK 中 CreateWindowEx 的 dwExStyle 参数。

dwStyle
指定热键控件的样式。应用控件样式的任意组合。有关详细信息，请参阅 Windows SDK 中的通用控件样式。

rect
对 RECT 结构的引用，该结构描述了要在客户端坐标 pParentWnd 中创建的窗口的大小和位置。

pParentWnd
指向作为控件父级的窗口的指针。

nID
控件的子窗口 ID。

返回值

如果成功，则不为 0；否则为 0。

注解

使用 CreateEx 而不是 Create 来应用由 Windows 扩展样式前言 WS_EX_ 指定的扩展 Windows 样式。

CHotKeyCtrl::GetHotKey

从热键控件中检索键盘快捷方式的虚拟键代码和修饰符标志。

DWORD GetHotKey() const;

void GetHotKey(
    WORD& wVirtualKeyCode,
    WORD& wModifiers) const;

参数

wVirtualKeyCode
[out] 键盘快捷方式的虚拟键代码。有关标准虚拟键代码的列表，请参见 Winuser.h。

wModifiers
[out] 指示键盘快捷方式中的修饰键的标志的按位组合 (OR)。

修饰符标志如下所示：

标记	相应的键
HOTKEYF_ALT	Alt 键
HOTKEYF_CONTROL	CTRL 键
HOTKEYF_EXT	扩展键
HOTKEYF_SHIFT	SHIFT 键

返回值

在第一个重载方法中，包含虚拟键代码和修饰符标志的 DWORD。低位字的低位字节包含虚拟键代码，低位字的高位字节包含修饰符标志，高位字为零。

备注

虚拟键代码和修饰键一起定义键盘快捷方式。

CHotKeyCtrl::GetHotKeyName

调用此成员函数以获取热键的本地化名称。

CString GetHotKeyName() const;

返回值

当前选定热键的本地化名称。如果不存在选定热键，则 GetHotKeyName 返回空字符串。

备注

此成员函数返回的名称来自键盘驱动程序。可以在本地化版本的 Windows 中安装非本地化键盘驱动程序，反之亦然。

CHotKeyCtrl::GetKeyName

调用此成员函数以获取分配给指定虚拟键代码的键的本地化名称。

static CString GetKeyName(
    UINT vk,
    BOOL fExtended);

参数

vk
虚拟键代码。

fExtended
如果虚拟键代码是扩展密钥，则为 TRUE；否则为 FALSE。

返回值

vk 参数指定的键的本地化名称。如果该键没有映射的名称，则 GetKeyName 返回空字符串。

注解

此函数返回的键名称来自键盘驱动程序，因此可以在本地化版本的 Windows 中安装非本地化键盘驱动程序，反之亦然。

示例

CString str;
str = CHotKeyCtrl::GetKeyName(VK_CONTROL, FALSE);
// str is now "Ctrl", or the localized equivalent.

CHotKeyCtrl::SetHotKey

设置热键控件的键盘快捷方式。

void SetHotKey(
    WORD wVirtualKeyCode,
    WORD wModifiers);

参数

wVirtualKeyCode
[in] 键盘快捷方式的虚拟键代码。有关标准虚拟键代码的列表，请参见 Winuser.h。

wModifiers
[in] 指示键盘快捷方式中的修饰键的标志的按位组合 (OR)。

修饰符标志如下所示：

标记	相应的键
HOTKEYF_ALT	Alt 键
HOTKEYF_CONTROL	CTRL 键
HOTKEYF_EXT	扩展键
HOTKEYF_SHIFT	SHIFT 键

注解

虚拟键代码和修饰键一起定义键盘快捷方式。

CHotKeyCtrl::SetRules

调用此函数以定义热键控件的无效组合和默认修饰符组合。

void SetRules(
    WORD wInvalidComb,
    WORD wModifiers);

参数

wInvalidComb
指定无效键组合的标志的数组。它可以是以下值的组合：

HKCOMB_A ALT
HKCOMB_C CTRL
HKCOMB_CA CTRL+ALT
HKCOMB_NONE 未修改的键
HKCOMB_S SHIFT
HKCOMB_SA SHIFT+ALT
HKCOMB_SC SHIFT+CTRL
HKCOMB_SCA SHIFT+CTRL+ALT

wModifiers
指定当用户输入无效组合时要使用的键组合的标志的数组。有关修饰符标志的详细信息，请参阅 GetHotKey。

备注

当用户输入无效的键组合（由 wInvalidComb 中指定的标志定义）时，系统使用 OR 运算符将用户输入的键与 wModifiers 中指定的标志组合在一起。生成的键组合转换为字符串，然后在热键控件中显示。

另请参阅

CWnd 类
 层次结构图

通过