BetterTouchTool Floating Menu JSON Documentation

This document describes the JSON structure for creating floating menus in BetterTouchTool.

NOTE Some text is replaced with special characters to reduce the size of this document for LLM usage: © = BTT $ = BTTMenu § = BTTMenuItem

Basic Structure

A floating menu JSON is an array containing menu objects. Each menu can contain multiple menu items via the §s array.

[
  {
    "©TriggerType": 767,
    "©TriggerTypeDescriptionReadOnly": "Floating Menu",
    "©TriggerClass": "©TriggerTypeFloatingMenu",
    "©UUID": "unique-uuid-here",
    "©Enabled": 1,
    "©TriggerName": "Floating Menu: Menu Name",
    "$Name": "Menu Name",
    "$Config": { /* menu configuration */ },
    "§s": [ /* array of menu items */ ],
    "$Availability": 0  /* 0=everywhere, 1=mac, 2=ios */
  }
]
  • 767 - Menu (top level)
  • 773 - Standard Item (button with actions)
  • 774 - Submenu (contains nested items)
  • 775 - Slider
  • 776 - Text Field (value queryable via scripts)
  • 777 - Back Button (for submenus)
  • 778 - WebView (displays HTML from §Text)
  • 800 - Trackpad widget
  • 801 - Row Breaker
  • 802 - Column Breaker
  • 810 - Text Area (value queryable via scripts)
  • 811 - Floating Menu Reference

Core Properties

  • ©TriggerType: 767 for menu
  • ©UUID: Unique identifier
  • ©Enabled: 1 to enable
  • $Name: Display name
  • $Config: Configuration object
  • §s: Array of menu items
  • $Availability: 0=everywhere, 1=mac, 2=ios, 3=iphone, 4=ipad
  • ©Order: Display order
  • ©LastUpdatedAt: Timestamp
  • ©AppBundleIdentifier: App-specific bundle ID
  • ©AppName: App-specific name

Item Properties

  • ©TriggerType: Item type (773, 774, etc.)
  • ©TriggerParentUUID: Parent menu's UUID
  • ©UUID: Unique identifier
  • ©Enabled: 1 to enable
  • ©TriggerName: Display name
  • $Config: Item configuration
  • §Actions: Array of actions

Positioning & Layout

  • $PositioningType: 0=freeMove, 1=fixedPosition, 2=menubarStatusItem
  • $PositionRelativeTo: 0=focusedWindow, 1=screenWithMouse, 3=focusedScreen, 7=mousePosition, 8=builtin, 11=notch, 12=focusedMenubar, 19=screenWithDock, 20=greenWindowButton, 21=hoveredFloatingMenuItem, 22=specificFloatingMenu, 23=dock
  • $AnchorMenu: 0=topLeft, 1=topRight, 2=bottomLeft, 3=bottomRight, 4=center, 5=topEdgeCenter, 6=rightEdgeCenter, 7=bottomEdgeCenter, 8=leftEdgeCenter
  • $AnchorRelation: Same values as $AnchorMenu
  • $OffsetX/$OffsetY: Position offset
  • $OffsetXUnit/$OffsetYUnit: 0=absolute, 1=menu%, 2=referenceFrame%
  • $PositionDynamicVariable: Variable for dynamic positioning
  • $ScreenUUID: Specific screen UUID

Layout Direction

  • $LayoutDirection: 0=fillRow, 1=fillColumn, 2=fillRowFixed, 3=fillColumnFixed, 4=absoluteScrollable, 5=absoluteFixed, 6=verticalOneColumn, 7=horizontalOneRow, 8=circular
  • $VerticalSpacing: Vertical spacing (pixels)
  • $HorizontalSpacing: Horizontal spacing (pixels)

Size

  • $SizingBehavior: 0=zero, 1=fixed, 2=variable, 3=content
  • $FrameWidth/$FrameHeight: Menu dimensions
  • $FrameMaxWidth/$FrameMaxHeight: Maximum dimensions
  • $FrameWidthVariable/$FrameHeightVariable: Variable names for dynamic sizing

