Skip to content

Latest commit

 

History

History
108 lines (77 loc) · 14.4 KB

layout.md

File metadata and controls

108 lines (77 loc) · 14.4 KB

Displays and layout

Displays and notch placement

notchLeft ends before the notch and notchRight starts after it. bar.notchSpacing controls the gap on each side (16 by default). The notch comes from the screen's unobscured top areas; bar.notchWidth can override its width. Screen shares, screenshots and recordings leave the notch out, so widgets that blend into it, such as black groups beside it, show a gap there. bar.fillNotch: true paints the notch black behind the widgets: the notch hides it on the display, and captures show the bar as you see it. On screens without a notch, notchLeft, center and notchRight form one centered group, measured from the visible content. Hidden groups leave no gap. With a notch, center joins the right side, between notchRight and right.

Each widget accepts display: "all" (default), "active", "main", "builtIn", "external", "monitor" (landscape external screens), "vertical" (screens taller than they are wide), "notched", "unnotched", an array of these to show the widget on any of them, for example ["builtIn", "vertical"], or an array of screen numbers, for example [1, 2]. Numbers are one-based positions in NSScreen.screens, matching AeroSpace and SketchyBar; they can change when displays are rearranged. active follows the configured workspace source's focus. With AeroSpace, use aerospace list-monitors --format '%{monitor-name}|%{monitor-appkit-nsscreen-screens-id}' to list them. yabai and OmniWM display IDs are mapped to these screen numbers, independently of the window manager's display ordering, and so are macOS Spaces displays.

bar.displayScale, which scaled the whole bar on built-in or external displays, is retired: Settings no longer shows it, and files that set it keep their scale. To return to the normal size, remove displayScale from wherever it's set: the main file, an included file, a profile or a screen setup's own bar. To size the bar on one kind of screen, give that screen its own height under screens (see Screen setups).

bar.style accepts background, cornerRadius, borderColor, borderWidth and borderEdges. The border defaults to "bottom"; "all" draws all four edges just inside the visible strip, following its corners. The outline does not change panel size, window clearance or clicks. A notch or the system menu bar can obscure part of the top edge. bar.margin (0 by default) insets the bar's background and widgets from every edge of the bar, so a rounded bar.style floats below the top of the screen and in from its sides. The bar keeps its height, so the visible strip is height minus twice the margin. Scripts can return barStyle to change those properties; later widgets override earlier widgets when they set the same property.

Screen setups

A screen setup is a combination of connected screens: the laptop only, a monitor only, the laptop with a monitor, the laptop with a monitor and a vertical monitor, and so on. A vertical monitor is a screen taller than it is wide. Each setup can have its own bar, with its own widgets on each screen, size, theme and placement. StableBar switches bars when you connect or disconnect a screen.

Setups start with the shared bar, your main configuration. In Settings → Bar, the menu beside the screen thumbnails names the setup you are editing, and whether it uses the shared bar or its own, such as Laptop + monitor (connected) · shared bar. Open it and choose Give it its own bar. The same action is available in the Bar → Placement inspector. StableBar copies the shared bar into a file beside it, such as setup-laptop+monitor.json, and from then on everything you change while those screens are connected changes that bar only, except in Theme. Theme changes go to the shared bar and every setup's own bar, so they still show after you connect or disconnect a screen. To change the look of one bar only, choose This setup only, or Shared bar only while editing the shared bar, next to All setups at the top of Theme. One Undo reverses a change in every bar. While you edit a profile, Theme changes stay in the bar you're editing. Copy bar from starts the own bar from the shared bar or another setup's own bar instead. Use the shared bar again… moves its own bar to the Trash after confirmation.

The menu lists the connected setup, each connected kind of screen on its own, such as Laptop only, and every setup with its own bar, each marked own bar or shared bar. Choosing a setup that isn’t connected previews it: the bar on your screens shows that setup's bar and Settings edits it, so you can change the laptop alone while docked. Choosing the connected setup again, closing Settings, or connecting or disconnecting a screen returns to the connected setup. Each file is a normal configuration file: includes, packages and $CONFIG_DIR work as in the main file, and command-line changes go to the bar on the screens. Switching bars discards temporary command-line changes and clears Undo. Uninstalling a package version that another setup's bar uses is refused until you remove it from that bar.

