InputHook() [v1.1.31+]

创建一个对象, 该对象可用于收集或拦截键盘输入.

InputHook := InputHook(Options, EndKeys, MatchList)

参数

Options

由零个或多个下列字母组成的字符串(可任意顺序, 中间可选空格):

B: 设置 BackspaceIsUndo 为 false, 这会导致 Backspace 被忽略.

C: 设置 CaseSensitive 为 true, 使 MatchList 区分大小写.

I: 设置 MinSendLevel 为 1 或给定值, 使任何输入级别低于该值的输入被忽略. 例如, I2 将忽略级别为 0(默认值) 或 1 的任何输入, 但将捕获级别为 2 的输入.

L: 长度限制(例如 L5). 输入的最大允许长度. 当文本达到这个长度时, 输入被终止, EndReason 被设置为单词 Max(除非文本匹配 MatchList 中的一个短语, 在这种情况下 EndReason 被设置为单词 Match). 如果未指定, 则长度限制为 1023.

指定 L0 禁用文本的收集和长度限制, 但并不影响按键生成的文本的统计(请参阅 VisibleText). 这可以与 OnChar, OnKeyDown, KeyOpt 或 EndKeys 组合使用.

M: 将修饰键击对应于真正的 ASCII 字符, 识别并转录修饰键击(如 Ctrl+A 到 Ctrl+Z). 参考这个例子, 它识别 Ctrl+C:

CtrlC := Chr(3) ; 将 Ctrl-C 对应的字符存储在 CtrlC 变量中.
ih := InputHook("L1 M")
ih.Start()
ih.Wait()
if (ih.Input = CtrlC)
    MsgBox, You pressed Control-C.

注意: 字符 Ctrl+A 到 Ctrl+Z 对应于 Chr(1) 到 Chr(26). 此外, M 选项可能会导致某些键盘快捷键(如 Ctrl+←) 在输入正在进行时出现异常.

T: 设置 Timeout(例如 T3 或 T2.5).

V: 设置 VisibleText 和 VisibleNonText 为真(true). 通常, 用户的输入会被阻止(对系统隐藏). 使用此选项可将用户的击键发送到活动窗口.

*: 通配符. 设置 FindAnywhere 为 true, 允许在用户键入的任何位置找到匹配项.

E: 按字符代码而不是键码处理单字符结束键. 如果活动窗口的键盘布局与脚本的键盘布局不同, 则可以提供更一致的结果. 它还可以防止实际上不会产生给定结束字符的键组合结束输入; 例如, 如果 @ 是结束键, 则在美式键盘中 Shift+2 将触发它, 但 Ctrl+Shift+2 不会触发(在使用 E 选项时). 如果还使用 C 选项, 则结束字符区分大小写.

EndKeys

一个由零个或多个按键组成的列表, 其中任何一个键在按下时终止输入(结束键本身不会写入输入缓冲). 当 Input 以这种方式终止时, EndReason 设置为单词 EndKey, EndKey 属性设置为键的名称.

EndKeys 列表使用类似于 Send 命令的格式. 例如, 指定 {Enter}.{Esc} 将使 Enter, . 或 Esc 任一一个都能终止输入. 使用大括号本身作为结束键, 指定 {{} 和/或 {}}.

要使用 Ctrl, Alt 或 Shift 作为结束键, 请指定键的左和/或右的版本, 而不是中性版本. 例如, 指定 {LControl}{RControl} 而不是 {Control}.

尽管不支持诸如 Alt+C(!c) 这样的修饰键, 而非-字母数字字符(如 ?!:@&{}) 默认情况下需要 Shift 按键按下与否, 取决于字符的正常输入方式. 如果有 E 选项, 则将单个字符键名解释为字符, 在这种情况下, 修饰符键必须处于正确的状态才能生成该字符. 当同时使用 E 和 M 选项时, 通过在 EndKeys 中包括相应的 ASCII 控制字符来支持 Ctrl+A 到 Ctrl+Z.

还可以指定明确的虚拟按键代码, 例如 {vkFF} 或 {sc001}. 这在键没有名称且按下时不产生可见字符的罕见情况下非常有用. 它的虚拟键码可以通过按键列表页面底部的步骤来确定.

MatchList

