This bar project aims to create a highly flexible, customizable and fast statusbar for users that like playing around with
shell scripts and want to make their statusbar show exactly the information they need for their workflow.
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* and *components*, 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* and *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.
This is an example setup (see more example setups [here](https://github.com/FelixKratz/SketchyBar/discussions/47)):
where I have my spaces and a Github indicator on the left. Not shown is the high memory warning which shows the process that is using high system memory on demand.
In the center I have a spotify indicator (only when music is playing) and on the right I have (not shown) a high cpu process indicator, as well as a cpu graph, a new mail counter and the current date.
* [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)
* [Batching of configuration commands](#batching-of-configuration-commands)
A list of properties available to the *set* command is listed below (components might have additional properties, see the respective component section for them):
* *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)
* *script*: a script to run every *update_freq* seconds
* *click_script*: script to run when left clicking on item (Note: This is also possible via the *mouse_clicked* event, see #subscribing-items-to-system-events-for-their-script-execution)
* *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*)
* *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 -m --push <name><datapoint>
```
### Space -- Associate mission control spaces with an item
```bash
sketchybar -m --add space <name><position>
```
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
if [ "$SELECTED" = "true" ]; then
sketchybar -m --set $NAME icon.highlight=on
else
sketchybar -m --set $NAME icon.highlight=off
fi
```
which you can freely configure to your liking by supplying a different script to the space component:
```bash
sketchybar -m --set <name> script=<pathtoscript>
```
For performance reasons the space script is only run on change.
### Item Bracket -- Group Items in e.g. colored sections
It is possible to bracket together items via the command (see [this](https://github.com/FelixKratz/SketchyBar/discussions/12#discussioncomment-1455842) discussion for an example):
The first item must always be the one listed earliest in the config. It is now possible to
set properties for the bracket, just as for any item or component. Brackets currently only support all background features.
E.g., if I wanted a colored background around *all* my space components (which are named *code*, *writing*, *reading* and *entertainment*) I would set it up like this:
this draws a white background below all my space components. I plan to expand the capability of item brackets significantly in the future.
### Item Alias -- Mirror items of the original macOS status bar into sketchybar
It is possible to create an alias for default menu bar items (such as MeetingBar, etc.) in sketchybar. The default menu bar can be set to autohide and this should still work.
Important: <br>
I highly recommend setting a wallpaper on all spaces that makes the default menu bar items appear in either the light or the dark theme consitently.
It is now possible to create an alias of a default menu bar item with the following syntax:
When an item is subscribed to these events the *script* is run and it gets passed the *$SENDER* variable, which holds exactly the above names, to distinguish between the different events.
It is thus possible to have a script that reacts to each event differently e.g. via a switch for the *$SENDER* variable in the *script*. I will soon create an example an link it here.
Where *$NAME* is the name of the item that has invoked the script and *$SENDER* is the reason why the script is executed.
### Creating custom events
This allows to define events which are triggered by a different application (see Trigger custom events). Items can also subscribe to these events for their script execution.
Optional: You can subscribe to the notifications sent to the NSDistributedNotificationCenter e.g.
the notification Spotify sends on track change: "com.spotify.client.PlaybackStateChanged" [example](https://github.com/FelixKratz/SketchyBar/discussions/12#discussioncomment-1455842), or the
notification sent by the system when a bluetooth device connected, or disconnected: *com.apple.bluetooth.state* ([example](https://github.com/FelixKratz/SketchyBar/discussions/12#discussioncomment-1465761))
where a new order can be supplied for arbitrary items. Only the specified items get reordered, by swapping them around, everything else stays the same. E.g. if you want to swap two items
*SketchyBar* can be configured to have a *very* small performance footprint. In the following I will highlight some optimizations that can be used to reduce the footprint further.
