Formatting Text for Various AutoHotkey Tools Can Get Tedious—Use AutoHotkey Section Continuation to Simplify the Work

In the MouseMeasure.ahk script (discussed last time), I added a pop-up window displaying instructions on how to use the app. I formatted the text with a number of new lines and tabs. Usually, this would have required careful placement of the special escape characters, but not this time.

When adding instructions to a MsgBox, we often resort to adding returns (`r), newlines (`n), and tabs (`t) to create the desired layout. While this works, it often produces perverse effects—especially when using individual line continuation techniques to wrap the code for display purposes. However, AutoHotkey offers an alternative type of code continuation which makes text formatting quick and easy— continuation sections (Method #2).

Multi-line continuation sections offer a number of advantages over using escape sequences to format text:

  1. Continuation sections maintain the same format as originally entered including all tabs, returns, and spaces—What You See Is What You Get (WYSIWYG).
  2. Continuation sections work either in replacement text or expressions.
  3. Continuation sections allow variable text replacement (%var%).
  4. Continuation sections ignore the effects of special symbols without requiring escaping (i.e. quotation marks, commas, etc).
  5. Continuation sections offer special options for removing extra space, joining lines, trimming text, and more.

Adding Multi-line Text

In the MouseMeasure.ahk script, I assigned a list of text instructions to a variable using this section continuation technique, then displayed the text in a MsgBox—no need to use returns (`r) or tabs (`t). To do the same thing using those escape characters would require at least 14 returns (`r) and six tabs (`t). Even then, the command code would either appear as one long line or, if using the individual line continuation (Method #1), likely leave an extra space (or two) before each punctuation mark.

Assign Multiple Lines of Text to a Variable

The following snipped assigns a formatted piece of text to a variable creating a WYSIWYG multi-line text entry: 

Help = ( To Calibrate Range:  	1. Cursor at start point — CTRL+LButton and hold. 	2. Drag to end of scale and release. 	3. Enter length of scale and units i.e. 10 miles.  Manual Calibration: CTRL+ALT+Z  To Measure Distance: 	1. Cursor at start point — SHIFT+LButton and hold. 	2. Drag to end of measurement and release. 	3. Distance displayed and saved to Clipboard.  CTRL+ALT+F12 for this Help Message. ) MsgBox, 0, MouseMeasure Help, % Help

The MsgBox command displays the contents of the variable Help exactly as originally typed.

Note: You can also use the := type of variable assignment, but you must enclose the section in quotes:

Help := " ( . . Multiline Text . . )"

… although to display a single double-quote mark (") and prevent runtime errors, you must now escape any quotation marks in the text with a preceding quote ("").

Using Multi-line Continuation in Commands

ToolTip

Any AutoHotkey command which accepts plain text can use the same type of multi-line continuations. For example, in the same MouseMeasure.ahk script, the updating ToolTip command displaying the current pixel distance and the converted unit length (see image) uses the following formatting:

                  ToolTip [%dx%:%dy%]`n%dist% px`n%distCalibrated% %units%

Using section continuation, you can replace the above line with the following WYSIWYG formatted section:

tooltip,   ; comma required ( [%dx%:%dy%] %dist% px %distCalibrated% %units% )

Note: You can include the traditional double-percent-sign text replacement (%var%) inside multi-line continuation sections.

While you can use this technique with any command that uses plain text parameters (or expressions), inserting so many lines in the middle of a command tends to make the code less readable. You may find it easier to read by saving the multi-line text to a variable, then using that variable as either a text substitution (%var%) or forced expression (% var).

Multi-line Section Continuation Options

AutoHotkey offers options when using section continuation. Place the options on the same lines as the open parentheses:

Help = (LTrim Comments To Calibrate Range:   ; Instructions for calibration  	1. Cursor at start point — CTRL+LButton and hold. 	2. Drag to end of scale and release. 	3. Enter length of scale and units i.e. 10 miles.  Manual Calibration: CTRL+ALT+Z  ; Calibration GUI  To Measure Distance:   ; Instruction for measuring distance  	1. Cursor at start point — SHIFT+LButton and hold. 	2. Drag to end of measurement and release. 	3. Distance displayed and saved to Clipboard.  CTRL+ALT+F12 for this Help Message. ) MsgBox, 0, MouseMeasure Help, % Help

Line 2 above includes the options LTrim and Comments. LTrim removes any space or tabs found to the left of the text and Comments prevents the display of the comments appearing on lines 3, 9, and 11 (as shown at right).

Multi-line continuation section options include (from online AutoHotkey documentation):

  • Join: Specifies how lines should be connected together. If this option is omitted, each line except the last will be followed by a linefeed character (`n). If the wordJoin is specified by itself, lines are connected directly to each other without any characters in between. Otherwise, the wordJoin should be followed immediately by as many as 15 characters. For example,Join`s would insert a space after each line except the last ("`s" indicates a literal space — it is a special escape sequence recognized only byJoin). Another example isJoin`r`n, which inserts CR+LF between lines. Similarly,Join| inserts a pipe between lines. To have the final line in the section also ended by a join-string, include a blank line immediately above the section's closing parenthesis.
    Known limitation: If the Join string ends with a colon, it must not be the last option on the line. For example,(Join: is treated as the label "(Join" and(LTrim Join: is unsupported, but(Join: C is okay.
  • LTrim: Omits spaces and tabs at the beginning of each line. This is primarily used to allow the continuation section to be indented. Also, this option may be turned on for multiple continuation sections by specifying#LTrim on a line by itself.#LTrim is positional: it affects all continuation sections physically beneath it. The setting may be turned off via#LTrim Off.
  • RTrim0 (RTrim followed by a zero): Turns off the omission of spaces and tabs from the end of each line.
  • Comments (orComment orCom orC) [v1.0.45.03+]: Allows semicolon comments inside the continuation section (but not/*..*/). Such comments (along with any spaces and tabs to their left) are entirely omitted from the joined result rather than being treated as literal text. Each comment can appear to the right of a line or on a new line by itself.
  • % (percent sign): Treats percent signs as literal rather than as variable references. This avoids the need to escape each percent sign to make it literal. This option is not needed in places where percent signs are already literal, such as auto-replace hotstrings.
  • , (comma): Treats commas as delimiters rather than as literal commas. This rarely-used option is necessary only for the commas between command parameters because in function calls, the type of comma does not matter. Also, this option transforms only those commas that actually delimit parameters. In other words, once the command's final parameter is reached (or there are no parameters), subsequent commas are treated as literal commas regardless of this option.
  • ` (accent): Treats each backtick character literally rather than as an escape character. This also prevents commas and percent signs from being explicitly and individually escaped. In addition, it prevents the translation of any explicitly specified escape sequences such as `r and `t.
  • ) [v1.1.01+]: If a closing parenthesis appears in the continuation section's options (except as a parameter of the Join option), the line is reinterpreted as an expression instead of the beginning of a continuation section. This allows expressions like(x.y)[z]() to work without the need to escape the opening parenthesis.

Click theFollow button at the top of the sidebar on the right of this page for e-mail notification of new blogs. (If you're reading this on a tablet or your phone, then you must scroll all the way to the end of the blog—pass any comments—to find theFollow button.)

jack

This post was proofread by Grammarly
(Any other mistakes are all mine.)

(Full disclosure: If you sign up for a free Grammarly account, I get 20¢. I use the spelling/grammar checking service all the time, but, then again, I write a lot more than most people. I recommend Grammarly because it works and it's free.)

Find my AutoHotkey books at ComputorEdge E-Books!

Find quick-start AutoHotkey classes at "Robotic Desktop Automation with AutoHotkey"!