InputHook

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

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

EndKeys

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

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

要使用 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, 则忽略 Sent 的击键. 在这种情况下, 击键仍然可以由堆栈中较低的输入来处理.

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

InputHook 对象

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

方法:

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

常规属性:

• EndKey: 返回终止 Input 而按下的结束建的名称.
• 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.

Input 正在进行时需要键盘钩子, 但当 Input 终止时, 如果不再需要键盘钩子, 则会自动卸载.

Input 正在进行时, 脚本为自动持续运行, 所以即使没有正在运行的线程, 它也会继续监视输入. 当输入结束时, 脚本可能会自动退出(如果没有正在运行的线程, 并且该脚本由于其他原因而不会持续运行).

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

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

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

InputHook vs. Input (v1)

在 AutoHotkey v1.1 中, InputHook 是 Input 命令的替代品, 提供了更大的灵活性. 在 2.0 版本中删除了 Input 命令, 但下面的代码基本相同:

; Input OutputVar, % Options, % EndKeys, % MatchList  ; v1
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 属性来确定到底是哪个匹配(当 * 选项存在时这更有用).

尽管脚本可以在 Input 函数返回后查询 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 产生按键名(如果有).

相关

KeyWait, 热字串, InputBox, InstallKeybdHook, 线程

示例

MsgBox KeyWaitAny()

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

KeyWaitAny(Options:="")
{
    ih := InputHook(Options)
    if !InStr(Options, "V")
        ih.VisibleNonText := false
    ih.KeyOpt("{All}", "E")  ; 结束
    ih.Start()
    ih.Wait()
    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()
    ih.Wait()
    return ih.EndMods . ih.EndKey  ; 返回字符串, 例如 <^<+Esc
}

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

global Suffix := "", SacHook

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

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

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