Hotstring

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

Type: 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 #HotIf or HotIf) 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 the double-colon syntax in the script -- its trigger string and sequence of option characters becomes the permanent name of that hotstring as reflected by 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 function name instead of replacement text. This has no effect if Replacement is an object.

Replacement

Type: String or Object

The replacement string, or a 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 function by name, include the X (execute) option in String. Note that after reassigning the function of a hotstring, its original function can only be restored if it was given a name.

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

Type: String or Integer

One of the following values:

On or 1 (true): Enables the hotstring.

Off or 0 (false): Disables the hotstring.

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

Errors

This function throws an exception if the parameters are invalid or a memory allocation fails.

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 HotIf setting determines the variant of a hotstring upon which the Hotstring function will operate.

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 HotIf criteria, case-sensitivity (C vs. C0/C1), or word-sensitivity (?). These are known as hotstring variants. For example:

HotIfWinActive "ahk_group CarForums"
Hotstring "::btw", "behind the wheel"
HotIfWinActive "Inter-Office Chat"
Hotstring "::btw", "back to work"
HotIfWinActive
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 #HotIf'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

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, #HotIf, A_ThisHotkey, #MaxThreadsPerHotkey, Suspend, Threads, Thread, Critical

Examples

#1: Hotstring Helper. The following script might be useful if you are a heavy user of hotstrings. It's based on the v1 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), add the new hotstring to the script and activate it.

#h::  ; Win+H hotkey
{
    ; Get the text currently selected. The clipboard is used instead of
    ; EditGetSelectedText 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 := A_Clipboard
    A_Clipboard := "" ; Must start off blank for detection to work.
    Send "^c"
    if !ClipWait(1)  ; ClipWait timed out.
    {
        A_Clipboard := ClipboardOld ; Restore previous contents of clipboard before returning.
        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(A_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, "`;", "```;")
    A_Clipboard := ClipboardOld  ; Restore previous contents of clipboard.
    ShowInputBox(":T:`::" ClipContent)
}

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

    Example entry: :T:btw`::by the way
    )", "New Hotstring",, DefaultValue)
    if IB.Result = "Cancel"  ; The user pressed Cancel.
        return

    if RegExMatch(IB.Value, "(?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" IB.Value, A_ScriptFullPath  ; Save the hotstring for later use.
        }
    }
    else
        MsgText := "The hotstring appears to be improperly formatted"

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