以逗号分隔的关键词列表, 其中任何一个都将导致终止输入(在这种情况下, EndReason 将被设置为单词 Match). 用户输入的内容必须完全匹配匹配列表中的某个词组(除非有 * 选项). 此外, 分隔符逗号周围的任何空格或制表符都是有意义的, 这意味着它们是匹配字符串的一部分. 例如, 如果 MatchList 为 ABC , XYZ, 则用户必须在 ABC 之后或 XYZ 之前键入空格以形成匹配.

两个连续的逗号产生单个原义逗号. 例如, 后面的匹配列表会在 string1 的末尾产生单个原义逗号: string1,,,string2. 类似的, 后面的匹配列表仅包含其中有一个原义逗号的单个项目: single,,item.

因为 MatchList 中的项目不被视为单独的参数, 所以列表可以完全包含在一个变量中. 事实上, 如果此列表的长度超过 16383, 那么列表的全部或部分必须包含在变量中, 因为这个长度是任何脚本行的最大长度. 例如, MatchList 可能由 %List1%,%List2%,%List3% 组成 -- 其中每个变量都包含匹配词组的子列表.

Input 堆栈

任何数量的 InputHook 对象都可以在任何时候创建和进行, 但是它们启动的顺序会影响 Input 的收集方式.

当每个 Input 开始时(通过 Start 方法或 Input 命令), 它被推到堆栈的顶部, 只有当输入终止时才从堆栈中删除. 键盘事件按最近开始到最早的顺序传递给每个输入. 如果一个输入抑制了一个给定的键盘事件, 那么它就不会再向下传递.

如果击键的发送级别低于 InputHook 的 MinSendLevel, 则忽略 Send 的击键. 在这种情况下, 击键仍然可以由堆栈中较低的输入来处理.

多个 InputHook 都可以与 MinSendLevel 一起使用, 以分别收集发送的击键和实际击键.

调用 Input 命令将终止任何由先前的 Input 命令启动的输入, 但保留任何活动的 InputHook. 如果输入 visible(不可见), 它中断的任何 InputHook 通常不会收集任何输入, 直到 Input 命令返回.

InputHook 对象

InputHook 函数返回一个 InputHook 对象, 该对象具有以下方法和属性.

方法:

• KeyOpt: 设置按键或按键列表的选项.
• Start: 启动收集输入.
• Stop: 终止 Input 并将 EndReason 设置为单词 Stopped.
• Wait: 等待, 直到输入终止(InProgress 为 false).

常规属性:

• EndKey: 返回按下终止输入的结束键的名称.
• EndMods: 返回在 Input 终止时逻辑上是按下的修饰符的字符串.
• EndReason: 返回 EndReason 字符串, 该字符串表明了 Input 是如何终止的.
• InProgress: 如果输入正在进行, 则返回 true, 否则返回 false.
• Input: 返回自上次 Input 启动以来收集的任何文本.
• Match: 返回导致 Input 终止的 MatchList 项目.
• OnEnd: 检索或设置在 Input 终止时调用的函数对象.
• OnChar: 检索或设置函数对象, 该函数对象将在字符添加到输入缓冲后调用.
• OnKeyDown: 检索或设置函数对象, 该函数对象将在按下启用通知的按键时调用.
• OnKeyUp: 检索或设置函数对象, 该函数对象将在启用通知按键释放时被调用.

选项属性:

• BackspaceIsUndo: 控制 Backspace 是否从输入缓冲的末尾删除最近按下的字符.
• CaseSensitive: 控制 MatchList 是否区分大小写.
• FindAnywhere: 控制每个匹配项是否可以是输入文本的子字符串.
• MinSendLevel: 检索或设置要收集的输入的最小发送级别.
• NotifyNonText: 控制当按下非文本键时是否调用 OnKeyDown 和 OnKeyUp 回调.
• Timeout: 检索或设置超时值(以秒为单位).
• VisibleNonText: 控制不产生文本的键或键组合是否可见(不阻塞).
• VisibleText: 控制产生文本的键或键组合是否可见(不阻塞).

InputHook.KeyOpt(Keys, KeyOptions)

InputHook.Start()

InputHook.Wait(MaxTime)

InputHook.Stop()

KeyName := InputHook.EndKey

Mods := InputHook.EndMods

<^>^<!>!<+>+<#>#

Mods := RegExReplace(Mods, "[<>](.)(?:>\1)?", "$1")

Reason := InputHook.EndReason

Boolean := InputHook.InProgress

String := InputHook.Input

String := InputHook.Match

MyFunc := InputHook.OnEnd

InputHook.OnEnd := MyFunc

MyFunc := InputHook.OnChar

InputHook.OnChar := MyFunc

