Triggering Scripting Functions from the Floating WebView

The Floating Web View allows you to trigger various scripting functions via Java Script.

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

Note: There are some built-in variables, which can also be quite helpful:

Built-In Scripting Variables


There are two ways to trigger these scripting functions, both are equally powerful:

bttweb:// is a custom URL scheme which allows you to trigger scripting functions and retrieve their results, just like any other http call. You can use them in normal a elements <a href="bttweb://trigger_named/?trigger_name=test"></a> or use XMLHTTPRequest or fetch for this.

The general format for bttweb:// links is always bttweb://**scripting_function_name**/?arg1=xxx&arg2=yyy&arg....

Loading bttweb links using fetch with async/await: // a little helper function

async function bttwebRequest(requestPath) {
    const response = await fetch(requestPath);
    const responseText = await response.text();
    return responseText;
}

let result = await bttwebRequest('bttweb://trigger_named/?trigger_name=test');

2.) Using the callBTT() JavaScript function.

BetterTouchTool automatically injects a JavaScript function into any HTML loaded into the floading HTML View. Using that function you can trigger the scripting interfaces mentioned above.

The injected function is async function callBTT(scriptingFunction, 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.

See below for examples on how to use this. In the examples I'm always making use of async/await, but you can also use Promise syntax if you like that better.

Internally the callBTT function just wraps the older window.BTT.callHandler(scriptingFunction, arguments, callback) function and promisifys it. This function is still available for legacy reasons.

Full Example using the callBTT() function

<html>
<head>
<script>
async function triggerNamedTrigger(namedTriggerName) {

  let result = await callBTT('trigger_named',     {trigger_name: namedTriggerName});

  // do whatever you want with the result
  alert('result: ' + result);

}
</script>
</head>
<body>
<button onclick="triggerNamedTrigger('test')">test</button>
</body>
</html>

Closing the webview

You can close the floating webview by passing the closeFloatingWebView set to 1. E.g. callBTT('trigger_named', {trigger_name: 'test', closeFloatingWebView:1} );


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


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

or

<a href="bttweb://trigger_named/trigger_name=Action5">

trigger_named_async_without_response

This method will trigger the specified named trigger (which can be configured in the "Other" tab in BetterTouchTool.). It won't wait for a response.

Example


callBTT('trigger_named_async_without_response', {trigger_name: 'Action5'});
// Currently only the Apple Script and Shell Script actions return results.

or

<a href="bttweb://trigger_named_async_without_response/trigger_name=Action5">

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:


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});

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:

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


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

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


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.

Or

<a href="bttweb://execute_assigned_actions_for_trigger/?uuid=2F34005D-4537-464D-94E9-A7F42DA39DF1">Trigger</a>

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

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

Or

<a href="bttweb://refresh_widget/?uuid=2F34005D-4537-464D-94E9-A7F42DA39DF1">Refresh Widget</a>

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.

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

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

get_trigger

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

let triggerJSONString = await callBTT('get_trigger', {uuid:'123e4567-e89b-12d3-a456-426655440000'})
let parsedJSON = JSON.parse(triggerJSONString);

console.log('parsed json:', parsedJSON);

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

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)});

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

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

Or

<a href="bttweb://add_new_trigger/?uuid=2F34005D-4537-464D-94E9-A7F42DA39DF1">Delete Trigger</a>

get_clipboard_content

Gives you the current text content of the clipboard.

Example

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

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:

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

set_string_variable

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

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

set_persistent_number_variable

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

callBTT('set_persistent_number_variable', {variable_name: 'test', to: 12345});

set_number_variable

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

callBTT('set_number_variable', {variable_name:'OutputVolume' to: 0.5});

get_number_variable

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

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

get_string_variable

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

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

results matching ""

    No results matching ""