Differences

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

--- Variables [2017/09/04 00:10]
peternlewis [Variable Arrays]
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Keyboard Maestro Variables ======
-Keyboard Maestro [[manual:Variables|variables]] are used much like variables in any scripting or macro language.  They provide for the storage of data (only plain text, no styles) as determined by you, the Keyboard Maestro user.
-===== Key Facts about Variables =====
-Keyboard Maestro has four types of variables, distinguished based on their name.
-* [[#Password_Variables|Password Variables]] — names start or end with "Password" or "PW".
-* [[#Local_Variables|Local Variables]] — names start or end with "Local " or "𝕃".
-* [[#Instance_Variables|Instance Variables]] — names start or end with "Instance " or "𝕀".
-* Variables — All other variables.
-As described in the [[manual:Variables|user manual]], variables contain text, but may be used as numbers in calculations if they contain a valid expression (eg "10*5").
-  * Each Macro may create Variables and read existing Variables.
-  * Variables persist, permanently stored on your Mac (much like a file) until deleted.
-  * Variables are global, fully accessible (create, read, write, delete) by:
-    * All other Macros.
-    * Future or simultaneous executions of some macro.
-    * Scripts.
-    * AppleScript.
-    * //Keyboard Maestro Editor Preferences// panel (Variables tab).  :!: **Note:**  When deleted, there is no warning, and there is no _Trash_ to recover deleted Variables from.
-    * **All Keyboard Maestro variables can contain only plain text**.
-    * However, you can use variables that contain numbers in calculations in [[https://wiki.keyboardmaestro.com/Text_Fields|numeric fields]], or by using the [[token:Calculate|Calculate Token]] in [[https://wiki.keyboardmaestro.com/Text_Fields|text fields]].
-===== Setting Variables =====
-Variables are usually created and set by [[:Actions|Macro Actions]], but can also be set by [[#Using_Variables_in_Scripts|scripts]], and can then be used by other Macro Actions.  The Action that sets a Variable will create it if need be.  Variables do not need to be declared in any way.
-The most common Action to set a variable is, well, [[action:Set_Variable_to_Text|Set Variable to Text]].
-{{ :token:km-wiki-set-variable-action.png?nolink |}}
-There are a number of other [[:Actions|Actions]] to set variables:
-  * [[action:Set_Variable_to_Calculation]]
-  * [[actions:Browser_Form_Actions#Set_Variable_to_Field|Set Variable to Browser Field]]
-  * [[action:Set_Variable_to_Keychain_Password]]
-In addition to these, there are a number of more complex Actions that can also set a variable.  The [[action:For_Each|For Each]] Action is an example.  Variables can also contain the results of many actions, such as the [[action:Execute_a_Shell_Script|Execute a Shell Script]] action.
-When setting a variable, you will be using a text field in most cases. :!: Be aware that [[:Text_Fields|Text fields]] (that are not regular expression fields), process backslashed characters \a,\b,\e,\f,\t,\r,\n (bell,backspace,escape,form feed,tab,return,line feed).  For more information, see the [[:Text_Fields|Text fields]] Wiki article.
-===== Using Variables =====
-There are many Macro Actions that can use variables.  Some of these explicitly provide for entry of the variable name, but most provide for a more general entry of a Keyboard Maestro Token.
-==== Variable Tokens ====
-The //%Variable%//`<VariableName>`% token allows you to include a variable in a token text field,\\
- where `<VariableName>` is the name of the variable.
-For Example, using the [[action:Insert_Text|Insert Text]] Action:
-{{ :token:km-wiki-insert-text-action.png?nolink |}}
-You can (v7.2+) access a variable as if it is a comma separated array of text using the notation //%Variable%//`<VariableName>[3]`% where 3 can be any [[manual:Calculations|Calculations]].  You can use a different item separator by putting the text between the ] and % characters, eg //%Variable%//`<VariableName>[3]:`%.  Arrays are indexed starting from 1.
-You can also use a short form of just //%Variable Name%// to include variables as long as the variable exists and has a value and there is no corresponding text token, although generally it is better and clearer to use the longer form //%Variable%Variable Name%//.
-==== Variables in Calculations ====
-Variables can be used in calculations if their value holds a number or a numeric expression that can be evaluated.  Variables are used *unadorned* in calculations, for example `My Variable * 7`.
-==== Variable Arrays ====
-Variables can contain an array of comma separated **numbers**, like the image size (123,456) or window frame (100,120,600,550). In a calculation field, you can refer to these using a normal (1-based) index notation, like Variable[2]. So you can use ClipboardImageSize[1] and ClipboardImageSize[2].
-**It is important to note that variable arrays can contain only numeric values**.  When you use the [[token:Calculate|%Calculate%]] function to reference a variable array element, it will convert the element to a number.  So, in effect, you can only use variable arrays to store/reference numbers.
-For example, suppose the variable `MyArray` has this value: `10,05,00,12`. In any Keyboard Maestro Action text field where you would like to use the array element `%Calculate%MyArray[2]%`, it will return "5" because it has evaluated it as number, not the actual string of the element "05".  In any numeric field, you would use just `MyArray[2]` and it will return the number 5.  Note that you can (v8+) use `%Dec2%MyArray[2]%` in a text field to return the value of the array element, padded to two digits withe leading zeros.
-===== Using Variables in Scripts =====
-You can get and set Keyboard Maestro Variables in these types of scripts:
-  * [[:AppleScript|AppleScripts]]
-  * [[:JavaScript for Automation#Accessing_Keyboard_Maestro_Variables|JavaScript for Automation (JXA)]]
-  * [[action:Execute_a_JavaScript_in_Google_Chrome|JavaScript in Safari or Google Chrome]]\\
-  * (Browser JavaScript can only GET Keyboard Maestro Variables.  They cannot be set there)
-  * [[action:Custom_HTML_Prompt#Using_JavaScript|JavaScript in Custom HTML Prompts]]
-  * [[action:Execute_a_Shell_Script|Shell Scripts]]
-  * [[action:Execute_a_Swift_Script|Swift Scripts]]
-And you can generally access Keyboard Maestro variables anywhere else via [[:AppleScript|AppleScript]] from whatever language you want to use.
-Click on the above links for example scripts.
-===== Password Variables =====
-Variables with names that start or end with “Password” or “PW” are considered passwords – their values will not be stored (except in memory) and they cannot be read directly by shell scripts or AppleScripts, though their consequences can easily be extracted, eg with the Set Clipboard to Text action. The Prompt For User Input dialog will display such variables in a password field.
-===== See Also =====
-----
-=== Actions ===
-* [[action:Set Variable to Calculation|Set Variable to Calculation]]
-* [[action:Set Variable to Text|Set Variable to Text]]
-* [[:Actions|See all Actions]]
-----
-==== Forum ====
-- [[https://forum.keyboardmaestro.com/t/how-do-i-get-km-variable-in-shell-script-from-other-apps/3165/3|How Do I Get KM Variable in Shell Script from other Apps?]]
-- [[https://forum.keyboardmaestro.com/t/proper-syntax-for-array-of-arrays/4506/5|Proper Syntax for Array of Arrays?]]
-- [[https://forum.keyboardmaestro.com/tags/variables|Keyboard Maestro Forum topics about Keyboard Maestro Variables]]
-- [[https://forum.keyboardmaestro.com/search?q=%22array%20of%20text%22|Keyboard Maestro Forum topics about Keyboard Maestro Array of Text]]

Keyboard Maestro Wiki

User Tools

Site Tools

Differences

Page Tools