Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add local documentation #421

Merged
merged 4 commits into from
Oct 15, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/build.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
#!/bin/sh

rm -rf build
mkdir build
scdoc < sketchybar-animate.5.scd > build/sketchybar-animate.5
scdoc < sketchybar-components.5.scd > build/sketchybar-components.5
scdoc < sketchybar-events.5.scd > build/sketchybar-events.5
scdoc < sketchybar-items.5.scd > build/sketchybar-items.5
scdoc < sketchybar-popup.5.scd > build/sketchybar-popup.5
scdoc < sketchybar-query.5.scd > build/sketchybar-query.5
scdoc < sketchybar-tips.5.scd > build/sketchybar-tips.5
scdoc < sketchybar-types.5.scd > build/sketchybar-types.5
scdoc < sketchybar.1.scd > build/sketchybar.1
scdoc < sketchybar.5.scd > build/sketchybar.5
69 changes: 69 additions & 0 deletions man/sketchybar-animate.5.scd
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
sketchybar-animate(5)

# NAME

sketchybar-animate - animate the bar, items, etc.

# SYNOPSIS

*sketchybar --animate* _CURVE_ _DURATION_ *--bar* _SETTING_=_VALUE_ ...
_SETTING_=_VALUE_ ++
*sketchybar --animate* _CURVE_ _DURATION_ *--set* _PROPERTY_=_VALUE_ ...
_PROPERTY_=_VALUE_

# DESCRIPTION

All transitions between argb_hex, integer and positive_integer values can be
animated, by prepending the animation command in front of any regular *--set*
or *--bar* command.

A series of animations can be chained together as many as desired. The
animation function can also be changed in between. This is a nice way to
create custom animations with key-frames.

Other properties can also be made to wait for their animation until another
animation is finished. This is done by simply setting the property that
should wait to its current value in the first animation.

A superseding non-animated *--set* command targeting a currently animated
property will cancel the animation queue and immediately set the value.

A superseding animated *--set* command targeting a currently animated
property will cancel the animation queue and immediately begin with the new
animation beginning at the current state.

# OPTIONS

*--animate* _CURVE_ _DURATION_ *--bar* _SETTING_=_VALUE_ ... _SETTING_=_VALUE_ ++
*--animate* _CURVE_ _DURATION_ *--set* _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_

Animate the bar or an item. _CURVE_ can be any of the following animation
curves: *linear*, *quadratic*, *tanh*, *sin*, *exp*, *circ*. _DURATION_ is
a positive integer quantifying the number of animation steps. The duration
is the frame count on a 60 Hz display such that the temporal duration of the
animation in seconds is given by _DURATION_ / 60.

The animation system *always* animates between all *current* values and the
values specified in a configuration command (i.e. *--bar* or *--set* commands).

# EXAMPLES

To chain two or more animations together, simply change the property
multiple times in a single call. Consider
```
sketchybar --animate sin 30 --bar y_offset=10 y_offset=0
```
This will animate the bar to the first offset and then to the second offset
afterwards.

# SEE ALSO

*sketchybar*(1)++
*sketchybar*(5)++
*sketchybar-items*(5)++
*sketchybar-components*(5)++
*sketchybar-popup*(5)++
*sketchybar-events*(5)++
*sketchybar-query*(5)++
*sketchybar-types*(5)++
*sketchybar-tips*(5)
301 changes: 301 additions & 0 deletions man/sketchybar-components.5.scd
Original file line number Diff line number Diff line change
@@ -0,0 +1,301 @@
sketchybar-components(5)

# NAME

sketchybar-components - configuration of special components in the bar

# SYNOPSIS