Hover Behavior

  • $ResizeOnHover: 1 to enable hover resize
  • $SizingBehaviorHover: Hover sizing mode
  • $FrameWidthHovered/$FrameHeightHovered: Hovered dimensions
  • $FrameWidthVariableHover/$FrameHeightVariableHover: Hover variables
  • $HoverKeepExpanded: 1 to stay expanded
  • $GoBackToNonHoveredSizeAfter: Seconds to collapse
  • $HoverExpansionDirection: 0=rightUp, 1=leftUp, 2=rightDown, 3=leftDown, 4=leftRightDown, 5=leftRightUp, 6=upDownLeft, 7=upDownRight
  • $HoverStartAnimationDuration/$HoverEndAnimationDuration: Animation durations
  • $HoverDelay: Hover activation delay
  • $HoverWhileMousePressed: 1 to hover while dragging
  • §AnimateHover: 1 to animate hover

Window Properties

  • $WindowLevel: 3=floating, 0=normal, 20=dock, 24=mainMenu, -1=custom
  • $WindowLevelManual: Custom level when $WindowLevel=-1
  • $WindowResizable: 1 to allow resizing
  • $TitleBarStyle: 0=noTitleBar, 1=standard, 2=overlayContent, 3=transparent
  • $ClickThroughEmptyParts: 1 to click through empty areas
  • $ClickThroughEverywhere: 1 to click through everywhere
  • $ShowDockIconWhileVisible: 1 to show dock icon
  • $StealKeyboardFocusOnShow: 1 to steal focus

Visibility

  • $Visibility: 0=onLaunch, 1=viaAction
  • $OpacityActive/$OpacityInactive: Opacity 0-1
  • $AlwaysUseLightMode: 1 to force light mode
  • $KeepCached: 1 to keep cached when hidden
  • $AnimateShow: 1 to animate appearance
  • $AnimateShowDuration: Animation duration
  • $AnimateChanges: 1 to animate property changes

Visibility Conditions

  • $ShowIfWindowTitleIsNotEmpty: 1 to check
  • $ShowIfWindowTitleContains: String to match
  • $ShowIfAppNameContains: String to match
  • $ShowIfWindowTitleContainsNot: String to exclude
  • $ShowIfAppNameContainsNot: String to exclude
  • $ShowIfWindowLevelEqualsEnabled: 1 to enable check
  • $ShowIfWindowLevelEquals: Window level value
  • $DoNotShowInFullscreen: 1 to hide in fullscreen
  • $OnlyShowOnSpaces: Comma-separated space numbers

Interaction

  • $CloseOnOutsideClick: 1 to close on outside click
  • $CloseOnMoveMouseAway: 1 to close when mouse leaves
  • $CloseOnKeyboardInput: 1 to close on keyboard
  • $CloseAfterAction: 1 to close after action
  • $DisableDrag: 1 to disable dragging

Modifiers

  • §sUseModifierModes: true if items use modifiers
  • $ModifierMode: -1=none, 0=showIfPressed, 1=showIfOthersPressed, 2=showIfNonePressed, 3=showAlways, 4=showIfPressedShowNonModified, 5=showIfAtLeast, 6=dontShowIfPressed
  • $ModifierKeys: Bitmask of modifier keys

Scripting

  • §ScriptActive: 1 to enable script
  • $ScriptSettings: Script configuration object
  • $ValueChangedScriptSettings: Script for value changes
  • $ScriptRunOnMenuHover: 1 to run on menu hover
  • $ScriptRunOnItemHover: 1 to run on item hover
  • $ScriptAlwaysRunOnFirstLoad: 1 to run on load
  • $ScriptUpdateInterval: Update interval in seconds
  • $ScriptAlwaysRunOnAppear: 1 to run on appear

