diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 162 |
1 files changed, 46 insertions, 116 deletions
@@ -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 -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> -<plist version="1.0"> -<dict> - <key>Label</key> - <string>house.panini.bar</string> - <key>ProgramArguments</key> - <array><string>~/.local/bin/bar</string></array> - <key>RunAtLoad</key> - <true/> - <key>KeepAlive</key> - <true/> - <key>StandardOutPath</key> - <string>/tmp/bar/bar.log</string> - <key>StandardErrorPath</key> - <string>/tmp/bar/bar.err</string> -</dict> -</plist> -``` - ---- - -## 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.<block-name> +```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 `&!<level>` 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 `&!<level>` 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.<block-name> +``` -## 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). |