*sketchybar --add graph* _NAME_ _POSITION_ _WIDTH_ *--push* _NAME_
_DATA_POINT_ ... _DATA_POINT_ ++
*sketchybar --add space* _NAME_ _POSITION_ ++
*sketchybar --add bracket* _NAME_ _MEMBER_NAME_ ... _MEMBER_NAME_ ++
*sketchybar --add alias* _APPLICATION_NAME_|"_WINDOW_OWNER_,_WINDOW_NAME_" _POSITION_ ++
*sketchybar --add slider* _NAME_ _POSITION_ _WIDTH_

# DESCRIPTION

Components are essentially items (see *sketchybar-items*(5)), but with special
properties.

Currently, the available components include
- *graph*: shows a graph
- *space*: represents a mission control space
- *bracket*: creates a shared background for any number of items
- *alias*: aliases a menu bar item from the macOS bar
- *slider*: shows a progression and can be clicked/dragged to set a new value.
Refer to *sketchybar-types*(5) when needed.

# OPTIONS

The usual commands for items such as *--add*, *--set*, *--move*, etc. (see
*sketchybar-items*(5)) can also be used by components as is unless superseded by
a redefinition below.

# DATA GRAPH

## Options

*--add graph* _NAME_ _POSITION_ _WIDTH_
Add an item to the bar that draws a graph. Inherits the usual *--add* command
usage. _WIDTH_ is the width of the graph in point units.

*--set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_
Change the properties of the component. Inherits the usual *--set* command
usage. Additional properties include:

