User Tools

Site Tools


manual:Scripting

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
manual:Scripting [2017/08/25 05:43]
peternlewis [Using Keyboard Maestro Facilities from AppleScript]
manual:Scripting [2023/10/04 04:27] (current)
peternlewis
Line 9: Line 9:
   * [[action:​Execute_a_JavaScript_For_Automation|Execute a JavaScript For Automation]]   * [[action:​Execute_a_JavaScript_For_Automation|Execute a JavaScript For Automation]]
   * [[action:​Execute_a_JavaScript_in_Custom_Prompt|Execute JavaScript in Custom HTML Prompt]]   * [[action:​Execute_a_JavaScript_in_Custom_Prompt|Execute JavaScript in Custom HTML Prompt]]
-  * [[action:Execute_a_JavaScript_in_Safari|Execute a JavaScript in Safari]] +  * [[actions:Execute_a_JavaScript_in_Browser|Execute a JavaScript in Browser]]
-  * [[action:​Execute_a_JavaScript_in_Google_Chrome|Execute a JavaScript in Google Chrome]]+
   * [[action:​Execute_a_Shell_Script|Execute a Shell Script]]   * [[action:​Execute_a_Shell_Script|Execute a Shell Script]]
 +  * [[action:​Execute_Shortcut|Execute Shortcut]]
   * [[action:​Execute_a_Swift_Script|Execute a Swift Script]]   * [[action:​Execute_a_Swift_Script|Execute a Swift Script]]
   * [[action:​Apply_a_BBEdit_Text_Factory|Apply a BBEdit Text Factory to the Clipboard]]   * [[action:​Apply_a_BBEdit_Text_Factory|Apply a BBEdit Text Factory to the Clipboard]]
Line 17: Line 17:
 You can specify the script to be executed either by reference to a file or as text entered directly in the _Execute Action_. ​ After pasting or typing script text into the Execute Script Action, press the <​key>​Enter</​key>​ key to compile and format the script. You can specify the script to be executed either by reference to a file or as text entered directly in the _Execute Action_. ​ After pasting or typing script text into the Execute Script Action, press the <​key>​Enter</​key>​ key to compile and format the script.
  
-For example, the [[action:​Execute_an_AppleScript]] ​Action:\\ +For example, the [[action:​Execute_an_AppleScript|Execute an AppleScript]] action:
-{{:​km-7.3-execute-script.png?​nolink|}}\\+
  
-==== Getting Script Results ====+{{ execute-script-example.png?​nolink&​424x400 | Execute AppleScript Example }}
  
-The results of scripts can be displayed, ​or they can be typed or pasted ​in to the current ​application document, or saved into a Keyboard Maestro Variable ​or the System Clipboard. ​ This allows you to insert text that depends on many factors, such as date calculations, ​file listings, SQL queries, web pages, or anything else you can imagine ​Alternatively, ​the results ​can be displayed in Notification Center, in a window, or in large type across the screen. ​ Or you can ignore ​the results, or execute ​the script asynchronously,​ leaving it running in the background.+**There are two setup options:​** 
 +^ Setup Option ^ Choices\\ (Default shown first) ^ 
 +| Script location | Execute text script (type or paste script into Action text field)\\ Execute script file (This may be faster if it is a compiled script file `.scpt`) | 
 +| Script Results | Ignored.\\ Displayed in a floating window.\\ Displayed briefly in a Notification.\\ Displayed large across the screen.\\ Typed in the current ​text field that has focus.\\ Pasted in text field that has focus.\\ Saved to a Keyboard Maestro Variable.\\ Appended to a Keyboard Maestro Variable.\\ Saved to the System ​or a Named Clipboard.\\ Saved to file.\\ Ignore ​the results ​and run //​Asynchronously//​ (the script runs while the macro continues on to the next //Action//)|
  
 ==== Using the Clipboard ==== ==== Using the Clipboard ====
  
