Both Hotkey Modifiers and Special Characters Might Disappear When Used in Regular Text. Usually, You’ll Find the Raw Mode the Easiest Solution for Vanishing Characters. Plus, a Secret AutoHotkey Hotstring Trick!

*          *          *

When I started working on this blog I thought I would hammer out a simple explanation of when to use the Raw option in AutoHotkey…and to a large degree I do that. However, in the course of testing both the Raw option and the backtick Escape Character, I discovered a secret undocumented feature of Hotstrings. In some special cases, it may come in handy for changing Hotstrings on-the-fly.

*          *          *

I probably should have noticed it sooner, but in previous debugging every time I launched an Instant Hotkey, I inserted fairly banal replacement text.  Until my recent testing, I hadn’t used any special characters or Hotkey modifiers. However, when I added:

This is a test of CTRL+ALT+O!

as the insertion text for a new Hotkey, the SendInput command returned:

This is a test of CTRLALTO

I lost the plus  (+) signs and the exclamation point (!).

I immediately understood what had happened. After all, I’d run into this problem many times before. Even though it only requires a relatively simple fix, I decided to write about the topic.

Finding Lost Characters

We readily recognize the Hotkey modifier symbols (e.g. ^!+#{}). How AutoHotkey reacts to these characters depends upon where you use them in a script. The Send command automatically interprets each as an active modifier. That means they don’t appear when used in conjunction with the AutoHotkey Send command (as shown in the second line above).

I saw the identical effect when I inserted the text into a Hotstring:

::test::This is a test of CTRL+ALT+O!

When activated, the replacement result removed the plus signs and exclamation point in the same manner as the Send command. AutoHotkey interprets any Hotkey modifying character (e.g. !+^#{}) as part of a Hotkey combination or a special character (e.g. {Enter}) which it drops from the result.  To prevent these special characters from vanishing, we must convert the string to plain text using the Raw option.

Two Types of Special Characters

In AutoHotkey, you’ll find two types of special characters: 1) symbols with inherent magical properties and 2) characters which you can imbue with magical properties using the accent/backtick (`).

The first type of special symbols include the Hotkey modifiers (e.g. ^!+#), the percent sign (%) used for variable substitution and forced expressions, the semicolon (;) which marks the beginning of a comment on a single line, curly brackets ({ }) for sending special keys, the backtick (`) Escape Character for adding and removing magical powers, and quotation marks (“”). You’ll find a few more (e.g. the tilde ~) plus conditional expression operators but they usually only take on magical powers in specific situations (e.g. ~ Hotkey modify)—and not normally the source of text output problems. In many cases, you can change an imbued symbol to plain text by preceding it with the backtick (Escape Character), but this also depends upon the situation. You’ll need to test to make sure.

The second form of special character takes on it magical power when preceded by the backtick Escape Character. These include (from the online AutoHotkey documentation):

`n	newline (linefeed/LF)
`r	carriage return (CR)
`b	backspace
`t	tab (the more typical horizontal variety)
`v	vertical tab — corresponds to Ascii value 11. It can also be manifest in some applications by typing Control+K.
`a	alert (bell) — corresponds to Ascii value 7. It can also be manifest in some applications by typing Control+G.
`f	formfeed — corresponds to Ascii value 12. It can also be manifest in some applications by typing Control+L.

For example, in situations where you may need a new line, such as in this MsgBox command:

MsgBox Beware!`rMad Dog!

