2021-12-20 18:30:45 +00:00
< p align = "center" >
< img src = "images/Sbar.svg" / >
< / p >
2021-12-20 18:37:25 +00:00
2021-12-20 23:07:38 +00:00
< p align = "center" >
< a href = "https://opensource.org/licenses/" > < img src = "https://img.shields.io/badge/License-GPL%20v3-blue.svg" > < / a >
2021-12-22 18:35:22 +00:00
< a href = "https://github.com/FelixKratz/SketchyBar/releases" > < img src = "https://img.shields.io/github/v/release/FelixKratz/SketchyBar.svg?style=flat&color=orange" / > < / a >
2021-12-22 18:32:09 +00:00
< a href = "https://github.com/FelixKratz/SketchyBar/releases" > < img src = "https://img.shields.io/github/commits-since/FelixKratz/SketchyBar/latest.svg?color=orange" > < / a >
2021-12-20 23:09:05 +00:00
< a href = "https://en.wikipedia.org/wiki/Free_and_open-source_software" > < img src = "https://img.shields.io/badge/FOSS-100%25-green.svg?style=flat" > < / a >
2021-12-20 23:07:38 +00:00
< / p >
2021-12-20 18:38:52 +00:00
2021-12-20 23:07:38 +00:00
< p align = "center" >
2021-12-20 18:36:07 +00:00
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.
2021-12-20 23:07:38 +00:00
< / p >
2021-12-20 18:36:07 +00:00
2021-12-22 18:32:09 +00:00
< p align = "center" >
2021-12-22 20:02:59 +00:00
More example setups < a href = "https://github.com/FelixKratz/SketchyBar/discussions/47" > here< / a > .
2021-12-22 18:32:09 +00:00
< / p >
2021-08-24 09:26:07 +00:00
2021-09-15 18:22:26 +00:00
Table of Contents
=================
2021-10-21 23:46:19 +00:00
* [Table of Contents ](#table-of-contents )
2021-12-20 23:07:38 +00:00
* [Features ](#features )
2021-09-15 18:22:26 +00:00
* [Installation ](#installation )
* [Stable Version ](#stable-version )
* [Plugins and Fonts ](#plugins-and-fonts )
2021-10-21 23:46:19 +00:00
* [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 )
2021-09-15 18:22:26 +00:00
* [Changing the default values for all further items ](#changing-the-default-values-for-all-further-items )
2021-10-21 23:46:19 +00:00
* [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 )
2021-12-20 23:07:38 +00:00
* [Popup Menus ](#popup-menus )
2021-10-21 23:46:19 +00:00
* [Batching of configuration commands ](#batching-of-configuration-commands )
* [Events and Scripting ](#events-and-scripting )
2021-09-15 18:22:26 +00:00
* [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 )
2021-10-10 16:14:29 +00:00
* [Querying ](#querying )
* [Bar Properties ](#bar-properties )
* [Item Properties ](#item-properties )
* [Default Properties ](#default-properties )
2021-11-01 13:39:10 +00:00
* [Event Properties ](#event-properties )
2021-10-26 15:42:26 +00:00
* [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 )
2021-10-21 23:46:19 +00:00
* [Performance optimizations ](#performance-optimizations )
2021-09-20 09:49:09 +00:00
* [Credits ](#credits )
2021-12-20 23:07:38 +00:00
## Features
* Performance friendly
* No accessibility permissions needed
2022-01-24 22:00:25 +00:00
* Fully scriptable
* Highly configurable
* Supports drawing native macOS menu bar applications
* Powerful event system (items can subscribe to many system events)
2021-12-20 23:07:38 +00:00
* Popup Menus
2022-01-24 22:00:25 +00:00
* Mouse Support
* Many visual features
* Support for graphs
* Per display and per space individualization
2021-12-20 23:07:38 +00:00
The configuration of the bar takes place in a confiuration file where almost everything can be configured.
2022-01-24 22:00:25 +00:00
Basically, the bar itself is a rectangle that can hold arbitrarily many *items* , which can be configured to do awesome stuff.
2021-12-20 23:07:38 +00:00
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,
2022-01-24 22:00:25 +00:00
which makes very powerful items possible.
2021-12-20 23:07:38 +00:00
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.
2022-01-24 22:00:25 +00:00
For more details on how the configuration works, see the configuration section below.
2021-12-20 23:07:38 +00:00
2021-08-14 00:21:10 +00:00
## Installation
2021-09-01 11:22:39 +00:00
### Stable Version
```bash
brew tap FelixKratz/formulae
brew install sketchybar
```
2021-12-10 09:03:04 +00:00
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
2021-09-01 11:22:39 +00:00
```bash
2021-09-01 12:07:45 +00:00
brew services start sketchybar
2021-09-01 11:22:39 +00:00
```
2021-09-01 13:39:22 +00:00
2021-09-01 11:22:39 +00:00
### Plugins and Fonts
2021-12-19 21:57:39 +00:00
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
2021-08-14 11:29:00 +00:00
```bash
chmod +x name/of/plugin.sh
```
2021-12-24 15:24:59 +00:00
The default plugin folder is located in `~/.config/sketchybar/plugins` .
2021-12-25 00:01:00 +00:00
All plugins must work with absolute paths because relative paths will not be resolved correctly.
2021-09-02 18:42:11 +00:00
Have a look at the [discussion ](https://github.com/FelixKratz/SketchyBar/discussions/12 ) about plugins and share your own if you want to.
2021-10-15 13:01:42 +00:00
You should of course vet the code from all plugins before executing them to make sure they are not harming your computer.
2021-08-14 00:21:10 +00:00
2021-08-14 20:58:01 +00:00
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
```
2021-10-21 21:32:44 +00:00
## Global configuration of the bar
2021-12-24 15:24:59 +00:00
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:
2021-09-11 21:22:51 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --bar < setting > =< value > ... < setting > =< value >
2021-09-06 23:51:46 +00:00
```
2022-01-24 22:00:25 +00:00
where possible settings are:
2022-04-16 15:48:14 +00:00
| \<setting\> | \<value\> | default | description |
| :-------: | :------: | :-------: | ----------- |
| `color` | `<argb_hex>` | `0x44000000` | Color of the bar |
| `border_color` | `<argb_hex>` | `0xffff0000` | Color of the bars border |
| `position` | `top` , `bottom` | `top` | Position of the bar on the screen |
| `height` | `<integer>` | `25` | Height of the bar |
| `margin` | `<integer>` | `0` | Margin around the bar |
| `y_offset` | `<integer>` | `0` | Vertical offset of the bar from its default position |
| `corner_radius` | `<positive_integer>` | `0` | Corner radius of the bar |
| `border_width` | `<positive_integer>` | `0` | Border width of the bars border |
| `blur_radius` | `<positive_integer>` | `0` | Blur radius applied to the background of the bar |
| `padding_left` | `<positive_integer>` | `0` | Padding between the left bar border and the leftmost item |
| `padding_right` | `<positive_integer>` | `0` | Padding between the right bar border and the rightmost item |
| `display` | `main` , `all` | `all` | Display to show the bar on |
| `hidden` | `<boolean>` , `current` | `off` | If all / the current bar is hidden |
| `topmost` | `<boolean>` | `off` | If the bar should be drawn on top of `everything` |
| `font_smoothing` | `<boolean>` | `off` | If fonts should be smoothened |
| `shadow` | `<boolean>` | `off` | If the bar should draw a shadow |
2021-08-19 12:38:02 +00:00
2021-11-04 19:24:29 +00:00
## Items and their properties
2021-10-21 21:32:44 +00:00
Items are the main building blocks of sketchybar and can be configured in a number of ways. Items have the following basic structure: < br >
2021-12-20 18:30:45 +00:00
< img src = "images/bar_item.svg" width = "300" > < br >
2021-08-19 12:38:02 +00:00
2021-10-21 21:32:44 +00:00
### Adding items to sketchybar
2021-09-11 21:22:51 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --add item < name > < position >
2021-09-11 21:22:51 +00:00
```
2022-01-24 22:00:25 +00:00
where the `<name>` should not contain whitespaces (or must be quoted), it can be used to further configure the item.
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 order
in which they are added, but can be moved later on.
2022-01-24 22:20:44 +00:00
| `<name>` | `<string>` |
| ----- | --------- |
| `<position>` | `left` , `right` , `center` , (`q`, `e` [#120 ](https://github.com/FelixKratz/SketchyBar/issues/120 )) |
2021-08-19 12:38:02 +00:00
2021-10-21 21:32:44 +00:00
### Changing item properties
2021-09-06 23:51:46 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --set < name > < property > =< value > ... < property > =< value >
2021-09-06 23:51:46 +00:00
```
2021-08-19 12:38:02 +00:00
where the *name* is used to target the item with this name.
2021-12-25 00:01:00 +00:00
(The *name* can be a regular expression inside of two '/': */\<regex\>/* )
2021-09-09 17:34:49 +00:00
2021-10-21 21:32:44 +00:00
A list of properties available to the *set* command is listed below (components might have additional properties, see the respective component section for them):
2021-09-09 17:34:49 +00:00
2022-01-24 22:00:25 +00:00
* Geometry Properties:
2022-01-24 22:15:17 +00:00
| \<property\> | \<value\> | default | description |
2022-01-24 22:00:25 +00:00
| :-------: | :------: | :-------: | ----------- |
| `position` | `left` , `right` , `center` | | Position of the item in the bar |
2022-01-24 22:15:17 +00:00
| `associated_space` | `<positive_integer list>` | `0` | Spaces to show this item on |
| `associated_display` | `<positive_integer list>` | `0` | Displays to show this item on |
2022-03-31 15:18:12 +00:00
| `ignore_association` | `<boolean>` | `off` | Ignores all space / display associations while on (Only on HEAD) |
2022-04-16 13:17:34 +00:00
| `y_offset` | `<integer>` | `0` | Vertical offset applied to the item |
2022-01-24 22:15:17 +00:00
| `width` | `<positive_integer>` or `dynamic` | `dynamic` | Makes the *item* use a fixed *width* given in points |
2022-01-24 22:00:25 +00:00
| `align` | `center` , `left` , `right` | `left` | Aligns the `item` content in its container when it has a fixed `width` larger than the content width |
* Drawing properties:
2022-01-25 17:31:11 +00:00
| \<property\> | \<value\> | default | description |
| :-------: | :------: | :-------: | ----------- |
| `drawing` | `<boolean>` | `on` | If the item should be drawn into the bar |
| `lazy` | `<boolean>` | `off` | Changes do not trigger a redraw of the bar, item is refreshed when the bar is redrawn anyways |
2022-01-24 22:00:25 +00:00
* Icon properties:
2022-01-24 22:15:17 +00:00
| \<property\> | \<value\> | default | description |
2022-01-24 22:00:25 +00:00
| :-------: | :------: | :-------: | ----------- |
| `icon` | `<string>` | | Icon of the item |
2022-01-24 22:15:17 +00:00
| `icon.<text_property>` | | | Icons support all *text* properties |
2022-01-24 22:00:25 +00:00
* Label properties:
2022-01-24 22:15:17 +00:00
| \<property\> | \<value\> | default | description |
2022-01-24 22:00:25 +00:00
| :-------: | :------: | :-------: | ----------- |
| `label` | `<string>` | | Label of the item |
2022-01-24 22:15:17 +00:00
| `label.<text_property>` | | | Labels support all *text* properties |
2022-01-24 22:00:25 +00:00
* Scripting properties:
2022-01-24 22:20:44 +00:00
| \<property\> | \<value\> | default | description |
| :-------: | :------: | :-------: | ----------- |
2022-02-08 15:28:22 +00:00
| `script` | `<path>` , `<string>` | | Script to run on an `event` |
2022-01-24 22:20:44 +00:00
| `click_script` | `<path>` , `<string>` | | Script to run on a mouse click (Difference to `mouse.clicked` event: [#109 ](https://github.com/FelixKratz/SketchyBar/discussions/109 )) |
| `update_freq` | `<positive_integer>` | `1` | Time in seconds between routine script executions |
| `updates` | `<boolean>` , `when_shown` | `on` | If and when the item updates e.g. via script execution |
2022-01-24 22:00:25 +00:00
* Text properties:
2022-04-16 13:16:37 +00:00
| \<text_property\> | \<value\> | default | description |
| :-------: | :------: | :-------: | ----------- |
| `drawing` | `<boolean>` | `on` | If the text is rendered |
| `highlight` | `<boolean>` | `off` | If the text uses the `highlight_color` or the regular `color` |
| `color` | `<argb_hex>` | `0xffffffff` | Color used to render the text |
| `highlight_color` | `<argb_hex>` | `0xff000000` | Highlight color of the text (e.g. for active space icon |
| `padding_left` | `<integer>` | `0` | Padding to the left of the `text` |
| `padding_right` | `<integer>` | `0` | Padding to the right of the `text` |
| `y_offset` | `<integer>` | `0` | Vertical offset applied to the `text` |
| `font` | `<family>:<type>:<size>` | `Hack Nerd Font:Bold:14.0` | The font to be used for the `text` |
| `width` | `<positive_integer>` or `dynamic` | `dynamic` | Makes the `text` use a fixed `width` given in points |
| `align` | `center` , `left` , `right` | `left` | Aligns the `text` in its container when it has a fixed `width` larger than the content width |
| `background.<background_property>` | | | Texts support all `background` properties |
| `shadow.<shadow_property>` | | | Texts support all `shadow` properties |
2022-01-24 22:00:25 +00:00
* Background properties:
2022-03-28 17:26:14 +00:00
| \<background_property\> | \<value\> | default | description |
| :-------: | :------: | :-------: | ----------- |
| `drawing` | `<boolean>` | `off` | If the `background` should be rendered |
| `color` | `<argb_hex>` | `0x00000000` | Fill color of the `background` |
| `border_color` | `<argb_hex>` | `0x00000000` | Color of the backgrounds border |
| `border_width` | `<positive_integer>` | `0` | Width of the background border |
| `height` | `<positive_integer>` | `0` | Overrides the `height` of the background |
| `corner_radius` | `<positive_integer>` | `0` | Corner radius of the background |
| `padding_left` | `<integer>` | `0` | Padding to the left of the `background` |
| `padding_right` | `<integer>` | `0` | Padding to the right of the `background` |
| `y_offset` | `<integer>` | `0` | Vertical offset applied to the `background` |
| `image` | `<path>` | | The path to a png or jpeg image file |
| `image.<image_property>` | | | Backgrounds support all `image` properties |
| `shadow.<shadow_property>` | | | Backgrounds support all `shadow` properties |
2022-01-24 22:00:25 +00:00
* Image properties (Can be resource intensive if many large images are drawn):
2022-03-28 17:26:14 +00:00
| \<image_property\> | \<value\> | default | description |
| :-------: | :------: | :-------: | ----------- |
| `drawing` | `<boolean>` | `off` | If the image should draw |
| `scale` | `<positive_integer>` | `0` | The scale factor that should be applied to the image |
2022-03-28 17:21:59 +00:00
* Shadow properties:
| \<shadow_property\> | \<value\> | default | description |
| :-------: | :------: | :-------: | ----------- |
| `drawing` | `<boolean>` | `off` | If the shadow should be drawn |
| `color` | `<argb_hex>` | `0xff000000` | Color of the shadow |
| `angle` | `<positive_integer>` | `30` | Angle of the shadow |
| `distance` | `<positive_integer>` | `5` | Distance of the shadow |
2021-12-23 14:04:51 +00:00
2021-08-22 12:37:30 +00:00
### Changing the default values for all further items
2021-10-15 13:01:42 +00:00
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.
2021-10-21 21:32:44 +00:00
2021-08-22 12:37:30 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --default < property > =< value > ... < property > =< value >
2021-08-22 12:37:30 +00:00
```
2021-11-04 19:24:29 +00:00
this works for all item properties.
2021-10-21 21:32:44 +00:00
2022-01-25 17:31:11 +00:00
### Type nomenclature
| `type` | `values` |
| ----- | --------- |
| `<boolean>` | `on` , `off` , `yes` , `no` , `true` , `false` , `1` , `0` , `toggle` |
| `<argb_hex>` | Color as an 8 digit hex with alpha, red, green and blue channels |
| `<path>` | An absolute file path |
| `<string>` | Any UTF-8 string or symbol |
2022-03-28 17:21:59 +00:00
| `<float>` | A floating point number |
2022-01-25 17:31:11 +00:00
| `<integer>` | An integer |
| `<positive_integer>` | A positive integer |
| `<positive_integer list>` | A comma separated list of positive integers |
2021-10-21 21:32:44 +00:00
## Components -- Special Items with special properties
2021-11-04 19:24:29 +00:00
Components are essentially items, but with special properties.
Currently there are the components (more details in the corresponding sections below):
2021-10-21 21:32:44 +00:00
* *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
2021-08-22 12:37:30 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --add graph < name > < position > < width in points >
2021-08-22 12:37:30 +00:00
```
2021-10-21 21:32:44 +00:00
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
2022-03-28 17:21:59 +00:00
| \<property\> | \<value\> | default | description |
| :-------: | :------: | :-------: | ----------- |
| `graph.color` | `<argb_hex>` | `0xcccccc` | Color of the graph line |
| `graph.fill_color` | `<argb_hex>` | `0xcccccc` | Fill color of the graph |
| `graph.line_width` | `<float>` | `0.5` | Width of the line in points |
2021-10-21 21:32:44 +00:00
Push data points into the graph via:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --push < name > < data point >
2021-10-21 21:32:44 +00:00
```
2022-04-11 08:26:58 +00:00
where the `data point` is a floating point number between 0 and 1.
2021-10-21 21:32:44 +00:00
### Space -- Associate mission control spaces with an item
```bash
2021-12-26 10:35:40 +00:00
sketchybar --add space < name > < position >
2021-10-21 21:32:44 +00:00
```
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
2022-01-16 19:40:52 +00:00
`$SID` holds the space id and `$DID` the display id.
2021-10-21 21:32:44 +00:00
By default the space component invokes the following script:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --set $NAME icon.highlight=$SELECTED
2021-10-21 21:32:44 +00:00
```
which you can freely configure to your liking by supplying a different script to the space component:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --set < name > script=< script / path >
2021-10-21 21:32:44 +00:00
```
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):
2021-11-04 19:24:29 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --add bracket < name > < first item name > ... < n-th item name >
2021-10-21 21:32:44 +00:00
```
2021-11-04 19:24:29 +00:00
The first item must always be the one listed earliest in the config. It is now possible to
2021-10-21 21:32:44 +00:00
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:
2021-11-04 19:24:29 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --add bracket primary_spaces code \
writing \
reading \
entertainment \
\
--set primary_spaces background.color=0xffffffff \
background.corner_radius=4 \
background.height=20
2021-10-21 21:32:44 +00:00
```
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.
It is now possible to create an alias of a default menu bar item with the following syntax:
2021-08-19 12:38:02 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --add alias < application_name > < position >
2021-08-19 12:38:02 +00:00
```
2021-10-21 21:32:44 +00:00
this operation requires *screen capture permissions* , which should be granted in the system preferences.
This will put the default item into sketchybar.
Aliases currently are not clickable but can be modified with all the options available for simple items.
The command can be overloaded by providing a *window_owner* and a *window_name*
2021-09-11 21:22:51 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --add alias < window_owner > ,< window_name > < position >
2021-10-21 21:32:44 +00:00
```
2021-12-09 16:57:03 +00:00
this way the default system items can also be slurped into sketchybar, e.g.: < br >
"Control Center,Bluetooth" < br >
"Control Center,WiFi" < br >
2021-10-21 21:32:44 +00:00
Or the individual widgets of [Stats ](https://github.com/exelban/stats ):< br >
2021-12-09 16:57:03 +00:00
"Stats,CPU_Mini"< br >
2021-10-21 21:32:44 +00:00
etc...< br >
All further default menu items currently available on your system can be found via the command:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --query default_menu_items
2021-10-21 21:32:44 +00:00
```
2022-02-13 15:00:45 +00:00
You can override the color of an alias via the property (HEAD only):
```bash
sketchybar --set < name > alias.color=< rgba_hex >
```
2021-10-21 21:32:44 +00:00
2021-12-19 21:57:39 +00:00
## Popup Menus
< img src = "https://user-images.githubusercontent.com/22680421/146688291-b8bc5e77-e6a2-42ee-bd9f-b3709c63d936.png" width = "300" > < br >
Popup menus are a powerful way to make further `items` accessible in a small popup window below any bar item.
Every item has a popup available with the properties:
2022-03-28 17:21:59 +00:00
| \<property\> | \<value\> | default | description |
| :-------: | :------: | :-------: | ----------- |
| `popup.drawing` | `<boolean>` | `off` | If the `popup` should be rendered |
| `popup.horizontal` | `<boolean>` | `off` | If the `popup` should render horizontally |
| `popup.height` | `<positive_integer>` | bar height | The vertical spacing between items in a popup (Only on HEAD) |
| `popup.y_offset` | `<integer>` | `0` | Vertical offset applied to the `popup` |
| `popup.align` | `left` , `right` , `center` | `left` | Alignment of the popup with its parent item in the bar |
| `popup.background.<background_property>` | | | Popups have a background and support all properties |
Items can be added to a popup menu by setting the `position` of those items to `popup.<name>` where `<name>` is the name of the item containing the popup.
2021-12-19 21:57:39 +00:00
You can find a demo implementation of this [here ](https://github.com/FelixKratz/SketchyBar/discussions/12?sort=new#discussioncomment-1843975 ).
2021-10-21 21:32:44 +00:00
## Batching of configuration commands
It is possible to batch commands together into a single call to sketchybar, this can be helpful to
keep the configuration file a bit cleaner and also to reduce startup times.
Assume 5 individual configuration calls to sketchybar:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --bar position=top
sketchybar --bar margin=5
sketchybar --add item demo left
sketchybar --set demo label=Hello
sketchybar --subscribe demo system_woke
2021-10-21 21:32:44 +00:00
```
after each configuration command the bar is redrawn (if needed), thus it is more perfomant to append these calls into a single command like so:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --bar position=top \
margin=5 \
--add item demo left \
--set demo label=Hello \
--subscribe demo system_woke
2021-10-21 21:32:44 +00:00
```
The backslash at the end of the first 4 lines is the default bash way to join lines together and should not be followed by a whitespace.
## Events and Scripting
Any item can *subscribe* to arbitrary *events* , when the *event* happens, all items subscribed to the *event* will execute their *script* .
This can be used to create more reactive and performant items which react to events rather than polling for a change.
```bash
2021-12-26 10:35:40 +00:00
sketchybar --subscribe < name > < event > ... < event >
2021-09-11 21:22:51 +00:00
```
2021-08-19 12:38:02 +00:00
where the events are:
2022-03-28 17:21:59 +00:00
| \<event\> | description |
| :-------: | :------: |
| `front_app_switched` | When the front application changes (not triggered if a different window of the same app is focused) |
| `space_change` | When the active mission control space changes |
| `display_change` | When the active display is changed |
| `system_will_sleep` | When the system prepares to sleep |
| `system_woke` | When the system has awaken from sleep |
| `mouse.entered` | When the mouse enters over an item |
| `mouse.exited` | When the mouse leaves an item |
| `mouse.clicked` | When an item is clicked |
2021-08-19 12:38:02 +00:00
2022-01-16 19:40:52 +00:00
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* .
2021-10-21 21:32:44 +00:00
Alternatively a fixed *update_freq* can be *--set* , such that the event is routinely run to poll for change.
When an item invokes a script, the script has access to some environment variables, such as:
2021-08-23 17:40:54 +00:00
```bash
2021-10-21 21:32:44 +00:00
$NAME
$SENDER
2021-08-23 17:40:54 +00:00
```
2022-01-16 19:40:52 +00:00
Where `$NAME` is the name of the item that has invoked the script and `$SENDER` is the reason why the script is executed.
2021-10-21 21:32:44 +00:00
2021-11-04 20:51:43 +00:00
If an item is *clicked* the script has access to the additional variables:
```bash
$BUTTON
$MODIFIER
```
2022-01-16 19:40:52 +00:00
where the `$BUTTON` can be *left* , *right* or *other* and specifies the mouse button that was used to click the item, while the `$MODIFIER` is either *shift* , *ctrl* , *alt* or *cmd* and
2021-11-04 20:51:43 +00:00
specifies the modifier key held down while clicking the item.
2022-01-16 19:40:52 +00:00
Some events send additional information in the `$INFO` variable
2021-11-14 20:36:09 +00:00
All scripts are forced to terminate after 60 seconds and do not run while the system is sleeping.
2021-11-13 13:02:39 +00:00
2021-10-21 21:32:44 +00:00
### 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.
2021-09-11 21:22:51 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --add event < name > [optional: < NSDistributedNotificationName > ]
2021-09-11 21:22:51 +00:00
```
2021-10-15 13:01:42 +00:00
Optional: You can subscribe to the notifications sent to the NSDistributedNotificationCenter e.g.
2022-01-24 22:00:25 +00:00
the notification Spotify sends on track change: *com.spotify.client.PlaybackStateChanged* ([example](https://github.com/FelixKratz/SketchyBar/discussions/12#discussioncomment-1455842)), or the
2021-10-15 13:01:42 +00:00
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))
2022-01-16 19:40:52 +00:00
to create more responsive items. Custom events that subscribe to NSDistributedNotificationCenter notifications will receive additional notification information in the `$INFO` variable if available.
2021-08-23 17:40:54 +00:00
### Triggering custom events
This triggers a custom event that has been added before
```bash
2021-12-26 10:35:40 +00:00
sketchybar --trigger < event > [Optional: < envvar > =< value > ... < envvar > =< value > ]
2021-08-23 17:40:54 +00:00
```
2021-12-12 13:17:29 +00:00
Optionaly you can add environment variables to the trigger command witch are passed to the script, e.g.:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --trigger demo VAR=Test
2021-12-12 13:17:29 +00:00
```
will trigger the demo event and `$VAR` will be available as an environment variable in the scripts that this event invokes.
2021-08-23 18:19:07 +00:00
This could be used to link the powerful event system of yabai to sketchybar by triggering the custom action via a yabai event.
2021-08-23 17:40:54 +00:00
2021-08-19 12:38:02 +00:00
### Forcing all shell scripts to run and the bar to refresh
```bash
2021-12-26 10:35:40 +00:00
sketchybar --update
2021-08-30 22:32:33 +00:00
```
2021-09-26 22:08:41 +00:00
## Querying
*SketchyBar* can be queried for information about a number of things.
2021-09-27 21:03:37 +00:00
### Bar Properties
2021-09-26 22:08:41 +00:00
Information about the bar can be queried via:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --query bar
2021-09-26 22:08:41 +00:00
```
The output is a json structure containing relevant information about the configuration settings of the bar.
2021-09-27 21:03:37 +00:00
### Item Properties
2021-09-26 22:08:41 +00:00
Information about an item can be queried via:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --query < name >
2021-11-30 16:59:56 +00:00
```
2021-09-26 22:08:41 +00:00
The output is a json structure containing relevant information about the configuration of the item.
2021-09-27 21:03:37 +00:00
### Default Properties
2021-09-27 20:44:17 +00:00
Information about the current defaults.
```bash
2021-12-26 10:35:40 +00:00
sketchybar --query defaults
2021-09-27 20:44:17 +00:00
```
2021-11-01 13:39:10 +00:00
### Event Properties
Information about the events.
```bash
2021-12-26 10:35:40 +00:00
sketchybar --query events
2021-11-01 13:39:10 +00:00
```
2021-10-26 15:42:26 +00:00
## Item Reordering
2021-10-25 19:34:39 +00:00
It is possible to reorder items by invoking
```bash
2021-12-26 10:35:40 +00:00
sketchybar --reorder < name > ... < name >
2021-10-25 19:34:39 +00:00
```
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
simply call
```bash
2021-12-26 10:35:40 +00:00
sketchybar --reorder < item 1 > < item 2 >
2021-10-25 19:34:39 +00:00
```
2021-10-26 15:42:26 +00:00
## Moving Items to specific positions
It is possible to move items and order them next to a reference item. < br >
Move Item *<name>* to appear *before* item *<reference name>* :
```bash
2021-12-26 10:35:40 +00:00
sketchybar --move < name > before < reference name >
2021-10-26 15:42:26 +00:00
```
Move Item *<name>* to appear *after* item *<reference name>* :
```bash
2021-12-26 10:35:40 +00:00
sketchybar --move < name > after < reference name >
2021-10-26 15:42:26 +00:00
```
## Item Cloning
It is possible to clone another item instead of adding a completely blank item
```bash
2021-12-26 10:35:40 +00:00
sketchybar --clone < name > < parent name > [optional: before/after]
2021-10-26 15:42:26 +00:00
```
2021-10-28 22:29:33 +00:00
the new item will inherit *all* properties of the parent item. The optional *before* and *after* modifiers can be used
to move the item *before* , or *after* the parent, equivalently to a --move command.
2021-10-26 15:42:26 +00:00
## Renaming Items
It is possible to rename any item. The new name should obviously not be in use by another item:
```bash
2021-12-26 10:35:40 +00:00
sketchybar --rename < old name > < new name >
2021-10-26 15:42:26 +00:00
```
## Removing Items
2021-12-26 10:38:18 +00:00
It is possible to remove any item by invoking, the item will be completely destroyed and removed from brackets
2021-10-26 15:42:26 +00:00
```bash
2021-12-26 10:35:40 +00:00
sketchybar --remove < name >
2021-10-26 15:42:26 +00:00
```
2022-01-23 12:36:55 +00:00
the `<name>` can again be a regex: `/<regex>/` .
2021-09-19 17:26:10 +00:00
2021-10-21 21:32:44 +00:00
## Performance optimizations
*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.
2021-09-19 17:26:10 +00:00
2021-10-21 21:32:44 +00:00
* Batch together configuration commands where ever possible.
* Set items to be *lazy* , e.g. I have an alias component in my bar that updates every *2* seconds, thus I set all *non-reactive* items to *lazy=on* ,
and only the ones that should react to change instantaneously to *lazy=off* .
* Set *updates=when_shown* for items that do not need to run their script if they are not rendered.
* Reduce the *update_freq* of *scripts* and *aliases* and use event-driven scripting when ever possible.
* Do not add *aliases* to apps that are not always running, otherwise sketchybar searches for them continously.
2021-10-10 16:10:36 +00:00
2021-08-18 21:22:01 +00:00
## Credits
2021-10-15 13:11:04 +00:00
This project was forked from *[spacebar](https://github.com/cmacrae/spacebar)* and completely reimagined and rewritten. < br >
The original idea is based on the status bar that was included in *[yabai](https://github.com/koekeishiya/yabai)* before getting removed.