[[ *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


*--push* _NAME_ _DATA_POINT_ ... _DATA_POINT_
Push data points to the graph. _DATA_POINT_ is a float between 0 and 1.

## Notes

Graphs usually take the entire height of the bar as a drawing canvas. However,
if a background is set for the graph item, the graph will draw inside of the
background (i.e. scaled in height to fit the background). With a background
enabled, the graph can also be moved via a *y_offset*, say,
```
sketchybar --set graph_name background.color=0xff00ff00 \\
background.height=20 \\
y_offset=2
```


# SPACE

## Options

*--add space* _NAME_ _POSITION_
Add an item to the bar that associates with a mission control space. Inherits
the usual *--add* command usage.

*--set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_
Change the properties of the component. Inherits the usual *--set* command
usage. Overriden properties include:
- *space*: which space this item represents
- *display*: (optional) on which display the space is shown.

The space property must be set to properly associate this item with the
corresponding mission control space. Optionally, a display to force a space
item to stay on a specific display can be provided. Otherwise the item will
draw on the screen on which the space is currently located.

## Notes

This component provides additional variables available for *script* and
*click_script*:
- *$SELECTED*: has the value *true* if the associated space is selected;
otherwise *false*
- *$SID*: holds the space id
- *$DID*: holds the display id.

By default, this component invokes the script
```
sketchybar --set $NAME icon.highlight=$SELECTED
```
which can be freely configured by supplying a different script:
```
sketchybar --set space_name script=path/to/script
```

For performance reasons the space script is only run on a change in the
*$SELECTED* variable, i.e. if the associated space has become active or has
resigned being active.


# ITEM BRACKET

## Options

*--add bracket* _NAME_ _MEMBER_NAME_ ... _MEMBER_NAME_
Add an item to the bar that groups other items together. Inherits the usual
*--add* command usage. _MEMBER_NAME_ is a name of any item in the bar. It can
also be a regular expression: /*REGEX*/.

*--set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_
Change the properties of the graph. Currently *DOES NOT* inherit *all* of the
usual *--set* command usage. Inherited properties include background-related
properties only.


## Notes

It is now possible to set properties for the bracket, just as for any item or
component, although support is only for background as of yet.

To set a colored background around the space components (which are, say, named
space.1, space.2, space.3), the setup would be:
```
sketchybar --add bracket spaces space.1 space.2 space.3 \\
--set spaces background.color=0xffffffff \\
background.corner_radius=4 \\
background.height=20
```

Alternatively, if there are a number of spaces, say, named space.1, space.2,
etc., the regex syntax comes in handy:
```
sketchybar --add bracket spaces '/space\..*/'
```

Brackets are very flexible with their members, i.e. it is no problem to bracket
a left and a center item together. The background will span all the way between
those items.

# ITEM ALIAS

## Options

*--add alias* _APPLICATION_NAME_ _POSITION_ ++
*--add alias* "_WINDOW_OWNER_,_WINDOW_NAME_" _POSITION_

Add an item to the bar that mirrors items in the original macOS status bar.
Inherits the usual *--add* command usage. _APPLICATION_NAME_ is the name of
the application (e.g. MeetingBar, "Google Drive", etc.) that manages the menu
bar item to be aliased.

If an application has multiple menu bar widgets, the command can be overloaded
by providing a _WINDOW_OWNER_ and _WINDOW_NAME_. See the note below on how to
list all available widgets.

Then, say, the default system items can be aliased as in:
- "Control Center,Bluetooth"
- "Control Center,WiFi"
- ...

Or, say, the individual widgets of Stats (see https://github.com/exelban/stats):
- "Stats,CPU_Mini"
- ...

*--set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_
Change the properties of the graph. Inherits the usual *--set* command usage.
Additional properties include:

[[ *property*
:[ *value*
:[ *default*
:< *description*
| alias.color
: <argb_hex>
: -
: Overriding color to use with the alias
| alias.scale
: <float>
: -
: The scale factor that should be applied to the alias
| alias.update_freq
: <positive_integer>
: 1
: Time in seconds before the alias is updated


## Notes

All macOS menu bar items currently available on the system with their respective
owners and names can be listed via (see *sketchybar-query*(5)):
```
sketchybar --query default_menu_items
```


# SLIDER

## Options

*--add slider* _NAME_ _POSITION_ _WIDTH_
Add an item to the bar that is a draggable progression indicator. Inherits
the usual *--add* command usage. _WIDTH_ is the width of the graph in point
units.

*--set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_
Change the properties of the component. Inherits the usual *--set* command
usage. Additional properties include:

[[ *property*
:[ *value*
:[ *default*
:< *description*
| slider.width
: <positive_integer>
: 100
: Total width of the slider in points
| slider.percentage
: <positive_integer>
: 0
: Progression of the slider in percent (0-100)
| slider.highlight_color
: <argb_hex>
: 0xff0000ff
: Color that highlights the progression of the slider
| slider.knob
: <string>
: -
: Knob of the slider
| slider.knob.<text_property>
: -
: -
: The slider knob supports all text properties
| slider.background.<background_property>
: -
: -
: The slider supports all background properties

## Notes

The slider can be enabled to receive *mouse.clicked* events by subscribing to
this event.

A slider will receive the additional environment variable *$PERCENTAGE* on a
click in its script, which represents the percentage corresponding to the click
location.

If a slider is dragged by the mouse it will only send a single event on drag
release and track the mouse during the drag.

# EXAMPLES

To add mission control space indicators to indicate active and available spaces
in bash:

```
SPACE_ICONS=("1" "2" "3" "4" "5" "6" "7" "8" "9" "10")
for i in "${!SPACE_ICONS[@]}"
do sid=$(($i+1))
sketchybar --add space space.$sid left \\
\--set space.$sid space=$sid icon=${SPACE_ICONS[i]} \\
script='sketchybar --set $NAME icon.highlight=$SELECTED'
done
```
Should you wish to focus the respective spaces with a click on the item in the
bar, you can add a *click_script* to the items which triggers a space change
(e.g. via yabai, or via skhd by synthetically emitting the space focus keyboard
shortcuts).

# SEE ALSO

*sketchybar*(1)++
*sketchybar*(5)++
*sketchybar-items*(5)++
*sketchybar-popup*(5)++
*sketchybar-events*(5)++
*sketchybar-query*(5)++
*sketchybar-animate*(5)++
*sketchybar-types*(5)++
*sketchybar-tips*(5)
Loading