Using Real Java Script in BTT

NOTE: If you are using the floating webview action in BTT have a look here instead: Floating Webview JavaScript


This feature is new in BetterTouchTool version 3.333. I think it is the most powerful and easiest way to script BetterTouchtool.

It's basically just modern Java Script (so you can use async await and the like) however it has a few important additions:

  • It can call any Apple Script - and get the result
  • It can call any Shell Script - and get the result.
  • It can trigger all functions available in BetterTouchTool's scripting interface.

By combining these three you can automate almost any task on your Mac.

mcc


1.) Running Apple Scripts

To run a Apple Script from within the Java Script code, use the runAppleScript(scriptCode) function. The function takes a string that defines the Apple Script, and returns a promise which resolves to the result value.

I'm always using it with async await, but you can also use classic Promise syntax.

Example: Run Apple Script from within Java Script

// I always put my code into a self executing async function, because top level await is not allowed in JavaScript.
(async () => {

// put the Apple Script into a string (back ticks are great for multi -line strings)
let appleScript = `
    set theDialogText to "The curent date and time is " & (current date) & "."
    set result to display dialog theDialogText
    return result
`;

// this will execute the Apple Script and store the result in the result variable.
let result = await runAppleScript(appleScript);

// do whatever you want with the result

// at the end you always need to call returnToBTT to exit the script / return the value to BTT.
returnToBTT(result);

// it is important that this function self-executes ()
})();

2.) Running Shell Scripts

Example: Run Shell Script from within Java Script

// I always put my code into a self executing async function, because top level await is not allowed in JavaScript.
(async () => {

// put the shell script into a string (single backticks are great for multiline strings)
let shellScript = `say hello world`;


let shellScriptWrapper = {
    script: shellScript, // mandatory
    launchPath: '/bin/bash', //optional - default is /bin/bash
    parameters: '-c', // optional - default is -c
    environmentVariables: '' //optional e.g. VAR1=/test/;VAR2=/test2/;
};

// this will execute the Apple Script and store the result in the result variable.
let result = await runShellScript(shellScriptWrapper);

// do whatever you want with the result

// at the end you always need to call returnToBTT to exit the script / return the value to BTT.
returnToBTT(result);

// it is important that this function self-executes ()
})();

3.) Using the callBTT() JavaScript function to call BTT scripting functions

All BetterTouchTool scripting functions are accessed via this function: async function callBTT(scriptingFunctionName, arguments). It takes two arguments: the name of the scripting function (e.g. 'trigger_named') and a JS object that contains the parameters (e.g. {trigger_name: 'test'}). It returns a promise that resolves to any result that might be returned by the BTT scripting function.

Available BetterTouchTool Scripting Interfaces

The available scripting functions are:

  • trigger_named
  • update_touch_bar_widget
  • trigger_action
  • execute_assigned_actions_for_trigger
  • refresh_widget
  • update_trigger
  • add_new_trigger
  • delete_trigger
  • trigger_named
  • trigger_named_async_without_response
  • get_dock_badge_for
  • get_active_touch_bar_group
  • is_true_tone_enabled
  • get_location
  • set_persistent_string_variable
  • set_string_variable
  • set_persistent_number_variable
  • set_number_variable
  • get_number_variable
  • get_string_variable
  • is_app_running

Example script function calls:

trigger_named

This method will trigger the specified named trigger (which can be configured in the "Other" tab in BetterTouchTool.)

Example

