Coming from BetterTouchTool

BetterTouchTool pairs a trigger, such as a gesture or a shortcut, with actions. In Switchboard each pair becomes a macro: the trigger goes under When and the actions under Do.

The importer knows every trigger and action in BetterTouchTool 6.977: 673 actions and 544 triggers, each with the number BetterTouchTool gives it, plus the conditions its editor offers. The pages BetterTouchTool actions and BetterTouchTool triggers list them all and say what each becomes. Where Switchboard chose not to have a feature, the entry says so and why, and the macro imports disabled instead of half working.

What maps #

Window management #

Switchboard itself does not manage windows. Every BetterTouchTool window action (halves, quarters, thirds, sixths, custom size and position, next monitor, center, minimize, close, tile, save and restore layouts, window switcher) imports as a step of the free Window extension from the gallery. The import's review says "Install Window to run 23 steps" and installs it in one click; until then those steps fail with that message. BetterTouchTool's snap areas, hover-and-snap and its own switcher window are not imported.

Touch Bar, Stream Deck, Notch Bar and floating menus #

Switchboard draws none of these. Their buttons import as macros you can run from the palette, the iPhone's pad and the Mac's menu bar:

• A button becomes a macro in a group named after the surface (Touch Bar, Stream Deck, Notch Bar, Floating menus).

• A group, folder or floating menu becomes a group with a Layer: open it with a Layer step (the "Open group" action does) and its buttons answer to the keys 1 to 9, then letters.

• Widgets (date, battery, now playing, weather, scripts) are recorded in the review to rebuild as menu bar items.

• Stream Deck buttons also become a profile for the gallery's Stream Deck companion: the review has Save Stream Deck profile…, and double-clicking the file imports it into Stream Deck.

BetterTouchTool scripts #

Scripts that talk back to BetterTouchTool are rewritten: get_string_variable and set_string_variable in AppleScript become switchboard var get and switchboard var set, and trigger_named becomes switchboard run. Any other BetterTouchTool command in a script is left alone and named in a note. BetterTouchTool's JavaScript API is not available in the JavaScript step; the note says what to change.

What is recorded but not imported #

• Key remaps are recorded in the review with their from and to keys, and the app they apply to. Switchboard has no remap feature yet, so the remap itself does nothing.

• Decided-out features (Siri Remote, drawings, hover and corner triggers, accelerometer, Logitech, Razer and gamepad control, BTT Mobile, the [email protected] assistant, Stage Manager and Spaces moves) import as an unsupported.btt placeholder that keeps the original data, and the macro imports disabled.

Import a preset #

In BetterTouchTool, choose Presets › Export and save a .bttpreset file. Then use File › Import… in Switchboard, or the command line:

switchboard import ~/Desktop/MyPreset.bttpreset --dry
switchboard import --btt-library --dry
switchboard import ~/Desktop/MyPreset.bttpreset
switchboard import ~/Desktop/MyPreset.bttpreset --take-over

• --dry prints the review as JSON and writes nothing.

• --btt-library reads BetterTouchTool's own data store on this Mac, from a copy: no export is needed, and BetterTouchTool can be uninstalled or running. If it has no store, the newest exported preset in its support folder is used.

• --take-over keeps each trigger's on/off state from BetterTouchTool.

Nothing fires twice #

Until you take over, everything imports disabled. BetterTouchTool still owns your shortcuts and gestures. To switch over, quit BetterTouchTool and import with Take over BetterTouchTool's hotkeys on, or with --take-over.

Reading the review #

Each macro has a badge: Ready, Needs a look (something was guessed, for example a gesture read from an id or a media key) or Not supported (it imports disabled). Open a macro's notes for the details. Remaps and widgets appear under Also found, and the coverage line says how many of each kind imported cleanly.

Tidying an import #

An import is literal too: a 0.5-second delay where a wait belongs, variables named however the preset named them, the same four steps pasted into a dozen macros. Tidy up with AI (Macro menu, ⌥⌘I) cleans one macro up. It never runs on its own, and nothing is saved until you have read the changes and pressed Apply, which is one Undo. History records what it did ("Tidied: renamed 4 variables, folded 2 waits").

The plain rules go first:

• Names. Variables that are not lower camel case become readable (my_file_path becomes myFilePath), in every step and condition that uses them. A name that a script, a shell command or a piece of text still uses is left alone, and the change list says why.

• Waits. A fixed pause right before a click, field or button becomes a wait for that element, up to the same time. Two waits in a row become one.

• Unused variables. A variable that is set and never read anywhere, scripts included, is dropped. When in doubt it stays.

• Calls. Steps that match a whole macro you already have become a call to it. Steps that only almost match are listed as a suggestion, not changed.

Then the model gives steps short labels, suggests a name and a description, and may answer an import note when the macro itself shows the answer. It cannot change what any step does: a check compares every step's type and settings before and after, and refuses the proposal if one differs.