Hotstring [v1.1.28+]

Creates, modifies, enables, or disables a hotstring while the script is running.

Hotstring(String , Replacement, OnOffToggle)
Hotstring(NewOptions)
OldValue := Hotstring("EndChars" , NewValue)
OldValue := Hotstring("MouseReset" , NewValue)
Hotstring("Reset")

Parameters

String

The hotstring's trigger string, preceded by the usual colons and option characters. For example, "::btw" or ":*:]d".

String may be matched to an existing hotstring by considering case-sensitivity (C), word-sensitivity (?), activation criteria (as set by #If, #IfWin or Hotkey, If) and the trigger string. For example, "::btw" and "::BTW" match unless the case-sensitive mode was enabled as a default, while ":C:btw" and ":C:BTW" never match. The C and ? options may be included in String or set as defaults by the #Hotstring directive or a previous call to this function.

If the hotstring already exists, any options specified in String are put into effect, while all other options are left as is. However, since hotstrings with C or ? are considered distinct from other hotstrings, it is not possible to add or remove these options. Instead, turn off the existing hotstring and create a new one.

When a hotstring is first created -- either by the Hotstring function or a double-colon label in the script -- its trigger string and sequence of option characters becomes the permanent name of that hotstring as reflected by A_ThisHotkey. This name does not change even if the Hotstring function later accesses the hotstring with different option characters.

If the X (execute) option is present in String (not just set as a default), the Replacement parameter is interpreted as a label or function name instead of replacement text. This has no effect if Replacement is an object.

Replacement

The replacement string, or a label, function or function object to call (as a new thread) when the hotstring triggers.

By default, all strings are treated as replacement text. To specify a label or function by name, include the X (execute) option in String. Both normal labels and hotkey/hotstring labels can be used, and the trailing colon(s) should not be included. If a function and a label exist with the same name, the label takes precedence. To use the function instead, pass a function reference.

This parameter can be left blank if the hotstring already exists, in which case its replacement will not be changed. This is useful to change only the hotstring's options, or to turn it on or off.

Note: If this parameter is specified but the hotstring is disabled from a previous use of this function, the hotstring will remain disabled. To prevent this, include the word "On" in OnOffToggle.

OnOffToggle

One of the following strings (enclosed in quote marks if used literally):

On: Enables the hotstring.

Off: Disables the hotstring.

Toggle: Sets the hotstring to the opposite state (enabled or disabled).

[v1.1.30+]: The values 1 (or true), 0 (or false) and -1 may be used in place of On, Off and Toggle, respectively.

Errors

This function throws an exception if the parameters are invalid or a memory allocation fails. It does not affect ErrorLevel.

An exception is also thrown if Replacement is omitted and String is valid but does not match an existing hotstring. This can be utilized to test for the existence of a hotstring. For example:

try
    Hotstring("::btw")
catch
    MsgBox The hotstring does not exist or it has no variant for the current IfWin criteria.

Remarks

The current IfWin setting determines the variant of a hotstring upon which the Hotstring function will operate.

A given label or function can be the target of more than one hotstring. If it is known that a label or function was called by a hotstring, you can determine which hotstring by checking the built-in variable A_ThisHotkey.

If the script is suspended, newly added/enabled hotstrings will also be suspended until the suspension is turned off (unless they are exempt as described in the Suspend section).

The keyboard and/or mouse hooks will be installed or removed if justified by the changes made by this function.

This function cannot directly enable or disable hotstrings in scripts other than its own.

Once a script has at least one hotstring, it becomes persistent, meaning that ExitApp rather than Exit should be used to terminate it. Hotstring scripts are also automatically #SingleInstance unless #SingleInstance Off has been specified.

Variant (Duplicate) Hotstrings

A particular hotstring can be created more than once if each definition has different IfWin criteria, case-sensitivity (C vs. C0/C1), or word-sensitivity (?). These are known as hotstring variants. For example:

Hotkey, IfWinActive, ahk_group CarForums
Hotstring("::btw", "behind the wheel")
Hotkey, IfWinActive, Inter-Office Chat
Hotstring("::btw", "back to work")
Hotkey, IfWinActive
Hotstring("::btw", "by the way")

If more than one variant of a hotstring is eligible to fire, only the one created earliest will fire.

For more information about IfWin, see #IfWin's General Remarks.

EndChars

OldValue := Hotstring("EndChars" , NewValue)

Retrieves or modifies the set of characters used as ending characters by the hotstring recognizer. For example:

prev_chars := Hotstring("EndChars", "-()[]{}':;""/\,.?!`n `t")
MsgBox The previous value was: %prev_chars%

#Hotstring EndChars also affects this setting.

It is currently not possible to specify a different set of end characters for each hotstring.

MouseReset

OldValue := Hotstring("MouseReset" , NewValue)

Retrieves or modifies the global setting which controls whether mouse clicks reset the hotstring recognizer, as described here. NewValue should be 1 (true) to enable mouse click detection and resetting of the hotstring recognizer, or 0 (false) to disable it. The return value is the setting which was in effect before the function was called.

The mouse hook may be installed or removed if justified by the changes made by this function.

#Hotstring NoMouse also affects this setting, and is equivalent to specifying false for NewValue.

Reset [v1.1.28.01+]

Hotstring("Reset")

Immediately resets the hotstring recognizer. In other words, the script will begin waiting for an entirely new hotstring, eliminating from consideration anything you previously typed.

Setting Default Options

Hotstring(NewOptions)

To set new default options for subsequently created hotstrings, pass the options to the Hotstring function without any leading or trailing colon. For example: Hotstring("T").

Turning on case-sensitivity (C) or word-sensitivity (?) also affects which existing hotstrings will be found by any subsequent calls to the Hotstring function. For example, Hotstring(":T:btw") will find ::BTW by default, but not if Hotstring("C") or #Hotstring C is in effect. This can be undone or overridden by passing a mutually-exclusive option; for example, C0 and C1 override C.

Related

Hotstrings, #IfWinActive/Exist, #MaxThreadsPerHotkey, Suspend, Threads, Thread, Critical

Examples

Example #1: Hotstring Helper

The following script might be useful if you are a heavy user of hotstrings. It's based on the script created by Andreas Borutta. By pressing Win+H (or another hotkey of your choice), the currently selected text can be turned into a hotstring. For example, if you have "by the way" selected in a word processor, pressing Win+H will prompt you for its abbreviation (e.g. btw) and then add the new hotstring to the script. The hotstring will be activated without reloading the script.

#h::  ; Win+H hotkey
; Get the text currently selected. The clipboard is used instead of
; "ControlGet Selected" because it works in a greater variety of editors
; (namely word processors).  Save the current clipboard contents to be
; restored later. Although this handles only plain text, it seems better
; than nothing:
ClipboardOld := Clipboard
Clipboard := "" ; Must start off blank for detection to work.
Send ^c
ClipWait 1
if ErrorLevel  ; ClipWait timed out.
    return
; Replace CRLF and/or LF with `n for use in a "send-raw" hotstring:
; The same is done for any other characters that might otherwise
; be a problem in raw mode:
ClipContent := StrReplace(Clipboard, "``", "````")  ; Do this replacement first to avoid interfering with the others below.
ClipContent := StrReplace(ClipContent, "`r`n", "``r")  ; Using `r works better than `n in MS Word, etc.
ClipContent := StrReplace(ClipContent, "`n", "``r")
ClipContent := StrReplace(ClipContent, "`t", "``t")
ClipContent := StrReplace(ClipContent, "`;", "```;")
Clipboard := ClipboardOld  ; Restore previous contents of clipboard.
ShowInputBox(":T:`::" ClipContent)
return

ShowInputBox(DefaultValue)
{
    ; This will move the InputBox's caret to a more friendly position:
    SetTimer, MoveCaret, 10
    ; Show the InputBox, providing the default hotstring:
    InputBox, UserInput, New Hotstring,
    (
    Type your abreviation at the indicated insertion point. You can also edit the replacement text if you wish.

    Example entry: :R:btw`::by the way
    ),,,,,,,, %DefaultValue%
    if ErrorLevel  ; The user pressed Cancel.
        return

    if RegExMatch(UserInput, "O)(?P<Label>:.*?:(?P<Abbreviation>.*?))::(?P<Replacement>.*)", Hotstring)
    {
        if !Hotstring.Abbreviation
            MsgText := "You didn't provide an abbreviation"
        else if !Hotstring.Replacement
            MsgText := "You didn't provide a replacement"
        else
        {
            Hotstring(Hotstring.Label, Hotstring.Replacement)  ; Enable the hotstring now.
            FileAppend, `n%UserInput%, %A_ScriptFullPath%  ; Save the hotstring for later use.
        }
    }
    else
        MsgText := "The hotstring appears to be improperly formatted"

    if MsgText
    {
        MsgBox, 4,, %MsgText%. Would you like to try again?
        IfMsgBox, Yes
            ShowInputBox(DefaultValue)
    }
    return
    
    MoveCaret:
    WinWait, New Hotstring
    ; Otherwise, move the InputBox's insertion point to where the user will type the abbreviation.
    Send {Home}{Right 3}
    SetTimer,, Off
    return
}