From e74d09ce7f6ae737d152bc5f627313e3da13f37a Mon Sep 17 00:00:00 2001 From: Tommaso Negri Date: Wed, 12 Aug 2026 12:20:54 +0200 Subject: Revise README for features and configuration clarity --- README.md | 162 ++++++++++++++++++-------------------------------------------- 1 file changed, 46 insertions(+), 116 deletions(-) diff --git a/README.md b/README.md index d53548f..ab9fec3 100644 --- a/README.md +++ b/README.md @@ -28,153 +28,83 @@ Everything is explained so you can truly own the codebase and customise it as yo --- -## Quick start - -### Requirements - -- **macOS 26** or later -- **Swift 6.3** (bundled with Xcode or installed from [swift.org](https://swift.org)) -- **No other dependencies** — `bar` only needs Swift and the macOS SDK. - -### Install - -```shell -git clone https://github.com/paninihouse/bar.git -cd bar -make install -``` - -The binary is placed at `~/.local/bin/bar` by default. Set `PREFIX` to change the location: - -```shell -make install PREFIX=/usr/local/bin -``` - -> While iterating on your configuration, use `make run` to build and run in one step. - -### Run at login - -Create a launch agent so the bar starts when you log in: - -```xml - - - - - Label - house.panini.bar - ProgramArguments - ~/.local/bin/bar - RunAtLoad - - KeepAlive - - StandardOutPath - /tmp/bar/bar.log - StandardErrorPath - /tmp/bar/bar.err - - -``` - ---- - -## Configuration - -All configuration lives in `Sources/bar/Config.swift`: - -```swift -enum Config { - static let height: Double = 30 - static let position: Position = .top - - static let font: Font = .system(size: 14, weight: .regular, design: .monospaced) - - static let foreground: Color = .hex("#FFFFFF") - static let background: Color = .hex("#000000").opacity(0.75) - static let highlights: [Color] = [.blue, .purple] - - static let blocks: [Block] = [ - Block(name: "workspaces", placement: .left, command: "~/bin/workspaces"), - Block(name: "clock", placement: .right, command: "date '+%a %d, %H:%M:%S'", interval: 1), - ] -} -``` - -Edit the properties, rebuild with `make install`, and the bar updates immediately after restart. - -> Colors can be defined with hex codes: `Color.hex("#CDD6F4")` supports `#RGB`, `#RGBA`, `#RRGGBB`, and `#RRGGBBAA` formats. - ---- - ## Features -### Blocks and cells +### Simple configuration -Each **block** runs a shell command. Every line of stdout becomes one **cell** in the bar: +Define a **block** by specifying a name, placement, shell command, and an optional refresh interval: -```shell -echo "first cell" -echo "second cell" -``` - -Blocks can refresh on an interval or on demand via a Darwin notification (using `notifyutil`, which ships with macOS): - -```shell -notifyutil -p bar.touch. +```swift +static let blocks: [Block] = [ + Block(name: "spaces", placement: .left, command: "~/.local/scripts/bar/spaces.sh"), + Block(name: "app", placement: .left, command: "~/.local/scripts/bar/app.sh"), + Block(name: "mail", placement: .right, command: "~/.local/scripts/bar/mail.sh", interval: 10), + Block(name: "volume", placement: .right, command: "~/.local/scripts/bar/volume.sh"), + Block(name: "clock", placement: .right, command: "~/.local/scripts/bar/clock.sh", interval: 60), +] ``` -### Highlighting +### Intuitive shell scripting -Prefix a line with `&!` to apply a background color from the `highlights` array: +Populate the block by writing to `stdout`, hide it by exiting with `0`: ```shell -echo "&!1 workspace 1" # highlighted with highlights[0] -echo "workspace 2" # no highlight +if [[ -n $session ]]; then + echo $session +else + exit 0 +fi ``` ### Gestures -React to clicks and scrolls on any block. The block's command receives `BUTTON` or `SCROLL` environment variables: +React to clicks and scrolls with the `BUTTON` and `SCROLL` environment variables: ```shell case $BUTTON in (0) mpc toggle ;; (1) mpc stop ;; esac -``` - -### Hide and show -```shell -notifyutil -p bar.hide # hide all bars -notifyutil -p bar.show # show all bars +case $SCROLL in + (UP) increaseVolume ;; + (DOWN) decreaseVolume ;; +esac ``` -### Multi-screen +### Highlighting -A bar is created for every connected display at launch. All bars share the same configuration. +Prefix the output with `&!` to apply a background color from the `highlights` array (defined in Config): ---- +```shell +echo "&!1 $(date '+%a %d, %H:%M') " # highlighted with highlights[0] +``` -## Documentation +### Manual refresh -Full documentation is available at [https://docs.panini.house/bar](https://docs.panini.house/bar). -It covers installation, customisation, blocks, highlighting, gestures, refresh, patches, daemons and more. +Refresh a block at any time, regardless of its interval, by sending a standard **Darwin notification**: ---- +```shell +notifyutil -p bar.touch. +``` -## Patches +### Multi cell output -If you find `bar` too limited, you can extend it via **patches**. -They are minimal, focused diffs that you apply to the source and rebuild. +Every line of `stdout` becomes one **cell** in the block. +Great for building grouped content like a workspace indicator: -Browse the available patches in the [official documentation](https://docs.panini.house/bar/documentation/bar/patches). +```shell +for workspace in "${workspaces[@]}"; do + if [[ $workspace == $focused_workspace ]]; then + echo "&!2 $workspace " + else + echo "&!1 $workspace " + fi +done +``` --- -## Daemons - -Even if not directly part of `bar`, the repository contains a few daemons that you can use to refresh blocks on specific system events. +## Get started & Full documentation -Browse the available daemons in the [official documentation](https://docs.panini.house/bar/documentation/bar/daemons). +The full documentation, with a get started guide, is available at [https://docs.panini.house/bar](https://docs.panini.house/bar). -- cgit v1.2.3