MyFunc := InputHook.OnKeyDown

InputHook.OnKeyDown := MyFunc

MyFunc := InputHook.OnKeyUp

InputHook.OnKeyUp := MyFunc

Boolean := InputHook.BackspaceIsUndo

InputHook.BackspaceIsUndo := Boolean

Boolean := InputHook.CaseSensitive

InputHook.CaseSensitive := Boolean

Boolean := InputHook.FindAnywhere

InputHook.FindAnywhere := Boolean

Level := InputHook.MinSendLevel

InputHook.MinSendLevel := Level

Boolean := InputHook.NotifyNonText

InputHook.NotifyNonText := Boolean

Seconds := InputHook.Timeout

InputHook.Timeout := Seconds

Boolean := InputHook.VisibleNonText

InputHook.VisibleNonText := Boolean

Boolean := InputHook.VisibleText

InputHook.VisibleText := Boolean

EndReason

EndReason 属性返回以下字符串之一:

备注

必须先调用 Start 方法, 然后才能收集输入.

InputHook 设计为允许脚本的不同部分都能监视输入, 并且冲突最小. 它可以连续操作, 例如观察任意的单词或其他模式. 它还可以临时运行, 例如收集用户输入或临时覆盖特定(或非-特定) 按键而不干扰热键.

当 Input 正在进行时, 键盘热键仍然有效, 但是如果任何必需的修饰符键被抑制, 或者如果热键使用 reg 方法并且其后缀键被抑制, 则不能激活热键. 例如, 热键 ^+a:: 可能 会被 InputHook 覆盖, 而热键 $^+a:: 会优先, 除非 InputHook 抑制 Ctrl 或 Shift.

按键抑制(阻止) 与否取决于以下因素(按顺序):

• 如果 V 选项对 VK 或 SC 有效, 则不会抑制.
• 如果 S 选项对 VK 或 SC 有效, 则抑制.
• 如果按键是标准修饰键或 CapsLock, NumLock 或 ScrollLock, 则不会抑制.
• VisibleText 或 VisibleNonText 是否被考虑, 具体取决于按键是否生成文本. 如果该属性为 false, 则抑制按键. 有关将哪些按键计为生成文本的详细信息, 请参阅 VisibleText.

输入正在进行时需要键盘钩子, 但如果在输入终止时, 若不再需要键盘挂钩, 则会自动卸载. 键盘钩子的存在导致脚本暂时变为持久的, 这意味着可能需要 ExitApp 来终止它.

AutoHotkey 不支持输入法编辑器(IME). 键盘钩子拦截键盘事件, 并通过使用 ToUnicodeEx 或 ToAsciiEx 将它们转换为文本(VK_PACKET 事件除外, 它封装了单个字符).

如果您使用多种语言或键盘布局, 则 Input 会使用活动窗口的键盘布局而不是脚本的(不论 Input 是否可见).

尽管不够灵活, 但热字串更容易使用.

InputHook vs. Input

InputHook 和 Input 命令是用于相同底层功能的两个不同接口. 以下内容大致相同:

Input, OutputVar, %Options%, %EndKeys%, %MatchList%

ih := InputHook(Options, EndKeys, MatchList)
ih.Start()
ErrorLevel := ih.Wait()
if (ErrorLevel = "EndKey")
    ErrorLevel .= ":" ih.EndKey
OutputVar := ih.Input

Input 命令终止任何先前由它启动的 Input, 而 InputHook 允许同时多个 Input.

Options 解释相同, 但默认设置不同:

• Input 命令将输入的长度限制为 16383, 而 InputHook 将其限制为 1023. 这可以使用 L 选项来改写, 并且没有绝对最大值.
• 默认情况下, Input 命令会阻止文本和非文本击键, 如果使用 V 选项, 则不会阻止. 相比之下, InputHook 默认只阻止文本击键(VisibleNonText 默认为 true), 因此大多数热键可以在输入正在进行时使用.

Input 命令在进行时会阻塞线程, 而 InputHook 允许线程继续, 甚至退出(这允许中断的任何线程继续运行). 脚本可以注册一个 OnEnd 函数, 当输入终止时调用该函数, 而不是等待.

Input 命令只在输入终止后返回用户的输入, 而 InputHook 的 Input 属性允许在任何时候检索它. 脚本可以注册一个 OnChar 函数, 以便在字符增加时调用, 而不是不断地检查 Input 属性.

