Differences

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

--- AppleScript [2017/06/04 23:06] – [Get Existing Variable] JMichaelTX
+++ AppleScript [2025/02/27 06:45] (current) – [Local & Instance Variables] peternlewis
@@ Line 1: / Line 1: @@
 ====== Using AppleScript to Get and Set Keyboard Maestro Variables ======
-\\
-===== Get and Set Variables =====
 Keyboard Maestro Version 7.1 introduced a streamlined way to Get and Set Keyboard Maestro Variables from AppleScript.
-In AppleScript, you can tell the application "Keyboard Maestro Engine" to:
+In AppleScript, you can access Keyboard Maestro variables like this:
-    getvariable <KM Variable Name>
+```applescript
-    setvariable <KM Variable Name> to <New Value>
+tell application "Keyboard Maestro Engine"
+    set v to getvariable "<KM Variable Name>"
+    setvariable "<KM Variable Name>" to "<New Value>"
+end tell
+```
 where both the `<KM Variable Name>` and `<New Value>` are text values.
-==== Examples ====
+**For more details, see:**
+  - [[manual:Scripting|Scripting article in the Manual Section]].
+  - [[action:Execute_an_AppleScript|Execute AppleScript Action]].
+===== Global Variables =====
+Global Variables (available in //all// macros) may be got and set like this:
 ```applescript
@@ Line 44: / Line 52: @@
 ```
+**Real-World Example**
 Normally, you would not have both a GET and a SET variable within the same AppleScript tell block.\\
@@ Line 50: / Line 58: @@
 ```applescript
+### Requires Keyboard Maestro 7.1+ ###
 --- GET REQUIRED KM VARIABLES ---
@@ Line 67: / Line 77: @@
 ```
+===== Local & Instance Variables =====
-**For more details, see [[manual:Scripting|Scripting article in the Manual Section]].**
-----
+To get or set [[manual:Variables#Scope|Local or Instance Variables]], you must pass the macro execution instance to the `getvariable` or `setvariable` command.  The instance is passed in to your script via the KMINSTANCE environment variable (v8.0.3+).
-===== Prior to Ver 7.1 =====
+```applescript
+set kmInst to system attribute "KMINSTANCE"
+tell application "Keyboard Maestro Engine"
+	set v to getvariable "Local__SomeLocalVariable" instance kmInst
+	setvariable "Local__FromAS" instance kmInst to "Variable set in AppleScript."
+end tell
-  * All of the below scripts were designed for use with Keyboard Maestro prior to version 7.1, but they will still work with the latest version.
+log v
-  * They present an alternate method.
+```
-==== Create & Set Variable ====
-```applescript
+===== Dictionary Values =====
---- Requires KM 7.0.2+ ---
---- Set AppleScript Variables to KM Variable Name and Value ---
+You can read and write [[manual:Dictionaries|Dictionary]] values from AppleScript.
-set myKMVar to "My KM Var Name"
-set myASVar to "My data"
+```applescript
+### Requires Keyboard Maestro 8.0+ ###
 tell application "Keyboard Maestro Engine"
-  if variable myKMVar exists then
+	set kmDictList to name of dictionaries
-    --- SET KM Variable ---
+	set dictKeyList to dictionary keys of dictionary "First Names"
-    set value of variable myKMVar to myASVar
-  else
+	set value of dictionary key "P" of dictionary "First Names" to "Fred"
-    --- Create & Set KM Variable ---
-    make new variable with properties {name:myKMVar, value:myASVar}
-  end if
 end tell
 ```
-==== Get Existing Variable ====
+===== Prior to Ver 7.1 =====
+  * All of the below scripts were designed for use with Keyboard Maestro prior to version 7.1, but they will still work with the latest version.
+  * They present an alternate method.
+==== Set Variable ====
+(will be created if necessary)
+```applescript
+my setKMVar("MY_KM_Variable", "some new value")
+on setKMVar(pKMVarNameStr, pValueStr)
+  --- Compatible with Keyboard Maestro 6+ ---
+  --     • Creates the KM Variable if does not exist (just like KM 7 setvariable)
+  --     • Returns true if new Variable was created
+  set varCreatedBool to false
+  tell application "Keyboard Maestro Engine"
+    try
+      set value of variable pKMVarNameStr to pValueStr
+    on error errMsg number errNum
+      if (errNum = -10006) then --- KM Variable Does NOT Exist ---
+        --- Create & Set KM Variable ---
+        make new variable with properties {name:pKMVarNameStr, value:pValueStr}
+        set varCreatedBool to true
+      else
+        error ("Error " & errNum & ":  " & errMsg)
+      end if
+      -- END on error
+    end try
+  end tell
+  return varCreatedBool
+end setKMVar
+```
+==== Get Variable ====
+(returns empty string "" if Variable does //not// exist)
 ```applescript
@@ Line 107: / Line 162: @@
   --- Compatible with Keyboard Maestro 6+ ---
-  --     • Returns "" if variable is not found (just like KM 7)
+  --     • Returns "" if variable is not found (just like KM 7 getvariable)
   tell application "Keyboard Maestro Engine"