diff --git a/README.md b/README.md index 8942f81..58b128e 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,7 @@ Themes, widgets and popups, set up in the app or in plain JSON.
- - - StableBar with workspaces, the active app, the next meeting, CPU and memory use, the battery and the time. Today's agenda is open below the meeting. - +StableBar on the desktop: workspaces with their app icons, the active app, music, the next meeting, CPU and memory, the battery and the clock. It moves to another workspace and back. ## Features @@ -34,46 +31,63 @@ Themes, widgets and popups, set up in the app or in plain JSON. - **Every display.** Notch-aware placement, widgets per kind of screen and a separate bar for each screen setup. - **Scriptable.** The command line queries and edits the running bar and sends events from other tools. -## Themes +## Workspaces -The same bar in each theme that ships with StableBar. Choose one during setup, cycle through them on your own bar with **Try Themes…**, or get more from the [store](https://github.com/Seb-GRAF/stablebar-packages). +The workspaces widget shows each workspace and its apps from AeroSpace, yabai or OmniWM, and follows you as you switch. Without a window manager, it can show macOS Spaces. See [Built-in widgets](docs/widgets.md). - - - One bar shown in each theme that ships with StableBar - +The bar's workspaces widget switching between workspaces while the window below changes to each workspace's app ## Popups Any widget can open a popup. Build it from rows, columns, text, graphs, lists, buttons, sliders, toggles and search fields, filled with the widget's data. See [Custom popups](docs/popups.md). - - - Three popups: CPU and memory with a graph, today's agenda, and a panel with a slider, a toggle, a segmented control and a search field - +The pointer clicks the meeting, system and music widgets in turn, opening today's agenda, a CPU and memory graph, and the playing track with its controls -## Settings +## Themes -Change content, appearance and behavior without touching JSON. Settings saves to the same configuration file you can edit by hand, with undo and redo. See [Settings](docs/settings.md). +Six themes ship with StableBar, alongside Built-in. Choose one during setup, cycle through them on your own bar with **Try Themes…**, or get more from the [store](https://github.com/Seb-GRAF/stablebar-packages). **Save as Theme…** turns your own look into one. See [Themes](docs/themes.md). - - - The Theme section of StableBar Settings, with a preview of the bar, the theme gallery and the theme's colors - +The bar and its open agenda popup changing through each theme that ships with StableBar, then back to Built-in -## Install +## Edit the bar in place -1. Download `StableBar.dmg` from the [latest release](https://github.com/Seb-GRAF/StableBar/releases/latest). -2. Open it and drag StableBar to Applications. -3. Open StableBar. Setup walks you through a preset, a theme and a placement. +Choose **Edit Bar in Place** from the bar's right-click menu to arrange widgets on the bar itself: drag them between positions, remove them with **−** or add one with **+**. Changes save as you go, with undo. See [Settings](docs/settings.md). -With [Homebrew](https://brew.sh), `brew install --cask seb-graf/tap/stablebar` replaces the first two steps. +Editing the bar in place: the music widget is dragged from the right of the bar to its center, then Done restores the normal bar -StableBar needs macOS 14 or later on Apple silicon. Releases update themselves; choose the Beta track in **Settings → General → Updates** to get betas. See [Getting started](docs/getting-started.md). To remove StableBar, use **Settings → General → [Uninstall](docs/getting-started.md#uninstall)**, which also turns off the menu bar auto-hide that StableBar turned on. +## Any script is a widget + +A widget can run any command that prints text or a JSON object, refresh on a timer or on events, and open a popup with graphs, lists and controls. + +A two-line shell script that prints the disk usage is typed, and its output appears on the bar as a new widget + +```sh +#!/bin/sh +# ~/.config/stablebar/widgets/disk.sh +used=$(df -h / | awk 'NR == 2 { print $5 }') +printf '{"text":"%s","icon":"internaldrive"}' "$used" +``` + +```json +{ + "id": "disk", "type": "script", "position": "right", "interval": 300, + "command": "~/.config/stablebar/widgets/disk.sh" +} +``` -## Configure +[Create a widget](docs/create-a-widget.md) covers the output format, events and layouts. Share a widget as a [package](docs/packages.md). -Your bar lives in `~/.config/stablebar/config.json`. Setup and Settings save to it, and you can edit it yourself: StableBar applies the file when you save it, and keeps the last working bar if a change is invalid. The JSON schema gives editors completion and validation. +## Widget store + +**Settings → Packages → Store** lists widgets and themes from the [StableBar store](https://github.com/Seb-GRAF/stablebar-packages). Before anything runs, StableBar shows the commands, hosts and permissions a package uses. See [Packages and the store](docs/packages.md#store). + +The Store in Settings lists widget packages; getting the Weather package marks it installed + +## Settings or JSON + +Change content, appearance and behavior in Settings, with undo and redo, or edit the file it saves to. Your bar lives in `~/.config/stablebar/config.json`: StableBar applies the file when you save it, and keeps the last working bar if a change is invalid. The JSON schema gives editors completion and validation. See [Settings](docs/settings.md) and [Configuration](docs/configuration.md). + +In config.json the theme is changed from catppuccin to nord and saved, and the bar above switches to Nord; then it is changed back ```json { @@ -88,25 +102,15 @@ Your bar lives in `~/.config/stablebar/config.json`. Setup and Settings save to } ``` -## Write a widget - -A widget can run any command that prints text or a JSON object: +## Install -```sh -#!/bin/sh -# ~/.config/stablebar/widgets/disk.sh -used=$(df -h / | awk 'NR == 2 { print $5 }') -printf '{"text":"%s","icon":"internaldrive"}' "$used" -``` +1. Download `StableBar.dmg` from the [latest release](https://github.com/Seb-GRAF/StableBar/releases/latest). +2. Open it and drag StableBar to Applications. +3. Open StableBar. Setup walks you through a preset, a theme and a placement. -```json -{ - "id": "disk", "type": "script", "position": "right", "interval": 300, - "command": "~/.config/stablebar/widgets/disk.sh" -} -``` +With [Homebrew](https://brew.sh), `brew install --cask seb-graf/tap/stablebar` replaces the first two steps. -[Create a widget](docs/create-a-widget.md) covers the output format, events and layouts. Share a widget as a [package](docs/packages.md), or install others from the store in **Settings → Packages**. +StableBar needs macOS 14 or later on Apple silicon. Releases update themselves; choose the Beta track in **Settings → General → Updates** to get betas. See [Getting started](docs/getting-started.md). To remove StableBar, use **Settings → General → [Uninstall](docs/getting-started.md#uninstall)**, which also turns off the menu bar auto-hide that StableBar turned on. ## Documentation