Script Configuration ($ScriptSettings)

  • ©ScriptType: 0=appleScript, 1=jax, 2=scpt, 3=realJavaScript, 4=shortcut
  • ©AppleScriptString: Script content
  • ©ScriptFunctionToCall: Function name
  • ©ScriptShortcutName: Shortcut name
  • ©ScriptLocation: 0=inline, 1=preset, 2/3=external
  • ©ScriptExternalPath: External script path
  • ©JavaScriptUseIsolatedContext: true for isolated JS

Item Properties

Visibility

  • §Disabled: 1 to disable
  • §VisibleWhileActive: 1 when menu hovered
  • §VisibleWhileInactive: 1 when not hovered
  • §VisibleIfVariableIsTrue: Variable name
  • §VisibleIfVariableIsFalse: Variable name
  • §DisplayOrder: Custom order value

Size & Position

  • §MinWidth/§MaxWidth: Width constraints
  • §MinHeight/§MaxHeight: Height constraints
  • §PaddingLeft/Right/Top/Bottom: Internal padding
  • §MarginLeft/Right/Top/Bottom: External margin
  • §PositioningMode: 1 for manual positioning
  • §X/§Y: Manual position
  • §OffsetX/§OffsetY: Position offset

Text

  • $AttributedText: RTF-encoded text
  • $AttributedTextDark: Dark mode RTF text
  • §Text: Plain text/HTML (for webviews)
  • $ElementIdentifier: Scripting identifier
  • $ElementTooltip: Tooltip text
  • §ShowIdentifierAsTooltip: 1=identifier, 2=tooltip
  • $TextMinimumScaleFactor: Min scale 0-1
  • $TextOffsetX/$TextOffsetY: Text offset
  • §FontColor/§FontColorHover: Font colors

Background

  • §BackgroundType: 0=none, 1=data, 2=sfsymbol, 3=file, 4=color, 5=linearGradient, 6=radialGradient, 7=presetFile, 8=internal
  • §BackgroundColor/2/3/4: Gradient colors "R,G,B,A"
  • §BackgroundColorHover: Hover background
  • §BackgroundImageData: Base64 image data
  • §BackgroundImagePresetPath: Preset path
  • §BlurredBackground: 1 for blur effect
  • §BackgroundTypeDark/ColorDark/etc.: Dark mode variants

Borders

  • §BorderWidth: Border width
  • §BorderColor: Border color "R,G,B,A"
  • §BorderColorHover: Hover border color
  • §BorderDashed: 1 for dashed
  • §CornerRadius: Corner radius
  • §CornerRadiusCorners: 0=all, 1=left, 2=right, 3=top, 4=bottom, 5=topLeft, 6=topRight, 7=bottomRight, 8=bottomLeft
  • Dark mode variants with Dark suffix

Shadow

  • §ShadowEnabled: 1 to enable
  • §ShadowColor/ColorHover: Shadow colors
  • §ShadowRadius: Shadow radius
  • Dark mode variants with Dark suffix

Icons/Images

  • §IconType: Same as §BackgroundType
  • §IconPosition: 0=left, 1=top, 2=right, 3=bottom, 4=center, 5=none
  • §Image: Base64 image data
  • §IconPresetPath: Preset icon path
  • §ResizeImage: 0=fit, 1=none, 2=fixed, 3=fitNew
  • §ImageChangeColor: 1 to tint with color
  • §ImageWidth/Height: Image dimensions
  • §ImageOffsetX/Y: Image offset
  • §ImagePadding: Image padding

SF Symbols

  • §SFSymbolName: Symbol name
  • §SFSymbolWeight: Symbol weight
  • §SFSymbolStyle: 0=monochrome, 1=hierarchical, 2=palette, 3=multiColor
  • §IconColor1/2/3: Symbol colors
  • §IconColor1Hover/2Hover/3Hover: Hover colors
  • Dark mode variants with Dark suffix

