Differences

This shows you the differences between two versions of the page.

--- manual:Tokens [2016/06/27 02:43]
peternlewis created
+++ manual:Tokens [2019/08/25 17:00]
JMichaelTX Major rewrite with examples and images
@@ Line 1: / Line 1: @@
 ====== Tokens ======
-Tokens allow you to add textual information to [[/Text_Fields|token text fields]].  You can insert tokens into a field using the Insert Token popup near the field or by choosing [[Menus#Edit_Insert_Token|Insert Token]] from the [[Menus#Edit|Edit menu]].  You can also start typing a token and use type completion to complete the token.
+**Keyboard Maestro provides two means to get information about objects (like web pages and windows) in the user's environment:**
-The available tokens are listed on the [[/Tokens|wiki Tokens page]].
+. [[:Tokens|Tokens]] (returns text, used in [[/Text_Fields|text fields]])
+. [[:Functions|Functions]] (returns numbers, used in numeric fields )
-Text token fields also process %NN% or %NNNN% as arbitrary hex unicode characters (eg %41% is an A), and (except for regular expression fields) process backslashed characters \a,\b,\e,\f,\t,\r,\n (bell,backspace,escape,form feed,tab,return,line feed).
+You can enter a Token in any [[/Text_Fields|text field]] in an [[:Actions|Action]], and when the Macro is triggered and the Action is executed, the token will be replaced by the value that is returned at run time.
+===== Token Format =====
+Tokens are identified by a pair of percent `%` symbols at the start and end of the Token name.
+^ Usage ^ Format ^ Example ^ Token\\ Results ^
+| No Parameter | `%TokenName%` | Safari open to this web page:\\ [[https://wiki.keyboardmaestro.com/Home_Page]] | [[token:FrontBrowserTitle|%FrontBrowserTitle%]] returns:\\ "Home Page [Keyboard Maestro Wiki]" |
+| With Parameter | `%TokenName%Parameter%` | Frontmost Window Size | [[token:WindowSize|%WindowSize%1%]] returns:\\ "1991,1417" |
+===== Entering Tokens into Actions =====
+The available tokens, and their definitions, are listed on the [[/Tokens|Token List page]].
+When you are editing a Macro, put the text cursor in a text field, and do one of the following to select and insert a Token into the text field.
+. Press ⌘⌃T (or use the Menu) to display a prompt to select the Token by Name
+. GoTo menu [[Menus#Insert_Token|Edit ➤ Insert Token menu]]
+. Click on the "Insert Token" popup at the top right of the text fields to see the same menu as in #2.
+. Of course, you can always just type the Token.
+You can tell that a text field accepts tokens because a small BUTTON{{{T}}} shows in the field while editing it.
+===== Examples =====
+Let's look at a real-world example.  Let's say you would like to set the Clipboard to a [[https://www.markdownguide.org/basic-syntax/#links | Markdown Link]] of the current web page you are reading.  All you need to do is insert these two tokens (using the Markdown format) in a [[action:Set_Clipboard_to_Text|Set Clipboard]] Action:
+. `%FrontBrowserTitle%`
+. `%FrontBrowserURL%`
+{{:manual:token-example-set-clipboard.png?nolink|}}
+The "`[]()`" are just characters you type.
+That's all you need for a great macro, which you can download from here.
+===== Processing =====
+The Tokens are processed, that is replaced by their value at run time, when the Macro is run, and the Action containing the Token is executed.
+In most text fields, you can control how Tokens are processed using the Gear BUTTON{{{⚙}}} popup menu:
+* Process tokens normally, or
+* Just tokens (not backslashed characters) or
+* Do not process any text.
+If you want to use the percent `%` character as a normal character, simply double the percent (`%%`). \\
+To use a backslash `\` in your text, double the backslash (`\\`).
+===== Other Uses for Tokens =====
+=== Non-Printing Control Characters ===
+An exception to the rule of enclosing Tokens in percent `%` characters, is the use of these Non-Printing Control Characters:\\
+`\a,\b,\e,\f,\t,\r,\n` \\
+which correspond to (bell,backspace,escape,form feed,tab,return,line feed).\\
+These will be replaced with their value in text fields, except for Regular Expression (RegEx) fields.
+=== Convert Hex to Unicode Characters ===
+Text token fields also process %NN% or %NNNN% or %NNNNNN% as arbitrary hex unicode characters (eg %41% is an A, %01F300% is 🌀), and (except for regular expression fields) .
+=== Using Special Characters as Plain Text ===
 To include a percent in your text, simply double the percent (%%). To include a backslash \ in your text, double the backslash (\\).
+===== Text Case Conversions =====
+Text fields also support (v9.0+) text case conversion using the below meta characters. You may use these in both standard Text Fields and in the Replace field of a [[action:Search_and_Replace|Search and Replace by regular expression]] action (even though these meta characters are _not_ supported by ICS Regular Expressions).
+The Available Case Conversion Meta Characters are:
+* `\U` converts everything up to the next `\L` or `\E` to uppercase.
+* `\L` converts everything up to the next `\U` or `\E` to lowercase.
+* `\u` converts the next character to uppercase.
+* `\l` converts the next character to lowercase.
+* `\U\l` lowercase first, then uppercase.
+* `\L\u` uppercase first, then lowercase.
+* `\E` stop changing case.
+You should not use `\u` after `\U` or `\l` after `\L` unless you terminate the sequence with `\E` first.
+==== Access to an Item in Token Results ====
+With tokens that return a list of information (comma separated by default), you can access the individual items using the Variable array notation, append the item number in square brackets `[ ]` to the Token name, just before the closing `%`.
+For example:\\
+Token for Window Frame, [[token:WindowFrame | %WindowFrame[3]%1%]], will be the third comma-separated value, which is the Window width in this case.
+* %WindowFrame%1% returns "3606,23,1514,1417"
+* %WindowFrame[3]%1% returns "1514"
+These tokens allow this indexing:
+* [[token:TriggerValue|TriggerValue]]
+* [[token:WindowFrame|FrontWindow*]]
+* [[token:WindowFrame|Window*]]
+* [[token:Screen|Screen*]]
+* [[token:SystemClipboard|SystemClipboard]]
+* [[token:PastClipboard|PastClipboard]]
+* [[token:NamedClipboard|NamedClipboard]]
+* [[token:TriggerClipboard|TriggerClipboard]]
+* [[token:CurrentMouse|CurrentMouse]]
+* [[token:FoundImage|FoundImage]]

Keyboard Maestro Wiki

User Tools

Site Tools

Differences

Page Tools