the escaped character`r forces a new line. At other times, such as in a menu item name, you’ll find it has no effect. In still other instances, the outcome appears situational. For example, in a regular Hotstring, a semicolon displays in the text only when preceded by a string but not when preceded by a space or tab `t. (AutoHotkey treats the separated semicolon as a comment flag.) If you want the semicolon to appear, place the backtick in front of it (`;).

You can easily get bogged down in the differences between all the special characters and what they do when. Rather than attempting to enumerate all the various ways to manipulate them, I offer a general approach to resolving plain text issues. Remember, the online command reference does a pretty good job of outlining the handling of variations in special symbols while writing a script.

How to Resolve Strange Symbol-Losing Behavior

If falling victim to disappearing characters, take these two steps:

1. Check if the Raw option will translate all data into plain text (available for Send command and Hotstrings).
2. If the Raw option either doesn’t solve the problem or doesn’t exist for the situation, look for an Escape Character to solve the problem.

How to Produce Plain Text with the Raw Option

The primary method for cleaning up special character laced text involves translating each symbol to its raw form. This works with both the Send command and Hotstrings. When AutoHotkey encounters the raw option, it ignores special characters and sends only plain text. In the Send command, you can either use SendRaw or Send, {raw}… to translate the data.

I corrected the InstantHotkey.ahk script (and its variations) as follows:

For InstantHotkey.ahk:

SendRaw, %TextInsert%

For InstantHotkeyTwoDeep.ahk:

SendRaw, % %IH_VarText% ; Send two-deep variable value

For InstantHotkeyLoop.ahk:

SendRaw, % IH_HotkeyText%A_Index%

For InstantHotkeyArrays.ahk:

; The Hotkey text insertion subroutine now uses 
; InstantHotkey[] array to insert the text using
; the recently pressed Hotkey (A_ThisHotkey) as the array key.

TextAdd:
  SendInput, % "{raw}" . InstantHotkey[A_ThisHotkey]
Return

Tip: Using the {raw} in place of SendRaw allows you to start the plain text conversion at any point in the string, as well as, in Hotstrings:

:*:test::{Volume_Mute} volume off and paste the modifiers {raw}^!#+

This Hotstring first turns off the speaker volume, then inserts text displaying Hotkey modifiers as plain text characters.

Sending Raw Data with a Hotstring

When it comes to special characters, Hotstrings act in a similar manner to the Send command. AutoHotkey treats all the Hotkey modifiers and terms within curly brackets (e.g. {tab}, {up}) as active elements and interprets them upon execution. To prevent this and send plain text, add the r option to the Hotstring:

:r:test::This is a test of CTRL+ALT+O!

All the text now appears as plain characters, except for Escape Sequences and the backtick. Also, any special strings such as {Enter} and {Space} will appear as “{Enter}” and “{Space}” rather than a new line or the space character.

While investigating this Hotstring behavior I came across an AutoHotkey secret which I offer at the end of this blog.

When the Raw Option Doesn’t Work

Depending upon whether your problem code uses the Send command or a Hotstring (or another command), AutoHotkey may need more help to recover missing (or misbehaving) characters. In those situations, you can often solve the problem with the backtick which converts the special character to plain text.

For example, in most AutoHotkey commands, the percent sign (%) acts as the force an expression operator while the double percent signs enclosing a variable (%var%) substitutes a value. The Send command always attempts to evaluate the % operator(s) even in Raw mode—often generating an error. To display the percent sign place the backtick in front of it (`%). Since the percent operator (%) doesn’t work in a Hotstring, it always appears as a mere character—not needing the backtick.

You’ll find that preceding a special character with the backtick often changes it to plain text—even the backtick needs a backtick in front of it. However, to render the double-quotation mark as a plain text when used as in an expression, precede it with another double-quote. (e.g. “” ⇒ “). (Some programmers get annoyed with this arrangement since many languages use the backslash (\) as the escape character for virtually everything—including a double-quotation mark (\”).)

Again results will vary—depending on what you do and where you do it. I’ve found that a little trial-and-error testing almost always helps to refresh your memory.

An AutoHotkey Hotstring Secret

Note: I call this feature a secret because I didn’t find any documentation directly addressing the topic. (That doesn’t mean the reference doesn’t exist.) I deduced the availability of this interesting effect after I finally understood how Hotstrings work.

By default, the latest version of AutoHotkey Hotstrings uses a stripped down version of the SendInput command to do text replacement. (I say “stripped down” because, unlike the SendInput command, you can’t evaluate expressions or variables in Hotstrings using % or %var%.) That means a Hotstring should interpret Hotkey combinations in the same manner as the SendInput command—and it does! You can directly execute a Hotkey combination with a Hotstring:

::test::^!#l                       ; Launches CTRL+ALT+WIN+L Hotkey

In fact, you can launch multiple Hotkeys with the same Hotstring:

::test::^!#l !#^g                      ; Launches two Hotkeys

I’m not sure, but only the maximum Hotstring length may limit the number of Hotkey activations. Pretty cool, huh?

I used the following to create a changing Hotstring based on the contents of the Windows Clipboard:

:*:test::View clipboard contents "^v" with {raw}^v in this Hotstring!

Since the Hotstring interprets the Windows shortcut CTRL+V (Paste), AutoHotkey inserts the Windows Clipboard contents (if text) into the Hotstring. Then, the {raw} option changes the next ^v into plain text.

I’m not sure if you’ll ever use this obscure AutoHotkey trick, but you never know when it might come in handy.

`