((async ()=> {
let result = await callBTT('trigger_named', {trigger_name: 'Action5'});
// Currently only the Apple Script and Shell Script actions return results.
returnToBTT(result);
})();

update_touch_bar_widget

This method will update the contents of a Touch Bar Script Widget (identified by its uuid). You can provide a new text to show, a new icon and a new background color.

For the icon you can either provide it directly using the icon_data parameter (must be base64 encoded) or you can provide a file path (via the icon_path parameter) that points to the new icon.

You can get the uuid by right-clicking any script widget in BTT.

Example:

(async ()=> {

let widgetConfig = {
    text: "hi there!",
    icon_path: "/Users/andi/Desktop/test.png",
    background_color: "200,100,100,255"    
};

callBTT('update_touch_bar_widget', {uuid: '9990CE09-9820-4D67-9C52-8BABAB263056', json: widgetConfig});

returnToBTT('done');

})();

trigger_action

This method will trigger any of BetterTouchTool's predefined actions (or any combination of them).

You need to provide a JSON description of the action you want to trigger as a string. The easiest way to get such a JSON description is to right-click the trigger you have configured in BetterTouchTool and choose "Copy JSON". This will copy the complete JSON (including the configuration for the trigger itself), but this action will ignore anything that's not needed. (or you can delete the not needed parts)

Example:

((async ()=> {

let actionDefinition = {
  "BTTPredefinedActionType" : 153, 
  "BTTPredefinedActionName" : "Move Mouse To Position", 
  "BTTMoveMouseToPosition" : "{100, 100}", 
  "BTTMoveMouseRelative" : "6"
};


let result = await callBTT('trigger_action', {json: JSON.stringify(actionDefinition)});

returnToBTT(result);

})();

execute_assigned_actions_for_trigger

This method execute all the assigned actions for a given trigger (i.e. gesture, shortcut, drawing etc.) identified by its uuid.

You can get the uuid by right-clicking any configured trigger in BetterTouchTool.

Example

((async ()=> {

    let result = await callBTT('execute_assigned_actions_for_trigger',{uuid: '2F34005D-4537-464D-94E9-A7F42DA39DF1'});
    // Currently only the Apple Script and Shell Script actions return results.
    returnToBTT(result);
})();

refresh_widget

This method will execute all scripts assigned to a script widget and update its contents accordingly.

The widget is identified by its uuid, which you can get by right-clicking the widget in BetterTouchTool.

Example

((async ()=> {

callBTT('refresh_widget', {uuid: '2F34005D-4537-464D-94E9-A7F42DA39DF1'});

returnToBTT('done');

})();

update_trigger

This method will update the configuration of any trigger you have configured in BTT (i.e. gestures, shortcuts, touchbar items etc.).

You need to provide the uuid of the trigger you want to update (get by right-clicking it in BTT) and a JSON object defining the updates. To know how the JSON object should look like, right-click the trigger in BTT and choose "Copy JSON".

Example:

Hint: don't forget to use JSON.stringify() before passing the updateDefinition object.

((async ()=> {

var updateDefinition = {
    "BTTTouchBarButtonName" : "New Name",
    "BTTTouchBarItemIconHeight" : 25
}

callBTT('update_trigger', {uuid: '123e4567-e89b-12d3-a456-426655440000',json: JSON.stringify(updateDefinition));

returnToBTT('done');

})();

get_trigger

This allows you to retrieve the json representation of any trigger (e.g. gesture, Touch Bar button, keyboard shortcut etc.) identified by the given UUID.

You can get the UUID by right-clicking any trigger in BTT.

((async ()=> {

let result = await callBTT('get_trigger', {uuid:'123e4567-e89b-12d3-a456-426655440000'})
returnToBTT(result);
})();

add_new_trigger

This method will add a new trigger to BTT (i.e. gestures, shortcuts, touchbar items etc.).

You need to provide a JSON object defining the new trigger. To know how the JSON object should look like, right-click any existing trigger in BTT and choose "Copy JSON".

Example


((async ()=> {
var newTriggerDefinition = {
  "BTTTriggerClass" : "BTTTriggerTypeKeyboardShortcut",
  "BTTPredefinedActionType" : 5,
  "BTTPredefinedActionName" : "Mission Control",
  "BTTAdditionalConfiguration" : "1179648",
  "BTTTriggerOnDown" : 1,
  "BTTEnabled" : 1,
  "BTTShortcutKeyCode" : 2,
  "BTTShortcutModifierKeys" : 1179648,
  "BTTOrder" : 3
}

callBTT('add_new_trigger', {json: JSON.stringify(newTriggerDefinition)});

returnToBTT('done');

})();

delete_trigger

This method will delete a trigger from BetterTouchTool. You need to provide the uuid of the trigger you want to delete (get by right-clicking it in BTT).

Example

((async ()=> {
 let result = await callBTT('add_new_trigger', {uuid: '2F34005D-4537-464D-94E9-A7F42DA39DF1'});
returnToBTT(result);
})();

get_clipboard_content

Gives you the current text content of the clipboard.

Example

((async ()=> {

let result = callBTT('get_clipboard_content', {});
returnToBTT(result);

})();

set_persistent_string_variable

This allows you to set a variable to a given string that persists over BTT relaunches.

Java Script for Automation Example:

((async ()=> {

let result = await callBTT('set_persistent_string_variable', {variable_name: 'test', to: "this is a test value"});

returnToBTT(result);

})();

set_string_variable

This allows you to set a variable to a given string that persists over BTT relaunches.

((async ()=> {

let result = await callBTT('set_string_variable', {variable_name: 'test', to: "this is a test value"});

returnToBTT(result);

})();

set_persistent_number_variable

This allows you to set a variable to a given string that persists over BTT relaunches.

((async ()=> {

let result = await callBTT('set_persistent_number_variable', {variable_name: 'test', to: 12345});

returnToBTT(result);

})();

set_number_variable

This allows you to set a variable to a given string that persists over BTT relaunches.

((async ()=> {

let result = await callBTT('set_number_variable', {variable_name:'OutputVolume' to: 0.5});

returnToBTT(result);
})();

get_number_variable

This allows you to retrieve the contents of a number variable with the given name

(async ()=> {

let result = await callBTT('get_number_variable', {variable_name:'OutputVolume'})
returnToBTT(result);

})();

get_string_variable

This allows you to retrieve the contents of a string variable with the given name

((async ()=> {

let result = await callBTT('get_string_variable', {variable_name:'BTTActiveAppBundleIdentifier'})
returnToBTT(result);
})();

results matching ""

    No results matching ""