This bar project aims to create a highly flexible, customizable, fast and powerful status bar replacement for users that like playing around with
shell scripts.
More example setups here.
Table of Contents
=================
* [Table of Contents](#table-of-contents)
* [Features](#features)
* [Installation](#installation)
* [Stable Version](#stable-version)
* [Plugins and Fonts](#plugins-and-fonts)
* [Global configuration of the bar](#global-configuration-of-the-bar)
* [Items and their properties](#items-and-their-properties)
* [Adding items to sketchybar](#adding-items-to-sketchybar)
* [Changing item properties](#changing-item-properties)
* [Changing the default values for all further items](#changing-the-default-values-for-all-further-items)
* [Components -- Special Items with special properties](#components----special-items-with-special-properties)
* [Data Graph -- Draws an arbitrary graph into the bar](#data-graph----draws-an-arbitrary-graph-into-the-bar)
* [Space -- Associate mission control spaces with an item](#space----associate-mission-control-spaces-with-an-item)
* [Item Bracket -- Group Items in e.g. colored sections](#item-bracket----group-items-in-eg-colored-sections)
* [Item Alias -- Mirror items of the original macOS status bar into sketchybar](#item-alias----mirror-items-of-the-original-macos-status-bar-into-sketchybar)
* [Popup Menus](#popup-menus)
* [Batching of configuration commands](#batching-of-configuration-commands)
* [Events and Scripting](#events-and-scripting)
* [Creating custom events](#creating-custom-events)
* [Triggering custom events](#triggering-custom-events)
* [Forcing all shell scripts to run and the bar to refresh](#forcing-all-shell-scripts-to-run-and-the-bar-to-refresh)
* [Querying](#querying)
* [Bar Properties](#bar-properties)
* [Item Properties](#item-properties)
* [Default Properties](#default-properties)
* [Event Properties](#event-properties)
* [Item Reordering](#item-reordering)
* [Moving Items to specific positions](#moving-items-to-specific-positions)
* [Item Cloning](#item-cloning)
* [Renaming Items](#renaming-items)
* [Removing Items](#removing-items)
* [Performance optimizations](#performance-optimizations)
* [Credits](#credits)
## Features
* Performance friendly
* No accessibility permissions needed
* As many widgets as you like at any of the three positions: left, center, right
* Popup Menus
* Associate widgets to certain displays or spaces, to show specific information on the relevant screens/displays
* The widgets are highly customizable with settings for different fonts, colors, icon paddings, label paddings, etc. for each individual element
* Display items from the default menu bar and configure them in sketchybar
* Draw arbitrary graphs in the bar with external data provider scripts that push the data into the graph
* Overlay as many graphs as wanted, like system cpu usage and user cpu usage in one figure
* Individual refresh frequencies for each widget
* Let items subscribe to system events (e.g. space changed, etc.) for their refresh action
* Create custom events and trigger them externaly
* "click" events for the widgets, where a script can be specified to run on a mouse click
* Offset the bar from its original location, rounded corners and background blur
* Batch configuration messages for easy configuration
The configuration of the bar takes place in a confiuration file where almost everything can be configured.
Bascially, the bar itself is a rectangle that can hold arbitrarily many *items*, which can be configured to do awesome stuff.
An *item* will occupy a space in the bar and can be equipped to show an *icon* and a *label*. The *icon* and *label* can be changed through
*scripts* that can be attached to the *item*. It is also possible to *subscribe* an *item* to certain *events* for their *script* execution action,
which makes very powerful items possible. Additionally, an *item* can be assigned a *click_script*, which executes on a mouse click.
Furthermore, an *item* can be assigned to mission control spaces or displays, such that they only show on a certain space or display, which makes multi-desktop configuration
of the bar possible and opens the possibility to create individualized bar configuration on a per display and per space level.
These simple ingredients make *items* almost endlessly customizable and can be used to display arbitrary information and perform useful actions. For some examples see my sketchybarrc and
the plugins folder.
Some special features can not be accomplished with a simple *item*, this is where the *components* come into play. They basically are *items* with
extra steps. They contain all the properties a regular item does, but they can do specialized tasks a simple item can not. For example, there
is a *graph* component, which can be used to display graphs in the bar.
For more details on how the configuration works, see the Configuration section below.
## Installation
### Stable Version
```bash
brew tap FelixKratz/formulae
brew install sketchybar
```
Do not forget to copy the example configuration files to your home directory (the brew installation specific commands are listed in the caveats section after the brew install is finished).
Run the bar via
```bash
brew services start sketchybar
```
### Plugins and Fonts
When you use additional plugins, make sure that they are referenced in the rc with the correct path and that they are made executable via
```bash
chmod +x name/of/plugin.sh
```
The default plugin folder is located in `~/.config/sketchybar/plugins`.
All plugins must work with absolute paths because relative paths will not be resolved correctly.
Have a look at the [discussion](https://github.com/FelixKratz/SketchyBar/discussions/12) about plugins and share your own if you want to.
You should of course vet the code from all plugins before executing them to make sure they are not harming your computer.
If you have problems with missing fonts you might need to install the Hack Nerd Font:
```bash
brew tap homebrew/cask-fonts
brew install --cask font-hack-nerd-font
```
## Global configuration of the bar
For an example configuration see the supplied default *sketchybarrc*. The configuration file resides in `~/.config/sketchybar/`, where everything can be freely configured. It is also possible to play around with properties in a terminal and change them while the bar is running, once you find a fitting value you can include it in the `sketchybarrc` file such that the configuration is restored on restart. The global bar properties can be configured by invoking:
```bash
sketchybar --bar = ... =
```
where the settings currently are:
* *position*: the position of the bar on the screen, either *top* or *bottom*
* *height*: the height of the bar in points
* *margin*: the screen margin around the bar
* *y_offset*: the y-offset in points from the default position
* *corner_radius*: the corner radius of the bar
* *border_width*: the width of the bars border
* *border_color*: the color of the bars border
* *blur_radius*: the blur radius to be applied to the background of the bar
* *padding_left*: padding on the left before first item
* *padding_right*: just as padding_right
* *color*: the color of the bar
* *display*: on which display to show bar (*main* or *all*)
* *hidden*: hides and unhides the bar, for hotkey toggling of the bar (*on*, *off*, *toggle*; optional: ** or *current*)
* *topmost*: draws sketchybar on top of *everything* (even the default menu bar) (*on*, *off*, *toggle*, default: *off*)
* *font_smoothing*: wheter fonts should be smoothened (*on*, *off*, *toggle*, default: *off*)
* *shadow*: if the bar should draw a shadow (*on*, *off*, *toggle*, default: *off*)
## Items and their properties
Items are the main building blocks of sketchybar and can be configured in a number of ways. Items have the following basic structure:
### Adding items to sketchybar
```bash
sketchybar --add item
```
where the *name* should not contain whitespaces, it can be used to further configure the item, which is covered later.
The *position* is the placement in the bar and can be either *left*, *right* or *center*. The items will appear in the bar in the ordered
in which they are added.
### Changing item properties
```bash
sketchybar --set = ... =
```
where the *name* is used to target the item with this name.
(The *name* can be a regular expression inside of two '/': */\/*)
A list of properties available to the *set* command is listed below (components might have additional properties, see the respective component section for them):
Geometry Properties:
* *position*: Overrides the position set in the *add* command (*left*, *right*, *center*)
* *associated_space*: on which space to show this item (can be multiple, not specifying anything will show item on all spaces)
* *associated_display*: on which displays to show this item (can be multiple, not specifying anything will show item on all displays)
* *width*: overrides the width of the item (useful for items which frequently change in width and thus move all other items) (values: width in points and *dynamic*)
* *y_offset*: the vertical offset of this item (default: 0)
Icon properties:
* *icon*: the icon of the item
* *icon.font*: the font for the icon
* *icon.color*: the color of the icon
* *icon.highlight_color*: the highlight color of the icon (e.g. for active space icon)
* *icon.padding_left*: left padding of icon (default: 0)
* *icon.padding_right*: right padding of icon (default: 0)
* *icon.highlight*: wether the icon is highlighted with the *icon_highlight_color* (values: *on*, *off*, *toggle*, default: *off*)
* *icon.drawing*: If the icon should be drawn into the bar (values: *on*, *off*, *toggle*, default: *on*)
* *icon.y_offset*: the vertical offset of the icon (default: 0)
* *icon.width*: Used to make the icon have a fixed custom width given in points (default: *dynamic*)
* *icon.align*: Used to align icons when they have a fixed width (values: *center*, *left*, *right*, default: *left*)
* *icon.background.\*: all background properties are also available for the icon
* *icon.shadow.\*: all shadow properties are available for the icon
Label properties:
* *label*: the label of the item
* *label.font*: the font for the label
* *label.color*: the color of the label
* *label.highlight_color*: the highlight color of the label (e.g. for active space icon)
* *label.padding_left*: left padding of label (default: 0)
* *label.padding_right*: right padding of label (default: 0)
* *label.highlight*: wether the label is highlighted with the *label_highlight_color* (values: *on*, *off*, *toggle*, default: *off*)
* *label.drawing*: If the icon should be drawn into the bar (values: *on*, *off*, *toggle*, default: *on*)
* *label.y_offset*: the vertical offset of the label (default: 0)
* *label.width*: Used to make the label have a fixed custom width given in points (default: *dynamic*)
* *label.align*: Used to align labels when they have a fixed width (values: *center*, *left*, *right*, default: *left*)
* *label.background.\*: all background properties are also available for the label
* *label.shadow.\*: all shadow properties are available for the label
Background properties:
* *background.drawing*: wether the item should draw a background (values: *on*, *off*, *toggle*, default: *off*)
* *background.color*: draws a rectangular background for this item in the given color (this automatically activates *draws_background*)
* *background.height*: the height of the background, the background will always be centered vertically around the center of the item
* *background.border_color*: the color of the backgrounds border
* *background.corner_radius*: the corner radius of the items background (default: 0)
* *background.border_width*: the border width of the items background (default: 0)
* *background.padding_left*: the left padding applied around the background of the item (default: 0)
* *background.padding_right*: the right padding applied around the background of the item (default: 0)
* *background.shadow.\*: all shadow properties are available for the backgrounds
Scripting properties:
* *update_freq*: time in seconds between script executions
* *script*: a script to run every *update_freq* seconds
* *click_script*: script to run when left clicking on item (Note: This is a shortcut for implemeting it via the *mouse_clicked* event)
* *cache_scripts*: If the scripts should be cached in RAM or read from disc every time (values: *on*, *off*, *toggle*, default: *off*)
* *updates*: If and when the item updates e.g. via script execution (values: *on*, *off*, *toggle*, *when_shown*, default: *on*)
Drawing properties:
* *drawing*: If the item should be drawn into the bar (values: *on*, *off*, *toggle*, default: *on*)
* *lazy*: Changes do not trigger a redraw of the bar, item is refreshed when the bar is redrawn anyways (values: *on*, *off*, *toggle*, default: *off*)
Shadow properties:
* *shadow.drawing*: If the shadow should be drawn (values: *on*, *off*, *toggle*, default: *off*)
* *shadow.angle*: The angle of the shadow (between 0 and 360, default: 30)
* *shadow.distance*: The distance of the shadow (default: 5)
* *shadow.color*: The color of the shadow (default: 0xff000000)
### Changing the default values for all further items
It is possible to change the *defaults* at every point in the configuration. All item created *after* changing the defaults will
inherit these properties from the default item.
```bash
sketchybar --default = ... =
```
this works for all item properties.
It is also possible to reset the defaults via the command
```bash
sketchybar --default reset
```
## Components -- Special Items with special properties
Components are essentially items, but with special properties.
Currently there are the components (more details in the corresponding sections below):
* *graph*: showing a graph,
* *space*: representing a mission control space
* *bracket*: brackets together other items
* *alias*: a default menu bar item
### Data Graph -- Draws an arbitrary graph into the bar
```bash
sketchybar --add graph
```
Additional graph properties:
* *graph.color*: color of the associated graph
* *graph.fill_color*: optional property to override the automatically calculated fill color of the graph
* *graph.line_width*: sets the line width of the associated graph
Push data points into the graph via:
```bash
sketchybar --push
```
### Space -- Associate mission control spaces with an item
```bash
sketchybar --add space
```
The space component overrides the definition of the following properties and they must be set to correctly associate a mission control space with this item:
* *associated_space*: Which space this item represents
* *associated_display*: On which display the *associated_space* is shown.
The space component has additional variables available in *scripts*:
```bash
$SELECTED
$SID
$DID
```
where *$SELECTED* has the value *true* if the associated space is selected and *false* if the selected space is not selected, while
*$SID* holds the space id and *$DID* the display id.
By default the space component invokes the following script:
```bash
sketchybar --set $NAME icon.highlight=$SELECTED
```
which you can freely configure to your liking by supplying a different script to the space component:
```bash
sketchybar --set script=