热键控件 (SHotKeyCtrl)¶

热键控件是一个用于捕获和显示键盘快捷键组合的专用控件。它允许用户通过按键来设置快捷键，并提供了相应的显示和处理功能。

基本信息¶

类名：SHotKeyCtrl
控件标签：hotkey
基类：SWindow
功能：捕获和显示键盘快捷键组合

属性说明¶

SHotKeyCtrl 标签为 hotkey，继承自 SComboBase（TWindowProxy），用于录入快捷键组合。

自身属性¶

属性名	类型	默认值	说明
hotKey	string	-	初始快捷键，格式同 `ctrl+s` / `alt+shift+a`，由 `OnAttrHotKey` 解析
invalidComb	string	-	禁止的组合键（如 `ctrl+a`），多个用 `,` 分隔
invalidSysKey	string	-	禁止的系统键
invalidModifier	string	-	禁止的修饰键

text、字体、颜色、可用、可见等通用属性见通用属性。

使用示例¶

基本热键控件¶

<hotkey name="hkBasic" 
        pos="10,10,200,35" 
        invalidComb="Ctrl+Alt+Del"/>

带默认值的热键控件¶

<hotkey name="hkDefault" 
        pos="10,45,200,70" 
        hotKey="CTRL+ALT+A"
        colorText="#333333"/>

自定义无效组合的热键控件¶

<hotkey name="hkCustom" 
        pos="10,80,200,105" 
        invalidComb="Ctrl+Alt+Del,Ctrl+Esc"
        invalidModifier="Shift"
        font="bold:1,size:14"
        align="center"/>

事件处理¶

热键控件支持以下事件：

事件名	EventID	说明
EVT_HOTKEY_CHANGED	EventHotKeyChanged::EventID	热键改变事件

// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_NAME_HANDLER(L"hkBasic", EventHotKeyChanged::EventID, OnHotKeyChanged)
EVENT_MAP_END()

void OnHotKeyChanged(IEvtArgs *pEvt)
{
    EventHotKeyChanged *pRealEvt = sobj_cast<EventHotKeyChanged>(pEvt);
    WORD wVK = pRealEvt->wVK;
    WORD wMod = pRealEvt->wMod;
    // 处理热键改变事件
}

代码操作¶

// 查找热键控件
SHotKeyCtrl *pHotKey = FindChildByName2<SHotKeyCtrl>(L"hkBasic");

// 设置热键
pHotKey->SetHotKey(VK_F1, HOTKEYF_CONTROL);

// 获取热键
WORD wVK, wMod;
pHotKey->GetHotKey(wVK, wMod);

// 设置无效组合
pHotKey->SetAttribute(L"invalidComb", L"Ctrl+Alt+Del");

// 设置默认热键
pHotKey->SetAttribute(L"hotKey", L"CTRL+SHIFT+T");

最佳实践¶

有效性检查：通过 invalidComb 和 invalidModifier 属性限制无效的热键组合
默认值设置：使用 hotKey 属性设置合理的默认热键
用户提示：提供清晰的说明帮助用户理解如何设置热键

常见问题¶

Q: 热键不生效怎么办？¶

A: 检查是否设置了有效的热键组合，并正确处理 EVT_HOTKEY_CHANGED 事件。

Q: 如何限制特定的无效组合？¶

A: 使用 invalidComb 属性设置不允许的热键组合。

Q: 如何设置默认热键？¶

A: 通过 hotKey 属性或 SetHotKey 方法设置默认值。