InputHook 通过 KeyOpt 方法对单个按键提供了更多控制. 这包括添加或删除结束键, 抑制或不抑制特定键, 或忽略特定键生成的文本.

与 Input 命令不同, InputHook 可用于检测不产生文本的键, 而 不 终止输入. 这是通过注册 OnKeyDown 函数和使用 KeyOpt 或 NotifyNonText 来指定相关键来完成的.

如果 MatchList 中的项目导致 Input 终止, 可以参考 Match 属性来确定到底是哪个匹配(当 * 选项存在时这更有用).

尽管脚本可以在输入命令返回后查询 GetKeyState(), 但有时它无法准确反映输入终止时按下了哪些键. InputHook 的 EndMods 属性反映了 Input 终止时修饰键的逻辑状态.

在向后兼容性方面有一些不同之处:

• Input 命令以大写存储结束键 A-Z, 即使某些键盘布局中的一些字母是小写的. 将值传递给 Send 会产生 Shift 的击键, 而不是普通的击键. 相比之下, InputHook 的 EndKeys 属性始终返回规范化的名称; 即按下该键而不按住 Shift 或其他修饰键时产生的字符.

• 如果 EndKeys 中使用的键的名称对应于两个物理键共享 VK(如 NumpadUp 和 Up), 则 Input 命令通过 VK 处理主键通过 SC 处理次要键, 而 InputHook 都通过 SC 来处理. {vkNN} 表示可以通过 VK 来处理按键.

  当结束键由 VK 处理时, 两个物理键都可以终止输入. 例如, {NumpadUp} 将导致通过按下 Up 终止 Input 命令, 但是 ErrorLevel 将包含 EndKey:NumpadUp, 因为只考虑 VK.

  当结束键由 SC 处理时, Input 命令将始终为任何给定 VK 的已知辅助 SC 生成名称, 并始终为任何其他键生成 scNNN. 与之相比, InputHook 产生按键名(如果有).

相关

Input, KeyWait, 热字串, InputBox, #InstallKeybdHook, 线程, if var in/contains MatchList

示例

MsgBox % KeyWaitAny()

; 再来一遍, 但不阻止按键.
MsgBox % KeyWaitAny("V")

KeyWaitAny(Options:="")
{
    ih := InputHook(Options)
    if !InStr(Options, "V")
        ih.VisibleNonText := false
    ih.KeyOpt("{All}", "E")  ; 结束
    ih.Start()
    ErrorLevel := ih.Wait()  ; 将 EndReason 存储在 ErrorLevel 中
    return ih.EndKey  ; 返回按键名称
}

MsgBox % KeyWaitCombo()

KeyWaitCombo(Options:="")
{
    ih := InputHook(Options)
    if !InStr(Options, "V")
        ih.VisibleNonText := false
    ih.KeyOpt("{All}", "E")  ; 结束
    ; Exclude the modifiers
    ih.KeyOpt("{LCtrl}{RCtrl}{LAlt}{RAlt}{LShift}{RShift}{LWin}{RWin}", "-E")
    ih.Start()
    ErrorLevel := ih.Wait()  ; 将 EndReason 存储在 ErrorLevel 中
    return ih.EndMods . ih.EndKey  ; 返回字符串, 如 <^<+Esc
}

global WordList := "Monday`nTuesday`nWednesday`nThursday`nFriday`nSaturday`nSunday"

global Suffix := "", SacHook

SacHook := InputHook("V", "{Esc}")
SacHook.OnChar := Func("SacChar")
SacHook.OnKeyDown := Func("SacKeyDown")
SacHook.OnEnd := Func("SacEnd")
SacHook.KeyOpt("{Backspace}", "N")
SacHook.Start()

SacChar(ih, char)  ; 当一个字符被添加到 SacHook.Input 时调用.
{
    Suffix := ""
    if RegExMatch(ih.Input, "`nm)\w+$", prefix)
        RegExMatch(WordList, "`nmi)^" prefix "\K.*", Suffix)
    
    ToolTip % Suffix, % A_CaretX + 15, % A_CaretY    
    
    ; 只在显示工具提示时拦截 Tab 键.
    ih.KeyOpt("{Tab}", Suffix = "" ? "-NS" : "+NS")
}

SacKeyDown(ih, vk, sc)
{
    if (vk = 8) ; 退格键
        SacChar(ih, "")
    else if (vk = 9) ; Tab 键
        Send % "{Text}" Suffix
}

SacEnd()
{
    ExitApp
}