User Tools

Site Tools


manual:Tokens

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revision Both sides next revision
manual:Tokens [2017/11/06 01:39]
peternlewis
manual:Tokens [2019/09/17 08:31]
peternlewis [Other Uses for Tokens]
Line 1: Line 1:
 ====== Tokens ====== ====== Tokens ======
  
-Tokens allow you to add textual ​information ​to [[/​Text_Fields|token text fields]]. ​ You can tell that a field accepts tokens because a small BUTTON{{{T}}} shows in the field while editing it.+**Keyboard Maestro provides two means to get information ​about objects (like web pages and windows) ​in the user's environment:​**
  
-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. ​ You can insert a token by name by choosing ​[[Menus#​Insert_Token_by_Name|Insert Token by Name]] from the [[Menus#​Edit|Edit menu]].+1. [[:Tokens|Tokens]] (returns text, used in [[/​Text_Fields|text fields]]
 +2. [[:Functions|Functions]] (returns numbers, used in numeric fields )
  
-The available tokens are listed on the [[/Tokens|wiki Tokens page]].+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.  This allows you to easily combine static text with dynamic data that is supplied at run time, in most any Action that has a text field, like [[action:​Display_Text|Display Text]] and [[action:​Set_Variable_to_Text|Set Variable to Text]].
  
-Text token fields also process ​%NNor %NNNN% as arbitrary hex unicode characters ​(eg %41is 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).+===== 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. 
 + 
 +1. Press ⌘⌃T (or use the Menu) to display a prompt to select the Token by Name 
 +2. GoTo menu [[Menus#​Insert_Token|Edit ➤ Insert Token menu]] 
 +3. Click on the "​Insert Token" popup at the top right of the text fields to see the same menu as in #2. 
 +4. 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: 
 + 
 +1. `%FrontBrowserTitle%
 +2. `%FrontBrowserURL%` 
 + 
 +{{:​manual:​token-example-set-clipboard.png?​nolink|}} 
 + 
 +The "`[]()`" are just characters you type. 
 + 
 +After the macro and Action are executed, you will see this on the Clipboard:​ 
 + 
 +{{:​manual:​token-demo-display-clipboard.png?​nolink|}} 
 + 
 +That's all you need for a great macro, which you can [[https://​forum.keyboardmaestro.com/​t/​set-clipboard-to-markdown-link-of-frontmost-browser-wiki-example-macro-v9-0-1d2/​15025|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 charactersor  
 +* 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 (\\). To include a percent in your text, simply double the percent (%%). To include a backslash \ in your text, double the backslash (\\).
  
-With tokens that commonly contain arrays ​of information,​ you can easily ​access the individual ​parts using the token array notation, ​eg `%TriggerValue[3]%will be the third comma-separated valueand `%TriggerValue[3];%will be the third semicolon-separated value, ​and `%TriggerValue[3] %` (note the space between the `]` and the `%`) will be the third space-separated value (8.0.4+). This currently works with the following ​tokens:+ 
 +===== 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 namejust 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]%1returns "​1514"​ 
 + 
 +These tokens ​allow this indexing:
  
 * [[token:​TriggerValue|TriggerValue]] * [[token:​TriggerValue|TriggerValue]]
Line 23: Line 115:
 * [[token:​CurrentMouse|CurrentMouse]] * [[token:​CurrentMouse|CurrentMouse]]
 * [[token:​FoundImage|FoundImage]] * [[token:​FoundImage|FoundImage]]
- 
-Many actions allow you to turn off tokens or backslash character processing if you need to use text that has percent or backslash characters. 
manual/Tokens.txt · Last modified: 2023/10/02 00:10 by peternlewis