-You can also read and set the clipboard in a script, although the easiest way to set the clipboard to the results of a script is to select the Execute Script Action option to "save results to clipboard"​. ​ This works _only_ ​for plain text returned by the script. ​ For more complex formats, you will need to set the Clipboard directly in the script.+You can also read and set the clipboard in a script, although the easiest way to set the clipboard to the results of a script is to select the Execute Script Action option to "save results to clipboard"​. ​ This works for plain text and some images ​returned by the script. ​ For more complex formats, you will need to set the Clipboard directly in the script.
  
 For more information about using the Clipboard in scripts, see: For more information about using the Clipboard in scripts, see:
   * [AppleScript Clipboard Commands suite](https://​developer.apple.com/​library/​mac/​documentation/​AppleScript/​Conceptual/​AppleScriptLangGuide/​reference/​ASLR_cmds.html)   * [AppleScript Clipboard Commands suite](https://​developer.apple.com/​library/​mac/​documentation/​AppleScript/​Conceptual/​AppleScriptLangGuide/​reference/​ASLR_cmds.html)
-  * [Shell Scripts Pasteboard Commands: ​pbcopy, pbpaste](https://​developer.apple.com/​legacy/​library/​documentation/​Darwin/​Reference/​ManPages/​man1/​pbpaste.1.html)+  * The unix man pages for pbcopy, pbpaste.
  
 ==== Automating Applications and Adding Functionality to Keyboard Maestro ==== ==== Automating Applications and Adding Functionality to Keyboard Maestro ====
Line 38: Line 40:
 ==== Web Page Interactions ==== ==== Web Page Interactions ====
  
- +The [[actions:Execute_a_JavaScript_in_Browser|Execute a JavaScript in Browser]] actions enable ​deep control over a web page, as well as extracting specific data from both the page contents and HTML.
-JavaScript in a Browser Actions ([[action:Execute_a_JavaScript_in_Google_Chrome|Google Chrome]] and [[action:​Execute_a_JavaScript_in_Safari|Safari]]) enables ​deep control over a web page, as well as extracting specific data from both the page contents and HTML.+
  
 ==== Shell Scripts ==== ==== Shell Scripts ====
- 
  
 Shell scripts can execute any installed scripting language, such as perl, python, ruby or whatever. ​ Be aware that because shell scripts are executed in a non-interactive shell, typically none of the shell configuration files (like CODE{{{.login}}} or CODE{{{.profile}}}) will be executed, which may change the way the shell script behaves. Shell scripts can execute any installed scripting language, such as perl, python, ruby or whatever. ​ Be aware that because shell scripts are executed in a non-interactive shell, typically none of the shell configuration files (like CODE{{{.login}}} or CODE{{{.profile}}}) will be executed, which may change the way the shell script behaves.
- 
  
 Variables can be accessed from shell scripts via the environment variables in the form $KMVAR‗Variable‗Name where KMVAR‗ is prefixed, and spaces are converted to underscores. ​ AppleScripts can also access the environment variables using the CODE{{{system attribute}}} command, but note that CODE{{{system attribute}}} is not safe for international characters. Variables can be accessed from shell scripts via the environment variables in the form $KMVAR‗Variable‗Name where KMVAR‗ is prefixed, and spaces are converted to underscores. ​ AppleScripts can also access the environment variables using the CODE{{{system attribute}}} command, but note that CODE{{{system attribute}}} is not safe for international characters.
  
-Note that the total size of the variables stored in the environment is limited to 100K, so larger variables may be excluded to ensure the variables do not take up excessive amounts of environment space since this is limited by the system.+Note that the total size of the variables stored in the environment is limited ​by the system ​to 100K, so larger variables may be excluded to ensure the variables do not take up excessive amounts of environment space.
  
 Variables whose names start with "​ENV‗"​ override regular environment variables (eg "​ENV‗PATH"​ overrides the regular "​PATH"​ environment variable). Variables whose names start with "​ENV‗"​ override regular environment variables (eg "​ENV‗PATH"​ overrides the regular "​PATH"​ environment variable).
  
-===== AppleScript ​=====+==== AppleScript ====
  
 AppleScripts ​ can perform many tasks on the Mac and control many applications. AppleScripts ​ can perform many tasks on the Mac and control many applications.
  
-You can read and write variables and control the Keyboard Maestro engine with AppleScript:​+You can read and write [[Variables|variables]], [[Dictionaries|dictionaries]] ​and control the Keyboard Maestro engine with AppleScript:​
  
 <code applescript>​ <code applescript>​
Line 69: Line 68:
 </​code>​ </​code>​
  
-**For AppleScripts compatible with prior versions of Keyboard Maestro**, see  [[:​AppleScript#​Prior_to_Ver_71|Using AppleScript prior to version 7.1]]. +==== JavaScript for Automation ​====
- +
- +
-===== JXA =====+
  
 JavaScript for Automation (JXA) can access Variables with: JavaScript for Automation (JXA) can access Variables with:
Line 83: Line 79:
  
 For details on JXA, see [[:​JavaScript for Automation]]. This provides an introduction to JXA and comparison with AppleScript. For details on JXA, see [[:​JavaScript for Automation]]. This provides an introduction to JXA and comparison with AppleScript.
-===== JavaScript ===== 
  
-JavaScript in web browsers can access the variable values by using the document.kmvar dictionary, like document.kmvar.Variable‗Name (spaces are converted to underscores),​ but they have no way to write values back to variables, except by returning a result from the script.+==== JavaScript ==== 
 + 
 +JavaScript in web browsers can access the variable values by using the kmvar dictionary, like kmvar.Variable‗Name (spaces are converted to underscores),​ but they have no way to write values back to variables, except by returning a result from the script.
  
 ===== User Interaction ===== ===== User Interaction =====
Line 97: Line 94:
 end tell end tell
 </​code>​ </​code>​
- 
-The CODE{{{osascript}}} tool will execute in 64-bit mode, which may be a problem if you have old versions of AppleScript extensions installed. ​ However, you can set the command line tool that is used to execute AppleScripts as described in [[Preferences#​Other_Hidden_Preferences|Other Hidden Preferences]]. 
  
 See also the [[Variables]] section. See also the [[Variables]] section.
Line 130: Line 125:
 </​code>​ </​code>​
  
-The CODE{{{do script}}} will not return until the macro is finished executing.+The CODE{{{do script}}} will not return until the macro is finished executing. The [[action:​Return_Result|Return Result]] action can be used to return a result to the AppleScipt.
  
 You can pass an optional parameter using the CODE{{{with parameter}}} clause, which you can read in the macro as the [[token:​TriggerValue|%TriggerValue% token]]. You can pass an optional parameter using the CODE{{{with parameter}}} clause, which you can read in the macro as the [[token:​TriggerValue|%TriggerValue% token]].
Line 169: Line 164:
 </​code>​ </​code>​
  
-You can ask Keyboard Maestro Engine to process tokens ​for you with:+or process tokens with:
  
 <code applescript>​ <code applescript>​
 tell application "​Keyboard Maestro Engine"​ tell application "​Keyboard Maestro Engine"​
-  ​set clip to process tokens "%PastClipboard%3%"+  process tokens "%LongDate%
 +end tell 
 +</​code>​ 
 + 
 +The `calculate` and `process tokens` commands can also take an `instance` parameter (v10.0+) to specify the instance for local variable access. 
 + 
 +You can ask Keyboard Maestro Engine to find strings in other scripts: 
 + 
 +<code applescript>​ 
 +tell application "​Keyboard Maestro Engine"​ 
 +   count found in "The Source"​ for "​.e"​ with regex 
 +end tell 
 +</​code>​ 
 + 
 +And you can search and replace with: 
 + 
 +<code applescript>​ 
 +tell application "​Keyboard Maestro Engine"​ 
 + search "3+4" for "​(\\d+)"​ replace "​%CalculateFormat%CALCULATE(\\1)%Currency%" ​with regex and process tokens
 end tell end tell
 </​code>​ </​code>​
Line 189: Line 202:
 </​code>​ </​code>​
  
-Alternatively you can use the [[/action/​Set_Macro_Enable|Set Macro Enable action]].+Alternatively you can use the [[action:​Set_Macro_or_Group_Enable|Set Macro Enable action]].
  
 You can rename, create, delete, duplicate macro groups and macros. ​ You can add and remove actions. ​ You can get or set the selection. You can rename, create, delete, duplicate macro groups and macros. ​ You can add and remove actions. ​ You can get or set the selection.
Line 203: Line 216:
 See the Keyboard Maestro AppleScript dictionary for more information. See the Keyboard Maestro AppleScript dictionary for more information.
  
-===== URL Schemes ​=====+===== Controlling Keyboard Maestro Engine via Scripting ​=====
  
-==== Editor ==== +You can adjust ​Keyboard Maestro ​Engine windows ​with:
- +
-Another way you can control ​Keyboard Maestro ​Editor is using the "​`keyboardmaestro`"​ URL scheme, which supports the following formats: +
- +
-^ Example Editor URL Command ^ Description ^ +
-| `keyboardmaestro://​u=support%40stairways.com/​s=ABCDEFGH0123456789` | enter your username/​serial number. | +
-| `keyboardmaestro://​m=Activate%20Application%20Switcher`\\ `keyboardmaestro://​m=D2F427A1-51E3-4719-820B-4C25B6FF7329` | edit a specific macro or macro group.\\ You may used either the Macro Name, or UUID. | +
-| `keyboardmaestro://​q=Activate` | filter macros ​with this keyword. | +
-| `keyboardmaestro://​g=All%20Macros/​q=Activate` | select a macro group and filter macros with this keyword. | +
-| `keyboardmaestro://​a=Execute` | filter actions with this keyword. | +
-| `keyboardmaestro://​c=All%20Actions/​a=Execute` | select action category and filter actions with this keyword. | +
- +
---- +
- +
-==== Triggers ==== +
- +
-You can trigger a macro (that is Active and Enabled) using the "​`kmtrigger`"​ URL scheme.\\ +
-The URL uses this format:\\ +
-`kmtrigger://​macro=<​Macro Name or UUID>​[&<​Trigger Value>​]` +
- +
-where +
-  * `<Macro Name or UUID>` is either the Macro Name, OR, its UUID\\ +
-  * `<​Trigger Value>` is the _optional_ Trigger Value +
-  * `[ ]` are _not_ included. ​ Used only to show _optional_ parameters +
-  * `&` must precede the Trigger Value, if it is provided. +
- +
-Note both Macro Name and Trigger Value must be URL encoded. +
- +
-You can easily get the Trigger URL by clicking on the "Or by Script"​ Trigger option, and selecting "Or by URL"​. +
- +
-{{:​manual:​km-7.3-macro-trigger-url-setup.png?​nolink|}} +
- +
-{{:​manual:​km-7.3-macro-trigger-url-results.png?​nolink|}} +
- +
-^ Example Trigger URL Command ^ Description ^ +
-| `kmtrigger://​macro=Your%20Macro%20Name` | Using the Macro Name | +
-| `kmtrigger://​macro=224AA8CB-07EB-4C92-8201-68FED82B6E9F` | Using the Macro UUID | +
-| `kmtrigger://​macro=Your%20Macro%20Name&​value=Your%20Trigger%20Value` | Using Macro Name with Trigger Value | +
-| `kmtrigger://​macro=224AA8CB-07EB-4C92-8201-68FED82B6E9F&​value=Your%20Trigger%20Value` | Using Macro UUID with Trigger Value  |+
  
 +<code applescript>​
 +tell application "​Keyboard Maestro Engine"​
 +    set bounds of window "​Clipboard History Switcher"​ to {1000, 50, 2000, 1200}
 +end tell
 +</​code>​
  
-See also the [[Calculations]] and [[Tokens]] sections. 
  
manual/Scripting.1503654232.txt.gz · Last modified: 2017/08/25 05:43 by peternlewis