Within a setup, select a screen-kind thumbnail in Bar, then use a widget’s eye control to show or hide it on that kind of screen. A widget's Shows on menu also offers the laptop, landscape monitors and vertical monitors, plus display rules. Screens of the same kind remain grouped and show the same widgets; the thumbnails do not select individual monitors of that kind. Specific display IDs remain editable as JSON. While editing the bar in place, a widget's context menu offers the same choices under Shows On.

Each kind of screen can also have its own layout, bar size and look. While another kind of screen is connected, moving a widget in Bar or on the bar itself moves it only on the selected kind of screen. In the Bar inspector, switch from Every screen to the selected screen to set its height, corner radius, insets, spacing, background, border, offset or margin. In Theme, switch to the selected screen to give it its own theme, appearance, colors, widget, popup and bar styles, Liquid Glass, presentation roles, workspace look and AeroSpace mode names. StableBar saves these under screens:

"screens": {
  "laptop": {
    "theme": { "id": "notch" },
    "tokens": { "accent": "#ff9f0aff" },
    "defaults": { "fontSize": 14 },
    "popupDefaults": { "cornerRadius": 10 },
    "bar": { "height": 32, "style": { "cornerRadius": 0 } },
    "layout": { "left": ["apple", "workspaces"], "center": [], "right": ["wifi", "clock"] }
  }
}

theme replaces the shared theme on that kind of screen, and tokens, defaults, popupDefaults, groupDefaults, roles, workspaceDefaults and modeAliases merge over the shared ones; active profiles still apply on top. bar accepts height, offset, belowMenuBar, margin, inset, spacing, background, notchWidth, notchSpacing, fillNotch, style, glass, appearance and popupOffset, merged over the shared bar. Each layout list names widget IDs, in order, for that position: left, notchLeft, center, notchRight or right. Widgets the layout doesn't list keep their own position after the listed ones, and IDs that are not present are skipped. Once a kind of screen has a layout, moves on it keep changing that layout, even when it is the only screen connected. A widget's own settings and content stay shared.

Right-click a screen thumbnail, or use its ⋯ button, to split or copy that screen's bar. Own layout and size for this screen saves the order it shows now as its layout; turning it off removes its screens entry so it follows the shared bar again. Copy from gives the screen another screen's widgets, order and bar size in one Undo step.

Adaptive layout and groups

Widgets keep their configured order within left, notchLeft, center, notchRight, and right. The center cluster shifts within the free space before anything overflows. On a notched screen, center widgets join the right side of the notch; neither side can use the other side's space.

Set priority on a widget to keep it visible longer; higher numbers win. The default is 0. When space runs out, lower-priority widgets move behind a More widgets button (⋯), drawn like the other widgets. On a notched screen, each side has its own button beside the widget nearest the notch, and among equal priorities the widgets next to the notch go first. Widgets in notchLeft and notchRight stay against the notch, and the button goes on their far side. Elsewhere one button follows the last widget, and equal priorities overflow from the end of the configuration first. Click the button to show those widgets in a popup, drawn as on the bar: their clicks, popups, workspaces and app menus work there, and app menus show all their titles. A popup opened there replaces the list under the button. Hover popups, tooltips and hover controls don't open in it. Widgets return automatically when space becomes available, and the bar animates them in and out with its motion. A widget that grows under the pointer, such as app menus that expand on hover, only takes free room: nothing hides or moves to make room for it. App menus that don't fit first move their last menus behind », down to the app name, and move behind ⋯ only after the other widgets of their priority.

Use "overflow": "never" for essential widgets. If these alone exceed the available width, their containers scroll horizontally so the full content remains reachable. This is useful for a required workspace list on a narrow display.