WebView Properties

  • §WebViewPlain: 1 for plain HTML
  • §UserAgent: Custom user agent
  • §UserScript: Script on load
  • §UserScriptOnvisible: Script on visible
  • §WebViewFocusTextField: 1 to auto-focus
  • §WebViewFocusTextFieldWithID: Field ID
  • §KeepActiveInBackground: 1 to keep active
  • §SystemBrowserPrefix: External URL prefixes
  • §SystemBrowserPrefixOverrides: Override prefixes
  • §SystemBrowserClosesMenu: 1 to close on external

Circular Layout

  • $HoverOnWholePizzaSlice: 1 for whole wedge hover
  • $HighlightPizzaSlice: 1 to highlight wedge
  • $PlaceFirstItemAtCenter: 1 to center first item
  • §PizzaSliceBackgroundColor: Wedge background
  • §PizzaSliceBorderColor: Wedge border
  • §PizzaSliceBorderWidth: Border width
  • Dark mode variants with Dark suffix

Interaction

  • §Focused: 1 for initial focus
  • §ScrollEnabled: 1 to enable scroll
  • §ScrollDelta: Touch scroll delta
  • §ScrollDeltaNormalMouse: Mouse scroll delta

Widget Properties

  • $WidgetStringStringDictionary: String dictionary
  • $WidgetStringIntDictionary: Integer dictionary
  • $WidgetNowPlayingPauseBehavior: 0=icon, 1=albumcover

Miscellaneous

  • $UseStyleForSubmenu: 1 to inherit parent style
  • $OverrideGlobalMenuSetttings: 1 to override globals
  • $CreatedViaScript: 1 if script-created
  • $OnlyCopyOpenCategories: 1 for categories
  • §Extras: Extra data (future use)
  • ©AnimateUUID: Animation trigger UUID
  • ©LastChangeUUID: Last change UUID

Actions (§Actions)

"§Actions": [{
  "©PredefinedActionType": 5,
  "©PredefinedActionName": "Mission Control",
  "©Enabled": 1,
  "©Order": 0
}]

Example: Complete Menu

[{
  "©TriggerType": 767,
  "©UUID": "menu-uuid",
  "©Enabled": 1,
  "$Name": "Example Menu",
  "$Config": {
    "$PositioningType": 1,
    "$PositionRelativeTo": 3,
    "$AnchorMenu": 1,
    "$AnchorRelation": 1,
    "$FrameWidth": 220,
    "$FrameHeight": 300,
    "$OpacityActive": 1,
    "$OpacityInactive": 0.8,
    "$LayoutDirection": 0,
    "$VerticalSpacing": 5,
    "$HorizontalSpacing": 5,
    "$WindowLevel": 3,
    "$CloseAfterAction": 1
  },
  "§s": [{
    "©TriggerType": 773,
    "©TriggerParentUUID": "menu-uuid",
    "©UUID": "item-uuid",
    "©Enabled": 1,
    "$Name": "Click Me",
    "$Config": {
      "§VisibleWhileActive": 1,
      "§VisibleWhileInactive": 1,
      "§MinWidth": 100,
      "§MinHeight": 50,
      "§BackgroundType": 4,
      "§BackgroundColor": "90, 180, 240, 255",
      "§BackgroundColorHover": "120, 200, 255, 255",
      "§CornerRadius": 10,
      "§BorderWidth": 2,
      "§BorderColor": "255, 255, 255, 128",
      "$AttributedText": "{\\rtf1 Click Me}",
      "§IconType": 2,
      "§SFSymbolName": "hand.tap",
      "§IconColor1": "255, 255, 255, 255"
    },
    "§Actions": [{
      "©PredefinedActionType": 5,
      "©PredefinedActionName": "Mission Control"
    }]
  }]
}]

Color Format

Colors use "R, G, B, A" format (0-255): "255, 0, 0, 255" = opaque red

Import Method

ai.create_bettertouchtool_trigger(json: theJSONAsString)

results matching ""

    No results matching ""