{
  "groups": {
    "system": {
      "style": {
        "background": "#202027",
        "paddingHorizontal": 4,
        "paddingVertical": 3,
        "borderColor": "#484850",
        "borderWidth": 1,
        "cornerRadius": 12,
        "spacing": 4
      }
    }
  },
  "widgets": [
    { "id": "app", "type": "activeApp", "position": "left", "style": { "minWidth": 80, "maxWidth": 200 } },
    { "id": "space", "type": "spacer", "position": "left" },
    { "id": "status", "type": "text", "text": "Ready", "position": "right", "group": "system" },
    { "id": "time", "type": "clock", "position": "right", "group": "system", "priority": 10 }
  ]
}

A named group has one shared background, padding, border and spacing. Members must use the same position; their first appearance places the group. To make one without editing the file, right-click a widget in Settings → Bar or while editing the bar in place and choose Group With the widget beside it. In Settings, the new group opens so you can choose its look; on the bar, choose Edit Group… for that. A group overflows as one unit, takes its highest member priority, and stays visible if any member sets overflow to never.

Every group starts from groupDefaults, then its own style, property by property. A theme drawn as pills sets its pill look there once, and the groups you make follow it too. Set it in Settings → Theme → Groups or Settings → Bar → Every group. Group With gives a new group its faint backdrop only while groupDefaults has no background; otherwise the group takes the shared look. A null in a group's style inherits the shared value, as a widget's does from defaults; for no background on one group, give it a transparent color such as #00000000.

"groupDefaults": { "background": "#8080802e", "cornerRadius": 14, "paddingHorizontal": 4 }

A group can also list its members, so widgets join it without a group of their own. A theme drawn as pills uses them to fill its pills while it's selected; under another theme, the widgets leave them.

"groups": {
  "clock":  { "style": { "background": "@token.accent" },        "members": [{ "type": "clock" }] },
  "status": { "style": { "background": "@token.surfaceRaised" }, "members": [{ "type": "battery" }, { "type": "network" }] },
  "media":  { "style": { "background": "@token.surfaceRaised" }, "members": [{ "id": "now-playing" }] }
}

Each selector names a widget type (aerospace counts as workspaces), a role, an id, or several of them, and a widget matches when it has every one. Use id for a package's widgets, whose IDs the package sets, such as now-playing; an id that matches no widget isn't an error, since the package may not be installed.

  • A widget's own group always wins, and the widgets that set one decide where their groups sit.
  • Each enabled widget without a group then joins the group that matches it best, in list order. If that group's widgets are in another position, it stays out. On a kind of screen with its own layout, the positions there decide.
  • A selector naming id beats one that doesn't, then the selector naming more keys wins. On a tie, the group whose ID sorts first wins.

Members gather where the first one appears, as in any group. Moving one moves the whole group, and StableBar saves only positions and order, never the membership. To keep widgets out of a theme's group, set its members in your main file or in a profile with "when": { "theme": "<id>" }: your list replaces the theme's. Narrow it, as with [{ "type": "clock", "role": "time" }], or empty it with [] or null.

Set flare in a group's style to square its top corners and curve them outward past its sides with that radius, the way the MacBook notch meets the top of the screen. cornerRadius then rounds only the bottom corners; 0 keeps the top corners square without a curve. Use it on a group that reaches the top of the bar, such as a black group beside the notch or a notch of your own on another display. The curves draw into the spacing beside the group. A flared group draws no border.

"groups": { "notch": { "style": { "background": "#000000", "cornerRadius": 10, "flare": 8 } } }

A spacer uses the remaining width. Place it between widgets to separate them without choosing a fixed gap. Widget styles accept minWidth and maxWidth in addition to a fixed width.

The interactive example combines groups, an expanding spacer, constrained text that rolls to the new app's name, and all popup controls. Copy both files from examples/interactive into your configuration directory. Its controls update demo state in .control-state next to the configuration; they do not alter macOS settings. The app list opens the selected application.