From bda14aacae81cb496a12b47bfbb896b6572ad728 Mon Sep 17 00:00:00 2001 From: Ralph Torres Date: Fri, 13 Oct 2023 08:27:47 +0000 Subject: [PATCH 1/4] docs: add local documentation --- docs/sketchybar-animate.5.scd | 69 +++++ docs/sketchybar-components.5.scd | 324 +++++++++++++++++++++++ docs/sketchybar-events.5.scd | 169 ++++++++++++ docs/sketchybar-items.5.scd | 425 +++++++++++++++++++++++++++++++ docs/sketchybar-popup.5.scd | 114 +++++++++ docs/sketchybar-query.5.scd | 44 ++++ docs/sketchybar-tips.5.scd | 155 +++++++++++ docs/sketchybar-types.5.scd | 78 ++++++ docs/sketchybar.1.scd | 215 ++++++++++++++++ docs/sketchybar.5.scd | 119 +++++++++ 10 files changed, 1712 insertions(+) create mode 100644 docs/sketchybar-animate.5.scd create mode 100644 docs/sketchybar-components.5.scd create mode 100644 docs/sketchybar-events.5.scd create mode 100644 docs/sketchybar-items.5.scd create mode 100644 docs/sketchybar-popup.5.scd create mode 100644 docs/sketchybar-query.5.scd create mode 100644 docs/sketchybar-tips.5.scd create mode 100644 docs/sketchybar-types.5.scd create mode 100644 docs/sketchybar.1.scd create mode 100644 docs/sketchybar.5.scd diff --git a/docs/sketchybar-animate.5.scd b/docs/sketchybar-animate.5.scd new file mode 100644 index 00000000..42509774 --- /dev/null +++ b/docs/sketchybar-animate.5.scd @@ -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 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) diff --git a/docs/sketchybar-components.5.scd b/docs/sketchybar-components.5.scd new file mode 100644 index 00000000..69291fee --- /dev/null +++ b/docs/sketchybar-components.5.scd @@ -0,0 +1,324 @@ +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_ + +*sketchybar --set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++ +*sketchybar --default* _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++ +*sketchybar --reorder* _NAME_ ... _NAME_ ++ +*sketchybar --move* _NAME_ *before*|*after* _REFERENCE_NAME_ ++ +*sketchybar --clone* _PARENT_NAME_ _NAME_ [*before*|*after*] ++ +*sketchybar --rename* _OLD_NAME_ _NEW_NAME_ ++ +*sketchybar --remove* _NAME_ + +# DESCRIPTION + +Components are essentially items, but with special properties. +Currently, there available components include +- *graph*: shows a graph +- *space*: represents a mission control space +- *bracket*: brackets other items together +- *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 +: +: 0xcccccc +: Color of the graph line +| graph.fill_color +: +: 0xcccccc +: Fill color of the graph +| graph.line_width +: +: 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 and for its height, the graph +will draw inside of 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 dditional 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 then 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_. + + 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 +: +: - +: Overriding color to use with the alias +| alias.scale +: +: - +: The scale factor that should be applied to the alias +| alias.update_freq +: +: 1 +: Time in seconds before the alias is updated + + +## Notes + +All other 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 +: +: 100 +: Total width of the slider in points +| slider.percentage +: +: 0 +: Progression of the slider in percent (0-100) +| slider.highlight_color +: +: 0xff0000ff +: Color that highlights the progression of the slider +| slider.knob +: +: - +: Knob of the slider +| slider.knob. +: - +: - +: The slider knob supports all text properties +| slider.background. +: - +: - +: 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 posix shell and without yabai scripting additions: + +``` +pos=left +name=space +set -- 1 2 3 4 5 6 7 8 9 +sid=0 +for win in "$@" +do sid=$((sid+1)) + sketchybar --add $name $name.$sid $pos \\ + --set $name.$sid associated_space=$sid icon.drawing=off label="$win" \\ + script='sketchybar --set $NAME background.border_width=1 \\ + background.padding_left=5 background.drawing=$SELECTED' \\ + click_script="skhd -k ctrl\\ -\\ $sid" +done +sketchybar --add bracket spaces "/$name\..*/" +``` + +Or, in bash and with scripting additions: + +``` +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]} \\ + background.color=0x44ffffff \\ + background.corner_radius=5 \\ + background.height=20 \\ + background.drawing=off \\ + label.drawing=off \\ + script="CONFIG_DIR/plugins/space.sh" \\ + click_script="yabai -m space --focus $sid" +done +``` + +# 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) diff --git a/docs/sketchybar-events.5.scd b/docs/sketchybar-events.5.scd new file mode 100644 index 00000000..a4060a7e --- /dev/null +++ b/docs/sketchybar-events.5.scd @@ -0,0 +1,169 @@ +sketchybar-events(5) + +# NAME + +sketchybar-events - configuration of events and scripting + +# SYNOPSIS + +*sketchybar --add event* _NAME_ [_NSDistributedNotificationName_] ++ +*sketchybar --subscribe* _NAME_ _EVENT_ ... _EVENT_ ++ +*sketchybar --trigger* _NAME_ [_ENVVAR_=_VALUE_ ... _ENVVAR_=_VALUE_] ++ +*sketchybar --update* + +# DESCRIPTION + +All items can subscribe to arbitrary events. When the event happens, all items +subscribed to the event will execute their scripts. This mechanism can be used +to create more reactive and performant items which react to events rather than +to polled changes. + +Some events send additional information through the *$INFO* environment variable. +When an item is subscribed to these events, the script is run and the *$SENDER* +variable is passed. This variable holds the event name (see EVENTS) to +distinguish between the different events. +It is thus possible to have a script that reacts differently to various events +(consider: a switch statement via shell's *case* command for the *$SENDER* +variable in the *script*). + +Alternatively, a fixed *update_freq* can be *--set* such that the event is +routinely run to poll for changes. Here, the *$SENDER* variable will hold the +value *routine*. + +An item invokes a script, the script has access to some environment variables +such as +- *$NAME* +- *$SENDER* +- *$CONFIG_DIR* +where *$NAME* is the name of the item that invoked the script and *$SENDER* is +the reason why the script was executed. *$CONFIG_DIR* holds the value of the +absolute path of the directory where the current configuration file is located. + +If an item is *clicked*, the script (that is *click_script*) has access to the +additional variables such as +- *$BUTTON* +- *$MODIFIER* +where *$BUTTON* can have a value of *left*, *right* or *other*, and does specify +the mouse button that was used to click the item. Whereas, *$MODIFIER* can be +*shift*, *ctrl*, *alt* or *cmd*, and does specify the modifier key held down while +clicking the item. + +If an item receives a *scroll* event from the mouse, the script sends the +additional *$SCROLL_DELTA* variable. + +All scripts are *forced* to terminate after 60 seconds and do not run while the +system is sleeping. + +# OPTIONS + +*--add event* _NAME_ [_NSDistributedNotificationName_] + Add an event to be triggered manually or by arbitrary applications. + Optionally, an event can use the notifications sent to macOS's notification + system by specifying the relevant _NSDistributedNotificationName_. + + For example, Spotify notifies the system on track change via + *com.spotify.client.PlaybackStateChanged*, and the system notifies itself + when the screen is unlocked via *com.apple.screenIsUnlocked*. + + Custom events that subscribe to *NSDistributedNotificationCenter* notifications + will receive additional notification information through the *$INFO* variable + if available. + + For more on *NSDistributedNotifications*, see + https://github.com/FelixKratz/SketchyBar/discussions/151 + +*--subscribe* _NAME_ _EVENT_ ... _EVENT_ + Subscribe an item referred by _NAME_ to an _EVENT_ or a series of events. + A list of events can be found in EVENTS. See below. + +*--trigger* _NAME_ [_ENVVAR_=_VALUE_ ... _ENVVAR_=_VALUE_] + Trigger the added custom event. Optionally, an event can send an environment + variable _ENVVAR with value _VALUE_ (or a series of such variables) to the + trigger command then pass them to *script* or *click_script*. + +*--update* + Forces all *scripts* to run and all *events* to be emitted. This should + *NEVER* be used in an item script as this would lead to infinite loops. + But, this is prominently needed after the initial configuration to properly + initialize all the items by forcing all their scripts to run. + +# EVENTS + +[[ *event* +:[ *description* +:< *returned $INFO* +| front_app_switched +: When the front application changes (not triggered if a different window of + the same app is focused) +: front application name +| space_change +: When the active mission control space changes +: JSON for active spaces on all displays +| display_change +: When the active display is changed +: new active display id +| volume_change +: When the system audio volume is changed +: new volume in percent +| brightness_change +: When a displays brightness is changed +: new brightness in percent +| power_source_change +: When the devices power source is changed +: new power source (AC or BATTERY) +| wifi_change +: When the device connects of disconnects from wifi +: new WiFi SSID or empty on disconnect (not working on Sonoma) +| media_change +: When a change in now playing media is performed (experimental) +: media info in a JSON structure +| 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.entered.global +: When the mouse enters over *any* part of the bar +: - +| mouse.exited.global +: When the mouse leaves *all* parts of the bar +: - +| mouse.clicked +: When an item is clicked +: mouse button and modifier info +| mouse.scrolled +: When the mouse is scrolled over an item +: scroll wheel delta +| mouse.scrolled.globa +: When the mouse is scrolled over an empty region of the bar +: scroll wheel delta + +# EXAMPLES + +A simple plugin that uses the com.spotify.client.PlaybackStateChanged* +*notification sent by Spotify can be found at +https://github.com/FelixKratz/SketchyBar/discussions/12#discussioncomment-1455842 + +A more advanced plugin that uses the *com.apple.screenIsUnlocked* notification +sent by the system and the animation feature (see *sketchybar-animate*(5)) can +be found at +https://github.com/FelixKratz/SketchyBar/discussions/12?sort=new#discussioncomment-2979651 + +# SEE ALSO + +*sketchybar*(1) +*sketchybar*(5) +*sketchybar-items*(5) +*sketchybar-components*(5) +*sketchybar-popup*(5) +*sketchybar-query*(5) +*sketchybar-animate*(5) +*sketchybar-types*(5) +*sketchybar-tips*(5) diff --git a/docs/sketchybar-items.5.scd b/docs/sketchybar-items.5.scd new file mode 100644 index 00000000..704f831c --- /dev/null +++ b/docs/sketchybar-items.5.scd @@ -0,0 +1,425 @@ +sketchybar-items(5) + +# NAME + +sketchybar-items - configuration of items in the bar + +# SYNOPSIS + +*sketchybar --add item* _NAME_ _POSITION_ ++ +*sketchybar --set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++ +*sketchybar --default* _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++ +*sketchybar --reorder* _NAME_ ... _NAME_ ++ +*sketchybar --move* _NAME_ *before*|*after* _REFERENCE_NAME_ ++ +*sketchybar --clone* _PARENT_NAME_ _NAME_ [*before*|*after*] ++ +*sketchybar --rename* _OLD_NAME_ _NEW_NAME_ ++ +*sketchybar --remove* _NAME_ + +# DESCRIPTION + +Items are the main building blocks of sketchybar and can be configured in a +number of ways. Items have the following basic structure: + +``` + : : - +--:----------------------:-- | +| : | icon | | | label | : | | background.height +--:----------------------:-- | + ^:^ ^ ^ ^:^ - + | | | | | |________________________________ + | | | |______________ label.padding_{left,right} | + | |_________________________ icon.padding_{left,right} | + |___________________________ background.padding_{left,right} + +``` + +When neeeded, refer to *sketchybar-types*(5) for the nomenclature of types of +values found here. + +# OPTIONS + +*--add item* _NAME_ _POSITION_ + Add an item to the bar. _NAME_ should not contain whitespaces, or must be + quoted. It is later used to refer to this item in the configuration. _POSITION_ + is the placement in the bar and can be either *left*, *right*, *center*, or *q* + (which is left of the notch) and *e* (which is right of the notch). The items + will appear in the bar in the order in which they are added, but can be moved + later on. + + For details about *q* and *e*, see + https://github.com/FelixKratz/SketchyBar/issues/120 + +*--set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ + Change the properties of an item. _NAME_ is used to target the item. It can + be a regular expression inside of two slashes: /*REGEX*/. A list of properties + available can be found in PROPERTIES. See below. + +*--default* _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ + Change the defaults at any point in the configuration. All item created + *after* changing the defaults will inherit these properties from the default + item. + +*--reorder* _NAME_ ... _NAME_ + Reorder the items. A new order can be supplied for arbitrary many items. Only the + specified items get reordered. By swapping them around, everything else stays + the same. To swap two items, simply call + ``` + sketchybar --reorder NAME1 NAME2 + ``` + +*--move* _NAME_ *before*|*after* _REFERENCE_NAME_ + Move items to specific positions. To move item _NAME_ before item + _REFERENCE_NAME_, use *before*. Otherwise, use *after*. + +*--clone* _PARENT_NAME_ _NAME_ [*before*|*after*] + Clone an item to another item. 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. + +*--rename* _OLD_NAME_ _NEW_NAME_ + Rename an item. Note that the new name should not be in use by another item. + +*--remove* _NAME_ + Remove an item. _NAME_ can be a regex: /*REGEX*/. The item will be completely + destroyed and removed from brackets. + +# PROPERTIES + +This section is relevant to the *--set* and *--default* commands. + +## Geometry properties + +[[ *property* +:[ *value* +:[ *default* +:< *description* +| drawing +: +: on +: If the item should be drawn into the bar +| position +: left, right, center +: - +: Position of the item in the bar +| space +: +: 0 +: Spaces to show this item on +| display +: , active +: 0 +: Displays to show this item on +| ignore_association +: +: off +: Ignores all space / display associations while on +| y_offset +: +: 0 +: Vertical offset applied to the item +| padding_left +: +: 0 +: The padding applied left of the item +| padding_right +: +: 0 +: The padding applied right of the item +| width +: or dynamic +: dynamic +: Makes the _item_ use a fixed _width_ given in points +| blur_radius +: +: 0 +: The blur radius applied to the background of the item +| background. +: - +: - +: Items support all background properties + +## Icon properties + +[[ *property* +:[ *value* +:[ *default* +:< *description* +| icon +: +: - +: Icon of the item +| icon. +: - +: - +: Icons support all _text_ properties + +## Label properties + +[[ *property* +:[ *value* +:[ *default* +:< *description* +| label +: +: - +: Label of the item +| label. +: - +: - +: Labels support all _text_ properties + +## Scripting properties + +[[ *property* +:[ *value* +:[ *default* +:< *description* +| script +: , +: - +: Script to run on an event +| click_script +: , +: - +: Script to run on a mouse click +| update_freq +: +: 0 +: Time in seconds between routine script executions (0 means never) +| updates +: , when_shown +: on +: If and when the item updates e.g. via script execution +| mach_helper +: +: - +: Registers a helper for direct event notifications + + +Note: +- *click_script* is different to a *mouse.clicked* event. See + https://github.com/FelixKratz/SketchyBar/discussions/109 +- An example of *mach_helper* can be found at + https://github.com/FelixKratz/SketchyBarHelper + +## Text properties + +[[ *text_property* +:[ *value* +:[ *default* +:< *description* +| drawing +: +: on +: If the text is rendered +| highlight +: +: off +: If the text uses the highlight_color or the regular color +| color +: +: 0xffffffff +: Color used to render the text +| highlight_color +: +: 0xff000000 +: Highlight color of the text (e.g. for active space icon +| padding_left +: +: 0 +: Padding to the left of the text +| padding_right +: +: 0 +: Padding to the right of the text +| y_offset +: +: 0 +: Vertical offset applied to the text +| font +: :: +: Hack Nerd Font:Bold:14.0 +: The font to be used for the text +| font.family +: +: Hack Nerd Font +: The font family to be used for the text +| font.style +: +: Bold +: The font style to be used for the text +| font.size +: +: 14.0 +: The font size to be used for the text +| string +: +: - +: Sets the text to the specified string +| width +: 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. +: - +: - +: Texts support all background properties +| shadow. +: - +: - +: Texts support all shadow properties + +## Background properties + +[[ *background_property* +:[ *value* +:[ *default* +:< *description* +| drawing +: +: off +: If the background should be rendered +| color +: +: 0x00000000 +: Fill color of the background +| border_color +: +: 0x00000000 +: Color of the backgrounds border +| border_width +: +: 0 +: Width of the background border +| height +: +: 0 +: Overrides the height of the background +| corner_radius +: +: 0 +: Corner radius of the background +| padding_left +: +: 0 +: Padding to the left of the background +| padding_right +: +: 0 +: Padding to the right of the background +| y_offset +: +: 0 +: Vertical offset applied to the background +| clip +: +: 0.0 +: By how much the background clips the bar (i.e. transparent holes in the bar) +| image +: , app. +: - +: The path to a png or jpeg image file, or a bundle identifier of an application +| image. +: - +: - +: Backgrounds support all image properties +| shadow. +: - +: - +: Backgrounds support all shadow properties + +## Image properties + +[[ *image_property* +:[ *value* +:[ *default* +:< *description* +| drawing +: +: off +: If the image should draw +| scale +: +: 1.0 +: The scale factor that should be applied to the image + +## Shadow properties + +[[ *shadow_property* +:[ *value* +:[ *default* +:< *description* +| drawing +: +: off +: If the shadow should be drawn +| color +: +: 0xff000000 +: Color of the shadow +| angle +: +: 30 +: Angle of the shadow +| distance +: +: 5 +: Distance of the shadow + +# EXAMPLES + +To set the default values that are applied to all further items, put something +similar to this in the configuration file before all *--set* commands: + +``` +sketchybar --default \\ + icon.font="Hack Nerd Font:Bold:17.0" \\ + icon.color=0xffffffff \\ + label.font="Hack Nerd Font:Bold:14.0" \\ + label.color=0xffffffff \\ + padding_left=5 \\ + padding_right=5 \\ + label.padding_left=4 \\ + label.padding_right=4 \\ + icon.padding_left=4 \\ + icon.padding_right=4 +``` + +To add a simple clock item on the left part of the bar: + +``` +pos=left +name=clock +sketchybar --add item $name $pos \\ + --set $name update_freq=60 icon.drawing=off \\ + script='sketchybar --set $NAME label="$(date "+%a %m%d %H%M")"' +``` + +To add a battery item on the right part wherein the item updates based on +*system_woke* and *power_source_change* events (see *sketchybar-events*(5)) and +uses some battery.sh script somewhere: + +``` +dir="$CONFIG_DIR"/plugins +pos=right +name=battery +sketchybar --add item $name $pos \\ + --set $name update_freq=120 script="$dir/battery.sh" \\ + --subscribe $name system_woke power_source_change +``` + +# SEE ALSO + +*sketchybar*(1) +*sketchybar*(5) +*sketchybar-components*(5) +*sketchybar-popup*(5) +*sketchybar-events*(5) +*sketchybar-query*(5) +*sketchybar-animate*(5) +*sketchybar-types*(5) +*sketchybar-tips*(5) diff --git a/docs/sketchybar-popup.5.scd b/docs/sketchybar-popup.5.scd new file mode 100644 index 00000000..2e06c2de --- /dev/null +++ b/docs/sketchybar-popup.5.scd @@ -0,0 +1,114 @@ +sketchybar-popup(5) + +# NAME + +sketchybar-popup - configuration of popup menus + +# SYNOPSIS + +*sketchybar --set* _NAME_ *popup*._PROPERTY_=_VALUE_ + +# DESCRIPTION + +Popup menus are a powerful way to make further items accessible in a small popup +window below any bar item. Every item and component can have a popup menu. + +# OPTIONS + +*--set* _NAME_ *popup*._PROPERTY_=_VALUE_ + Change the popup properties of an item or a component. Inherits the usual + *--set* command usage. A list of properties available can be found in + PROPERTIES. See below. + + 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. + +# PROPERTIES + +[[ *popup_property* +:[ *value* +:[ *default* +:< *description* +| drawing +: +: off +: If the popup should be rendered +| horizontal +: +: off +: If the popup should render horizontally +| topmost +: +: on +: If the popup should always be on top of all other windows +| height +: +: bar height +: The vertical spacing between items in a popup +| blur_radius +: +: 0 +: The blur applied to the popup background +| y_offset +: +: 0 +: Vertical offset applied to the popup +| align +: left, right, center +: left +: Alignment of the popup with its parent item in the bar +| background. +: - +: - +: Popups have a background and support all properties + + +# EXAMPLES + +To get a simple popup menu that allows us to either go to System Settings or +Activity Monitor, or lock the screen: + +``` +sketchybar -m --bar blur_radius=50 height=32 \\ + --add item apple.logo left \\ + --set apple.logo icon=🍎 \\ + icon.font="SF Pro:Black:16.0" \\ + label.drawing=off \\ + click_script='sketchybar -m --set $NAME popup.drawing=toggle' \\ + popup.background.border_width=2 \\ + popup.background.corner_radius=3 \\ + popup.background.border_color=0xff9dd274 \\ + --default \\ + background.padding_left=5 \\ + background.padding_right=5 \\ + icon.padding_right=5 \\ + icon.font="SF Pro:Bold:16.0" \\ + label.font="SF Pro:Semibold:13.0" \\ + --add item apple.preferences popup.apple.logo \\ + --set apple.preferences icon=⚙ label="Settings" \\ + click_script="open -a 'System Settings'; + sketchybar -m --set apple.logo popup.drawing=off" \\ + --add item apple.activity popup.apple.logo \\ + --set apple.activity icon=🔍 label="Activity" \\ + click_script="open -a 'Activity Monitor'; + sketchybar -m --set apple.logo popup.drawing=off" \\ + --add item apple.lock popup.apple.logo \\ + --set apple.lock icon=🔒 label="Lock Screen" \\ + click_script="pmset displaysleepnow; + sketchybar -m --set apple.logo popup.drawing=off" +``` + +More examples be found at +https://github.com/FelixKratz/SketchyBar/discussions/12?sort=new#discussioncomment-1843975 + +# SEE ALSO + +*sketchybar*(1) +*sketchybar*(5) +*sketchybar-items*(5) +*sketchybar-components*(5) +*sketchybar-events*(5) +*sketchybar-query*(5) +*sketchybar-animate*(5) +*sketchybar-types*(5) +*sketchybar-tips*(5) diff --git a/docs/sketchybar-query.5.scd b/docs/sketchybar-query.5.scd new file mode 100644 index 00000000..03b753bb --- /dev/null +++ b/docs/sketchybar-query.5.scd @@ -0,0 +1,44 @@ +sketchybar-query(5) + +# NAME + +sketchybar-query - query information about bar, items, events, etc. + +# SYNOPSIS + +*sketchybar --query* *bar*|_NAME_|*defaults*|*events*|*default_menu_items* + +# DESCRIPTION + +Sketchybar can be queried for information about a number of things. + +# OPTIONS + +*--query bar* + Output a json structure with info about the bar. + +*--query* _NAME_ + Output a json structure with info about a specific item referred to by _NAME_. + +*--query defaults* + Output a json structure with info about the current defaults. + +*--query events* + Output a json structure with info about events. + +*--query default_menu_items* + Output a json structure with the names of the menu bar items in the + default macOS bar. This is useful for configuring aliases (see + *sketchybar-components*(5)). + +# SEE ALSO + +*sketchybar*(1) +*sketchybar*(5) +*sketchybar-items*(5) +*sketchybar-components*(5) +*sketchybar-popup*(5) +*sketchybar-events*(5) +*sketchybar-animate*(5) +*sketchybar-types*(5) +*sketchybar-tips*(5) diff --git a/docs/sketchybar-tips.5.scd b/docs/sketchybar-tips.5.scd new file mode 100644 index 00000000..428de1f0 --- /dev/null +++ b/docs/sketchybar-tips.5.scd @@ -0,0 +1,155 @@ +sketchybar-tips(5) + +# NAME + +sketchybar-tips(5) - useful configuration tips and tricks + +# TIPS & TRICKS + +## 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. Consider these 5 individual configuration calls to +sketchybar: +``` +sketchybar --bar position=top +sketchybar --bar margin=5 +sketchybar --add item demo left +sketchybar --set demo label=Hello +sketchybar --subscribe demo system_woke +``` + +After each configuration command, the bar is redrawn (if needed). Thus it is +faster to append these calls into a single command as in +``` +sketchybar --bar position=top \\ + margin=5 \\ + --add item demo left \\ + --set demo label=Hello \\ + --subscribe demo system_woke +``` + +The use of backslashes at the end of the first four lines is a posix-compliant +(includes bash, zsh) way in shell scripting to join lines together. It should +not be followed by a whitespace. + +## Using arrays for cleaner configuration + +Assume bash. Consider the bar configuration command +``` +sketchybar --bar \\ + height=32 \\ + blur_radius=30 \\ + position=top \\ + sticky=off \\ + padding_left=10 \\ + padding_right=10 \\ + color=0x15ffffff +``` + +You can rewrite this as an array to get rid of the backslashes and pass the +contents of the array to the *--bar* command as in +``` +bar=( + height=32 + blur_radius=30 + position=top + sticky=off + padding_left=10 + padding_right=10 + color=0x15ffffff +) +sketchybar --bar "${bar[@]}" +``` + +## Debugging problems + +If you are experiencing problems with the configuration process, it might be +helpful to work through the following steps: + +. Start sketchybar directly from the commandline to see the verbose error or, + warning messages. +. Make sure you have no trailing whitespaces after the newline escape character + *\\*. +. Make sure your scripts are made executable (that is via chmod +x script.sh). +. Reduce the configuration to a minimal example and narrow down the problematic + region. +. Try running erroneous scripts directly in the command line. +. Query sketchybar for relevant properties and use them to deduce the, + problems root cause. +. Create and file an issue at https://github.com/FelixKratz/SketchyBar/issues. + A second pair of eyes might now be the only thing that helps. + +## Color picker + +Sketchybar uses the argb hex color format, which means: *0xAARRGGBB* encodes a +color. If you are looking for colors, check out the color picker at +https://felixkratz.github.io/SketchyBar/config/bar + +## Finding icons + +The default font sketchybar uses is the *Hack Nerd Font*. This means all +*Nerdfont* icons can be used. Refer to the Nerdfont cheat-sheet at +https://www.nerdfonts.com/cheat-sheet to find new icons. + +Additionally, it is possible to use other icons and glyphs from different fonts, +such as the *sf-symbols* (see https://developer.apple.com/sf-symbols) from Apple. +Those symbols can be installed via brew: +``` +brew install --cask sf-symbols +``` + +After installing this package, an app called *SF Symbols* will be available +where you can find all the available icons. Once you find a fitting icon, right +click it, select _Copy Symbol_ and paste it in the relevant configuration file. + +If you are looking for stylised app icons, you might want to checkout the +excellent community maintained app-icon-font for sketchybar (see +https://github.com/kvndrsslr/sketchybar-app-font). + +## Multiple bars + +It is possible to have multiple independent instances of SketchyBar running. +This is possible by changing the *argv[0]* of the sketchybar program. This is +very easy: do symlink the sketchybar binary with a different name (e.g. +*bottom_bar*) as in +``` +ln -s $(which sketchybar) $(dirname $(which sketchybar))/bottom_bar +``` + +This symlink can now be used to spawn and target an additional bar. For this +bar, you do not call *sketchybar --bar color=0xffff0000* but rather +*bottom_bar --bar color=0xffff0000*. You also start it by running *bottom_bar* in +the command line. + +The config path for this additional bar is in _$HOME/.config/bottom_bar/_. Of +course *bottom_bar* is only an example and can be freely replaced with any other +identifier. + +## Performance optimizations + +Sketchybar can be configured to have a *very* small performance footprint. We +highlight some optimizations that can be used to reduce the footprint further: +- batch together configuration commands where possible +- 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 whenever possible +- do not add *aliases* to apps that are not always running; otherwise sketchybar + searches for them continuously +- (Advanced, only >=v2.9.0) use compiled *mach_helper* programs that + directly interface with sketchybar. An example for performance sensitive + tasks can be found at https://github.com/FelixKratz/SketchyBarHelper + +# SEE ALSO + +*sketchybar*(1) +*sketchybar*(5) +*sketchybar-items*(5) +*sketchybar-components*(5) +*sketchybar-popup*(5) +*sketchybar-events*(5) +*sketchybar-query*(5) +*sketchybar-animate*(5) +*sketchybar-types*(5) diff --git a/docs/sketchybar-types.5.scd b/docs/sketchybar-types.5.scd new file mode 100644 index 00000000..41e664c3 --- /dev/null +++ b/docs/sketchybar-types.5.scd @@ -0,0 +1,78 @@ +sketchybar-types(5) + +# NAME + +sketchybar-types - nomenclature of all value types + +# DESCRIPTION + +The nomenclature of all value types used in the other *sketchybar*(5) man pages +is described here. + +# TYPE NOMENCLATURE + +[[ *type* +:< *values* +| +: on, off, yes, no, true, false, 1, 0, toggle +| +: Color as an 8 digit hex with alpha, red, green and blue channels +| +: An absolute file path +| +: Any UTF-8 string or symbol +| +: A floating point number +| +: An integer +| +: A positive integer +| +: A comma separated list of positive integers + +## Further operations + +All properties can be negated with an exclamation mark, e.g. *!on*. + +## Further operations + +All colors (i.e. all fields where the value type is ) can additionally +be accessed to change specific channels like this: + +[[ *color_property* +:[ *value* +:[ *default* +:< *description* +| alpha +: +: 1.0 +: The alpha channel of the color (0 to 1) +| red +: +: 1.0 +: The red channel of the color (0 to 1) +| green +: +: 1.0 +: The green channel of the color (0 to 1) +| blue +: +: 1.0 +: The blue channel of the color (0 to 1) + +# EXAMPLES + +If the alpha channel of the bar color is the only change needed, execute + sketchybar --bar color.alpha=0.5 + +# SEE ALSO + +*sketchybar*(1) +*sketchybar*(5) +*sketchybar-items*(5) +*sketchybar-components*(5) +*sketchybar-popup*(5) +*sketchybar-events*(5) +*sketchybar-query*(5) +*sketchybar-animate*(5) +*sketchybar-tips*(5) diff --git a/docs/sketchybar.1.scd b/docs/sketchybar.1.scd new file mode 100644 index 00000000..3fd01a81 --- /dev/null +++ b/docs/sketchybar.1.scd @@ -0,0 +1,215 @@ +sketchybar(1) + +# NAME + +sketchybar - custom macOS statusbar with shell plugin, interaction and graph +support + +# SYNOPSIS + +*sketchybar* ++ +*sketchybar --config* _FILE_ ++ +*sketchybar --reload* [_CONFIG_FILE_] ++ +*sketchybar --hotload* _BOOLEAN_ + +*sketchybar --bar* _SETTING_=_VALUE_ ... _SETTING_=_VALUE_ + +*sketchybar --add item* _NAME_ _POSITION_ ++ +*sketchybar --set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++ +*sketchybar --default* _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++ +*sketchybar --reorder* _NAME_ ... _NAME_ ++ +*sketchybar --move* _NAME_ *before*|*after* _REFERENCE_NAME_ ++ +*sketchybar --clone* _PARENT_NAME_ _NAME_ [*before*|*after*] ++ +*sketchybar --rename* _OLD_NAME_ _NEW_NAME_ ++ +*sketchybar --remove* _NAME_ + +*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_ + +*sketchybar --set* _NAME_ *popup*._PROPERTY_=_VALUE_ + +*sketchybar --add event* _NAME_ [_NSDistributedNotificationName_] ++ +*sketchybar --subscribe* _NAME_ _EVENT_ ... _EVENT_ ++ +*sketchybar --trigger* _NAME_ [_ENVVAR_=_VALUE_ ... _ENVVAR_=_VALUE_] ++ +*sketchybar --update* + +*sketchybar --query* *bar*|_NAME_|*defaults*|*events*|*default_menu_items* + +*sketchybar --animate* _CURVE_ _DURATION_ *--bar* _SETTING_=_VALUE_ ... +_SETTING_=_VALUE_ ++ +*sketchybar --animate* _CURVE_ _DURATION_ *--set* _PROPERTY_=_VALUE_ ... +_PROPERTY_=_VALUE_ + +# OPTIONS + +*--config* _FILE_ + Specify an alternative configuration file. The default one found at + _$HOME/.config/sketchybar/sketchybarrc_ is automatically read when sketchybar + is launched. + +*--reload* [_CONFIG_FILE_] + Reload the bar without manually restarting the process. Essentially, this + has the same effect as restarting the process, but is a bit more convenient. + Additionally, an optional path to a new _CONFIG_FILE_ can be given to load + a different configuration. If the optional argument is left out, the current + configuration is reloaded. + +*--hotload* _BOOLEAN_ + Enables the hotload feature. If you wish that the bar automatically reloads + the configuration file once it is edited, the hotload functionality can be used. + It will monitor the directory of the current configuration for changes and + reload the configuration should it detect file changes. + +For the other commands, see CONFIGURATION below for the relevant man page. + +# DESCRIPTION + +*sketchybar* aims to create a highly flexible, customizable, fast and powerful +status bar replacement for people that like playing with shell scripts. + +Its features include +- performance friendly +- fully scriptable +- fully configurable (fonts, backgrounds, colors, icons, etc.) +- support for drawing native macOS menu bar applications (aliases) +- powerful event and scripting system +- animation system +- popup menus +- mouse support +- support for graphs +- per display and per space individualization. + +The _bar_ 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. + +Furthermore, an item can be assigned to mission control spaces or displays, +such that they only show on a certain space or display. This makes +multi-desktop configuration of the bar possible. This also 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. Some +special features can not be accomplished with a simple item. This is where the +_components_ come into play which 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 CONFIGURATION. + +# CONFIGURATION + +A sketchybar configuration file is a regular shell script file that resides +at _$HOME/.config/sketchybar/sketchybarrc_. It is executed when sketchybar +launches. Everything persistent should be set up in this file. + +It is possible to play with properties in the commandline and change them on the +fly while the bar is running. Once a fitting value is found, the configuration +can then be included in the configuration file. The configuration is then +restored on restart. + +When configuring the bar, it can be helpful to *stop the brew service* and *run +sketchybar* from the commandline directly to see all relevant error messages +and warnings directly. + +Refer to +- *sketchybar*(1) (this man page) for the overview of sketchybar +- *sketchybar*(5) to configure the bar +- *sketchybar-items*(5) to configure items +- *sketchybar-components*(5) to configure special components +- *sketchybar-popup*(5) to configure popup menus +- *sketchybar-events*(5) to configure events and scripting +- *sketchybar-query*(5) to query information +- *sketchybar-animate*(5) to animate +- *sketchybar-types*(5) for the nomenclature of the value types used in sketchybar +- *sketchybar-tips*(5) for configuration tips and tricks. + +# SETUP + +## Running sketchybar + +Run the bar automatically at startup: +``` +brew services start sketchybar +``` + +or in the command line with verbose output: +``` +sketchybar +``` + +## Fonts + +The default sketchybar font is the Hack Nerd Font. To install: +``` +brew tap homebrew/cask-fonts +brew install --cask font-hack-nerd-font +``` + +If there exists missing icons, you might need to install it. Any font of your +liking can be used in sketchybar. + +## Plugins + +When additional plugins are used or created, make sure that they are made +executable via +``` +chmod +x name_of_plugin.sh +``` + +If sketchybar is run from the command line directly with the command +*sketchybar*, all outputs and error messages from scripts will be printed in +stdout. + +The default plugin folder is located in _$HOME/.config/sketchybar/plugins_. +Plugins need to be referenced with absolute paths because relative paths will +not be resolved correctly. + +Have a look at the discussion for plugins and share your own if you want to. +Just make sure to vet the code from all plugins before executing them to make +sure they are not harming your computer. + +## Hiding the system menu bar + +To hide the original macOS bar in +- pre-Ventura: go to _System Preferences_ > _Dock & Menu Bar_, then check the + _Automatically hide and show the menu bar_ option +- Ventura: go to _System Settings_ > _Desktop & Dock_, then set the + _Automatically hide and show the menu bar_ option to _Always_ +- Sonoma: go to _System Settings_ > _Control Center_, then set the + _Automatically hide and show the menu bar_ option to _Always_. + +# SEE ALSO + +*sketchybar*(5) +*sketchybar-items*(5) +*sketchybar-components*(5) +*sketchybar-popup*(5) +*sketchybar-events*(5) +*sketchybar-query*(5) +*sketchybar-animate*(5) +*sketchybar-types*(5) +*sketchybar-tips*(5) + +# BUGS + +Report them at https://github.com/FelixKratz/Sketchybar/issues. + +# CREDITS + +*Sketchybar* was forked from *spacebar* (see https://github.com/cmacrae/spacebar) +and completely reimagined and rewritten. The original idea is based on the +status bar that was included in *yabai* (see +https://github.com/koekeishiya/yabai) before getting removed. + +# MAINTAINERS + +Felix Kratz diff --git a/docs/sketchybar.5.scd b/docs/sketchybar.5.scd new file mode 100644 index 00000000..7052302c --- /dev/null +++ b/docs/sketchybar.5.scd @@ -0,0 +1,119 @@ +sketchybar(5) + +# NAME + +sketchybar - configuration of the bar + +# SYNOPSIS + +*sketchybar --bar* _SETTING_=_VALUE_ ... _SETTING_=_VALUE_ + +# SETTINGS + +The possible settings to configure the bar include + +[[ *setting* +:[ *value* +:[ *default* +:< *description* +| color +: +: 0x44000000 +: Color of the bar +| border_color +: +: 0xffff0000 +: Color of the bars border +| position +: top, bottom +: top +: Position of the bar on the screen +| height +: +: 25 +: Height of the bar +| margin +: +: 0 +: Margin around the bar +| y_offset +: +: 0 +: Vertical offset of the bar from its default position +| corner_radius +: +: 0 +: Corner radius of the bar +| border_width +: +: 0 +: Border width of the bars border +| blur_radius +: +: 0 +: Blur radius applied to the background of the bar +| padding_left +: +: 0 +: Padding between the left bar border and the leftmost item +| padding_right +: +: 0 +: Padding between the right bar border and the rightmost item +| notch_width +: +: 200 +: The width of the notch to be accounted for on the internal display +| notch_offset +: +: 0 +: Additional y_offset exclusively applied to notched screens +| display +: main, all, +: all +: Display to show the bar on +| hidden +: , current +: off +: If all / the current bar is hidden +| topmost +: , window +: off +: If the bar should be drawn on top of everything, or on top of all windows +| sticky +: +: off +: Makes the bar sticky (only use with disabled space change animations [See issue #220] +| font_smoothing +: +: off +: If fonts should be smoothened +| shadow +: +: off +: If the bar should draw a shadow + +# EXAMPLES + +``` +sketchybar --bar \\ + height=32 \\ + blur_radius=30 \\ + position=top \\ + sticky=off \\ + padding_left=10 \\ + padding_right=10 \\ + color=0x15ffffff +``` + +# SEE ALSO + +*sketchybar*(1) +*sketchybar-items*(5) +*sketchybar-components*(5) +*sketchybar-popup*(5) +*sketchybar-events*(5) +*sketchybar-query*(5) +*sketchybar-animate*(5) +*sketchybar-types*(5) +*sketchybar-tips*(5) From f865fa7811d99c5aacfbb57a3092d5cb5317237f Mon Sep 17 00:00:00 2001 From: Felix Kratz Date: Sat, 14 Oct 2023 00:06:51 +0200 Subject: [PATCH 2/4] formatting and slight modifications fixup --- docs/build.sh | 12 ++++ docs/sketchybar-animate.5.scd | 48 ++++++------- docs/sketchybar-components.5.scd | 113 ++++++++++++------------------- docs/sketchybar-events.5.scd | 91 ++++++++++++------------- docs/sketchybar-items.5.scd | 55 ++++++--------- docs/sketchybar-popup.5.scd | 45 +++++------- docs/sketchybar-query.5.scd | 16 ++--- docs/sketchybar-tips.5.scd | 25 ++++--- docs/sketchybar-types.5.scd | 17 ++--- docs/sketchybar.1.scd | 27 ++++---- docs/sketchybar.5.scd | 16 ++--- 11 files changed, 215 insertions(+), 250 deletions(-) create mode 100755 docs/build.sh diff --git a/docs/build.sh b/docs/build.sh new file mode 100755 index 00000000..a81e1d18 --- /dev/null +++ b/docs/build.sh @@ -0,0 +1,12 @@ +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 diff --git a/docs/sketchybar-animate.5.scd b/docs/sketchybar-animate.5.scd index 42509774..fc1501de 100644 --- a/docs/sketchybar-animate.5.scd +++ b/docs/sketchybar-animate.5.scd @@ -14,23 +14,23 @@ _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. +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 changed in between. This is a nice way to create custom -animations with key-frames. +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. +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. +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 @@ -38,18 +38,18 @@ beginning at the current state. *--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. + 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 +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 ``` @@ -58,12 +58,12 @@ 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*(1)++ +*sketchybar*(5)++ +*sketchybar-items*(5)++ +*sketchybar-components*(5)++ +*sketchybar-popup*(5)++ +*sketchybar-events*(5)++ +*sketchybar-query*(5)++ +*sketchybar-types*(5)++ *sketchybar-tips*(5) diff --git a/docs/sketchybar-components.5.scd b/docs/sketchybar-components.5.scd index 69291fee..7493c180 100644 --- a/docs/sketchybar-components.5.scd +++ b/docs/sketchybar-components.5.scd @@ -13,21 +13,15 @@ _DATA_POINT_ ... _DATA_POINT_ ++ *sketchybar --add alias* _APPLICATION_NAME_|"_WINDOW_OWNER_,_WINDOW_NAME_" _POSITION_ ++ *sketchybar --add slider* _NAME_ _POSITION_ _WIDTH_ -*sketchybar --set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++ -*sketchybar --default* _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++ -*sketchybar --reorder* _NAME_ ... _NAME_ ++ -*sketchybar --move* _NAME_ *before*|*after* _REFERENCE_NAME_ ++ -*sketchybar --clone* _PARENT_NAME_ _NAME_ [*before*|*after*] ++ -*sketchybar --rename* _OLD_NAME_ _NEW_NAME_ ++ -*sketchybar --remove* _NAME_ - # DESCRIPTION -Components are essentially items, but with special properties. -Currently, there available components include +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*: brackets other items together +- *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. @@ -74,11 +68,13 @@ a redefinition below. ## Notes Graphs usually take the entire height of the bar as a drawing canvas. However, -if a background is set for the graph item and for its height, the graph -will draw inside of the background. With a background enabled, the graph can -also be moved via a *y_offset*, say, +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 +sketchybar --set graph_name background.color=0xff00ff00 \\ + background.height=20 \\ + y_offset=2 ``` @@ -94,15 +90,16 @@ sketchybar --set graph_name background.color=0xff00ff00 background.height=20 y_o 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. + - *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 dditional variables available for *script* and +This component provides additional variables available for *script* and *click_script*: - *$SELECTED*: has the value *true* if the associated space is selected; otherwise *false* @@ -113,7 +110,7 @@ By default, this component invokes the script ``` sketchybar --set $NAME icon.highlight=$SELECTED ``` -which can then be freely configured by supplying a different script: +which can be freely configured by supplying a different script: ``` sketchybar --set space_name script=path/to/script ``` @@ -147,9 +144,9 @@ 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 + --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, @@ -175,7 +172,8 @@ those items. 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_. + by providing a _WINDOW_OWNER_ and _WINDOW_NAME_. See the note below how to + list all available widgets. Then, say, the default system items can be aliased as in: - "Control Center,Bluetooth" @@ -210,8 +208,8 @@ those items. ## Notes -All other macOS menu bar items currently available on the system with their -respective owners and names can be listed via (see *sketchybar-query*(5)) +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 ``` @@ -261,64 +259,43 @@ sketchybar --query default_menu_items ## Notes -The slider can be enabled to receive *mouse.clicked* events by subscribing -to this event. +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. +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 posix shell and without yabai scripting additions: - -``` -pos=left -name=space -set -- 1 2 3 4 5 6 7 8 9 -sid=0 -for win in "$@" -do sid=$((sid+1)) - sketchybar --add $name $name.$sid $pos \\ - --set $name.$sid associated_space=$sid icon.drawing=off label="$win" \\ - script='sketchybar --set $NAME background.border_width=1 \\ - background.padding_left=5 background.drawing=$SELECTED' \\ - click_script="skhd -k ctrl\\ -\\ $sid" -done -sketchybar --add bracket spaces "/$name\..*/" -``` - -Or, in bash and with scripting additions: +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]} \\ - background.color=0x44ffffff \\ - background.corner_radius=5 \\ - background.height=20 \\ - background.drawing=off \\ - label.drawing=off \\ - script="CONFIG_DIR/plugins/space.sh" \\ - click_script="yabai -m space --focus $sid" + \--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 by synthetically emitting the space focus keyboard shortcuts via +skhd) # 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*(1)++ +*sketchybar*(5)++ +*sketchybar-items*(5)++ +*sketchybar-popup*(5)++ +*sketchybar-events*(5)++ +*sketchybar-query*(5)++ +*sketchybar-animate*(5)++ +*sketchybar-types*(5)++ *sketchybar-tips*(5) diff --git a/docs/sketchybar-events.5.scd b/docs/sketchybar-events.5.scd index a4060a7e..0550f964 100644 --- a/docs/sketchybar-events.5.scd +++ b/docs/sketchybar-events.5.scd @@ -13,25 +13,23 @@ sketchybar-events - configuration of events and scripting # DESCRIPTION -All items can subscribe to arbitrary events. When the event happens, all items -subscribed to the event will execute their scripts. This mechanism can be used -to create more reactive and performant items which react to events rather than -to polled changes. - -Some events send additional information through the *$INFO* environment variable. -When an item is subscribed to these events, the script is run and the *$SENDER* -variable is passed. This variable holds the event name (see EVENTS) to -distinguish between the different events. -It is thus possible to have a script that reacts differently to various events -(consider: a switch statement via shell's *case* command for the *$SENDER* -variable in the *script*). +All items can subscribe to events. When an event is triggered, all items +subscribed to this event will execute their scripts. This mechanism can be +used to create more reactive and performant items which react to events rather +than to poll changes. + +Some events send additional information through the *$INFO* environment +variable. When a script is run due to an event the *$SENDER* variable is passed. +This variable holds the event name (see EVENTS) and can be used to distinguish +between different events in a script. It is thus possible to have a script +that reacts differently to various events (consider: a switch statement via +shell's *case* command for the *$SENDER* variable in the *script*). Alternatively, a fixed *update_freq* can be *--set* such that the event is routinely run to poll for changes. Here, the *$SENDER* variable will hold the value *routine*. -An item invokes a script, the script has access to some environment variables -such as +All scripts invoked by an item have access to some environment variables such as - *$NAME* - *$SENDER* - *$CONFIG_DIR* @@ -39,20 +37,21 @@ where *$NAME* is the name of the item that invoked the script and *$SENDER* is the reason why the script was executed. *$CONFIG_DIR* holds the value of the absolute path of the directory where the current configuration file is located. -If an item is *clicked*, the script (that is *click_script*) has access to the -additional variables such as +If an item is *clicked*, the script being called (either *click_script* or the +*script* when subscribed to *mouse.clicked*) has access to the additional +variables such as - *$BUTTON* - *$MODIFIER* -where *$BUTTON* can have a value of *left*, *right* or *other*, and does specify -the mouse button that was used to click the item. Whereas, *$MODIFIER* can be -*shift*, *ctrl*, *alt* or *cmd*, and does specify the modifier key held down while -clicking the item. +where *$BUTTON* can have a value of *left*, *right* or *other*, and does +specify the mouse button that was used to click the item. Whereas, *$MODIFIER* +can be *shift*, *ctrl*, *alt* or *cmd*, and does specify the modifier key held +down while clicking the item. If an item receives a *scroll* event from the mouse, the script sends the additional *$SCROLL_DELTA* variable. -All scripts are *forced* to terminate after 60 seconds and do not run while the -system is sleeping. +All scripts are *forced* to terminate after 60 seconds and do not run while +the system is sleeping. # OPTIONS @@ -61,14 +60,14 @@ system is sleeping. Optionally, an event can use the notifications sent to macOS's notification system by specifying the relevant _NSDistributedNotificationName_. - For example, Spotify notifies the system on track change via + For example, Spotify notifies the system on track change via *com.spotify.client.PlaybackStateChanged*, and the system notifies itself when the screen is unlocked via *com.apple.screenIsUnlocked*. - Custom events that subscribe to *NSDistributedNotificationCenter* notifications - will receive additional notification information through the *$INFO* variable - if available. - + Custom events that subscribe to *NSDistributedNotificationCenter* + notifications will receive additional notification information through the + *$INFO* variable if available. + For more on *NSDistributedNotifications*, see https://github.com/FelixKratz/SketchyBar/discussions/151 @@ -77,14 +76,14 @@ system is sleeping. A list of events can be found in EVENTS. See below. *--trigger* _NAME_ [_ENVVAR_=_VALUE_ ... _ENVVAR_=_VALUE_] - Trigger the added custom event. Optionally, an event can send an environment - variable _ENVVAR with value _VALUE_ (or a series of such variables) to the - trigger command then pass them to *script* or *click_script*. + Trigger any custom event. Optionally, specify _ENVVAR with value _VALUE_ + (or a series of such variables) to pass them on to the *script* or + *click_script*. *--update* - Forces all *scripts* to run and all *events* to be emitted. This should - *NEVER* be used in an item script as this would lead to infinite loops. - But, this is prominently needed after the initial configuration to properly + Forces all *scripts* to run and all *events* to be emitted. This should + *NEVER* be used in an item script as this would lead to infinite loops. + But, this is prominently needed after the initial configuration to properly initialize all the items by forcing all their scripts to run. # EVENTS @@ -147,23 +146,23 @@ system is sleeping. # EXAMPLES -A simple plugin that uses the com.spotify.client.PlaybackStateChanged* -*notification sent by Spotify can be found at +A simple plugin that uses the com.spotify.client.PlaybackStateChanged* +*notification sent by Spotify can be found at https://github.com/FelixKratz/SketchyBar/discussions/12#discussioncomment-1455842 -A more advanced plugin that uses the *com.apple.screenIsUnlocked* notification -sent by the system and the animation feature (see *sketchybar-animate*(5)) can -be found at +A more advanced plugin that uses the *com.apple.screenIsUnlocked* notification +sent by the system and the animation feature (see *sketchybar-animate*(5)) can +be found at https://github.com/FelixKratz/SketchyBar/discussions/12?sort=new#discussioncomment-2979651 # SEE ALSO -*sketchybar*(1) -*sketchybar*(5) -*sketchybar-items*(5) -*sketchybar-components*(5) -*sketchybar-popup*(5) -*sketchybar-query*(5) -*sketchybar-animate*(5) -*sketchybar-types*(5) +*sketchybar*(1) ++ +*sketchybar*(5) ++ +*sketchybar-items*(5) ++ +*sketchybar-components*(5) ++ +*sketchybar-popup*(5) ++ +*sketchybar-query*(5) ++ +*sketchybar-animate*(5) ++ +*sketchybar-types*(5) ++ *sketchybar-tips*(5) diff --git a/docs/sketchybar-items.5.scd b/docs/sketchybar-items.5.scd index 704f831c..b09dc8e8 100644 --- a/docs/sketchybar-items.5.scd +++ b/docs/sketchybar-items.5.scd @@ -51,8 +51,8 @@ values found here. *--set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ Change the properties of an item. _NAME_ is used to target the item. It can - be a regular expression inside of two slashes: /*REGEX*/. A list of properties - available can be found in PROPERTIES. See below. + be a regular expression inside of two slashes: /*REGEX*/ to target mutliple + items. A list of properties available can be found in PROPERTIES. See below. *--default* _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ Change the defaults at any point in the configuration. All item created @@ -60,9 +60,9 @@ values found here. item. *--reorder* _NAME_ ... _NAME_ - Reorder the items. A new order can be supplied for arbitrary many items. Only the - specified items get reordered. By swapping them around, everything else stays - the same. To swap two items, simply call + Reorder the items. A new order can be supplied for arbitrary many items. Only + the specified items get reordered. By swapping them around, everything else + stays the same. To swap two items, simply call ``` sketchybar --reorder NAME1 NAME2 ``` @@ -72,20 +72,20 @@ values found here. _REFERENCE_NAME_, use *before*. Otherwise, use *after*. *--clone* _PARENT_NAME_ _NAME_ [*before*|*after*] - Clone an item to another item. 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. + Clone an item to another item. 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. *--rename* _OLD_NAME_ _NEW_NAME_ Rename an item. Note that the new name should not be in use by another item. *--remove* _NAME_ Remove an item. _NAME_ can be a regex: /*REGEX*/. The item will be completely - destroyed and removed from brackets. + destroyed and removed from the bar, brackets and popups. # PROPERTIES -This section is relevant to the *--set* and *--default* commands. +This section is relevant for the *--set* and *--default* commands. ## Geometry properties @@ -392,34 +392,19 @@ sketchybar --default \\ To add a simple clock item on the left part of the bar: ``` -pos=left -name=clock -sketchybar --add item $name $pos \\ - --set $name update_freq=60 icon.drawing=off \\ +sketchybar --add item clock left \\ + --set clock update_freq=60 icon.drawing=off \\ script='sketchybar --set $NAME label="$(date "+%a %m%d %H%M")"' ``` -To add a battery item on the right part wherein the item updates based on -*system_woke* and *power_source_change* events (see *sketchybar-events*(5)) and -uses some battery.sh script somewhere: - -``` -dir="$CONFIG_DIR"/plugins -pos=right -name=battery -sketchybar --add item $name $pos \\ - --set $name update_freq=120 script="$dir/battery.sh" \\ - --subscribe $name system_woke power_source_change -``` - # SEE ALSO -*sketchybar*(1) -*sketchybar*(5) -*sketchybar-components*(5) -*sketchybar-popup*(5) -*sketchybar-events*(5) -*sketchybar-query*(5) -*sketchybar-animate*(5) -*sketchybar-types*(5) +*sketchybar*(1)++ +*sketchybar*(5)++ +*sketchybar-components*(5)++ +*sketchybar-popup*(5)++ +*sketchybar-events*(5)++ +*sketchybar-query*(5)++ +*sketchybar-animate*(5)++ +*sketchybar-types*(5)++ *sketchybar-tips*(5) diff --git a/docs/sketchybar-popup.5.scd b/docs/sketchybar-popup.5.scd index 2e06c2de..13f2f990 100644 --- a/docs/sketchybar-popup.5.scd +++ b/docs/sketchybar-popup.5.scd @@ -69,33 +69,22 @@ To get a simple popup menu that allows us to either go to System Settings or Activity Monitor, or lock the screen: ``` -sketchybar -m --bar blur_radius=50 height=32 \\ +sketchybar --bar height=32 \\ --add item apple.logo left \\ - --set apple.logo icon=🍎 \\ - icon.font="SF Pro:Black:16.0" \\ - label.drawing=off \\ - click_script='sketchybar -m --set $NAME popup.drawing=toggle' \\ - popup.background.border_width=2 \\ - popup.background.corner_radius=3 \\ - popup.background.border_color=0xff9dd274 \\ - --default \\ - background.padding_left=5 \\ - background.padding_right=5 \\ - icon.padding_right=5 \\ - icon.font="SF Pro:Bold:16.0" \\ - label.font="SF Pro:Semibold:13.0" \\ + --set apple.logo icon="#Popup#" \\ + click_script='sketchybar --set $NAME popup.drawing=toggle' \\ --add item apple.preferences popup.apple.logo \\ - --set apple.preferences icon=⚙ label="Settings" \\ + --set apple.preferences label="Settings" \\ click_script="open -a 'System Settings'; - sketchybar -m --set apple.logo popup.drawing=off" \\ + sketchybar --set apple.logo popup.drawing=off" \\ --add item apple.activity popup.apple.logo \\ - --set apple.activity icon=🔍 label="Activity" \\ + --set apple.activity label="Activity" \\ click_script="open -a 'Activity Monitor'; - sketchybar -m --set apple.logo popup.drawing=off" \\ + sketchybar --set apple.logo popup.drawing=off" \\ --add item apple.lock popup.apple.logo \\ - --set apple.lock icon=🔒 label="Lock Screen" \\ + --set apple.lock label="Lock Screen" \\ click_script="pmset displaysleepnow; - sketchybar -m --set apple.logo popup.drawing=off" + sketchybar --set apple.logo popup.drawing=off" ``` More examples be found at @@ -103,12 +92,12 @@ https://github.com/FelixKratz/SketchyBar/discussions/12?sort=new#discussioncomme # SEE ALSO -*sketchybar*(1) -*sketchybar*(5) -*sketchybar-items*(5) -*sketchybar-components*(5) -*sketchybar-events*(5) -*sketchybar-query*(5) -*sketchybar-animate*(5) -*sketchybar-types*(5) +*sketchybar*(1)++ +*sketchybar*(5)++ +*sketchybar-items*(5)++ +*sketchybar-components*(5)++ +*sketchybar-events*(5)++ +*sketchybar-query*(5)++ +*sketchybar-animate*(5)++ +*sketchybar-types*(5)++ *sketchybar-tips*(5) diff --git a/docs/sketchybar-query.5.scd b/docs/sketchybar-query.5.scd index 03b753bb..64b95696 100644 --- a/docs/sketchybar-query.5.scd +++ b/docs/sketchybar-query.5.scd @@ -33,12 +33,12 @@ Sketchybar can be queried for information about a number of things. # SEE ALSO -*sketchybar*(1) -*sketchybar*(5) -*sketchybar-items*(5) -*sketchybar-components*(5) -*sketchybar-popup*(5) -*sketchybar-events*(5) -*sketchybar-animate*(5) -*sketchybar-types*(5) +*sketchybar*(1)++ +*sketchybar*(5)++ +*sketchybar-items*(5)++ +*sketchybar-components*(5)++ +*sketchybar-popup*(5)++ +*sketchybar-events*(5)++ +*sketchybar-animate*(5)++ +*sketchybar-types*(5)++ *sketchybar-tips*(5) diff --git a/docs/sketchybar-tips.5.scd b/docs/sketchybar-tips.5.scd index 428de1f0..d969be52 100644 --- a/docs/sketchybar-tips.5.scd +++ b/docs/sketchybar-tips.5.scd @@ -119,14 +119,17 @@ ln -s $(which sketchybar) $(dirname $(which sketchybar))/bottom_bar ``` This symlink can now be used to spawn and target an additional bar. For this -bar, you do not call *sketchybar --bar color=0xffff0000* but rather -*bottom_bar --bar color=0xffff0000*. You also start it by running *bottom_bar* in -the command line. +bar, you do not call *sketchybar --bar color=0xffff0000* but rather +*bottom_bar --bar color=0xffff0000*. You also start it by running *bottom_bar* +in the command line. The config path for this additional bar is in _$HOME/.config/bottom_bar/_. Of course *bottom_bar* is only an example and can be freely replaced with any other identifier. +You can bootstrap the additional bar by invoking it at the very bottom of your +main bar's sketchybarrc. + ## Performance optimizations Sketchybar can be configured to have a *very* small performance footprint. We @@ -144,12 +147,12 @@ highlight some optimizations that can be used to reduce the footprint further: # SEE ALSO -*sketchybar*(1) -*sketchybar*(5) -*sketchybar-items*(5) -*sketchybar-components*(5) -*sketchybar-popup*(5) -*sketchybar-events*(5) -*sketchybar-query*(5) -*sketchybar-animate*(5) +*sketchybar*(1)++ +*sketchybar*(5)++ +*sketchybar-items*(5)++ +*sketchybar-components*(5)++ +*sketchybar-popup*(5)++ +*sketchybar-events*(5)++ +*sketchybar-query*(5)++ +*sketchybar-animate*(5)++ *sketchybar-types*(5) diff --git a/docs/sketchybar-types.5.scd b/docs/sketchybar-types.5.scd index 41e664c3..b0183b77 100644 --- a/docs/sketchybar-types.5.scd +++ b/docs/sketchybar-types.5.scd @@ -33,6 +33,7 @@ is described here. ## Further operations All properties can be negated with an exclamation mark, e.g. *!on*. +Note that you may have to quote the negated expression in certain shells. ## Further operations @@ -67,12 +68,12 @@ If the alpha channel of the bar color is the only change needed, execute # SEE ALSO -*sketchybar*(1) -*sketchybar*(5) -*sketchybar-items*(5) -*sketchybar-components*(5) -*sketchybar-popup*(5) -*sketchybar-events*(5) -*sketchybar-query*(5) -*sketchybar-animate*(5) +*sketchybar*(1)++ +*sketchybar*(5)++ +*sketchybar-items*(5)++ +*sketchybar-components*(5)++ +*sketchybar-popup*(5)++ +*sketchybar-events*(5)++ +*sketchybar-query*(5)++ +*sketchybar-animate*(5)++ *sketchybar-tips*(5) diff --git a/docs/sketchybar.1.scd b/docs/sketchybar.1.scd index 3fd01a81..9fe308d4 100644 --- a/docs/sketchybar.1.scd +++ b/docs/sketchybar.1.scd @@ -2,8 +2,7 @@ sketchybar(1) # NAME -sketchybar - custom macOS statusbar with shell plugin, interaction and graph -support +sketchybar - a highly customizable macOS status bar replacement # SYNOPSIS @@ -60,9 +59,9 @@ _PROPERTY_=_VALUE_ *--hotload* _BOOLEAN_ Enables the hotload feature. If you wish that the bar automatically reloads - the configuration file once it is edited, the hotload functionality can be used. - It will monitor the directory of the current configuration for changes and - reload the configuration should it detect file changes. + the configuration file once it is edited, the hotload functionality can be + used. It will monitor the directory of the current configuration for changes + and reload the configuration should it detect file changes. For the other commands, see CONFIGURATION below for the relevant man page. @@ -113,7 +112,7 @@ launches. Everything persistent should be set up in this file. It is possible to play with properties in the commandline and change them on the fly while the bar is running. Once a fitting value is found, the configuration -can then be included in the configuration file. The configuration is then +can then be included in the configuration file. The configuration is then restored on restart. When configuring the bar, it can be helpful to *stop the brew service* and *run @@ -189,14 +188,14 @@ To hide the original macOS bar in # SEE ALSO -*sketchybar*(5) -*sketchybar-items*(5) -*sketchybar-components*(5) -*sketchybar-popup*(5) -*sketchybar-events*(5) -*sketchybar-query*(5) -*sketchybar-animate*(5) -*sketchybar-types*(5) +*sketchybar*(5)++ +*sketchybar-items*(5)++ +*sketchybar-components*(5)++ +*sketchybar-popup*(5)++ +*sketchybar-events*(5)++ +*sketchybar-query*(5)++ +*sketchybar-animate*(5)++ +*sketchybar-types*(5)++ *sketchybar-tips*(5) # BUGS diff --git a/docs/sketchybar.5.scd b/docs/sketchybar.5.scd index 7052302c..b9e98903 100644 --- a/docs/sketchybar.5.scd +++ b/docs/sketchybar.5.scd @@ -108,12 +108,12 @@ sketchybar --bar \\ # SEE ALSO -*sketchybar*(1) -*sketchybar-items*(5) -*sketchybar-components*(5) -*sketchybar-popup*(5) -*sketchybar-events*(5) -*sketchybar-query*(5) -*sketchybar-animate*(5) -*sketchybar-types*(5) +*sketchybar*(1)++ +*sketchybar-items*(5)++ +*sketchybar-components*(5)++ +*sketchybar-popup*(5)++ +*sketchybar-events*(5)++ +*sketchybar-query*(5)++ +*sketchybar-animate*(5)++ +*sketchybar-types*(5)++ *sketchybar-tips*(5) From b07a1dd7ad96139edfe292c5320a27d28626c495 Mon Sep 17 00:00:00 2001 From: Ralph Torres Date: Sun, 15 Oct 2023 06:05:55 +0000 Subject: [PATCH 3/4] slight modifications --- docs/build.sh | 2 ++ docs/sketchybar-animate.5.scd | 2 +- docs/sketchybar-components.5.scd | 12 ++++++------ docs/sketchybar-events.5.scd | 20 ++++++++++---------- docs/sketchybar-items.5.scd | 2 +- docs/sketchybar-tips.5.scd | 8 ++++---- docs/sketchybar.1.scd | 12 ++++++------ docs/sketchybar.5.scd | 10 +++++++--- 8 files changed, 37 insertions(+), 31 deletions(-) diff --git a/docs/build.sh b/docs/build.sh index a81e1d18..c9fcee9b 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -1,3 +1,5 @@ +#!/bin/sh + rm -rf build mkdir build scdoc < sketchybar-animate.5.scd > build/sketchybar-animate.5 diff --git a/docs/sketchybar-animate.5.scd b/docs/sketchybar-animate.5.scd index fc1501de..117dc656 100644 --- a/docs/sketchybar-animate.5.scd +++ b/docs/sketchybar-animate.5.scd @@ -44,7 +44,7 @@ animation beginning at the current state. 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). +values specified in a configuration command (i.e. *--bar* or *--set* commands). # EXAMPLES diff --git a/docs/sketchybar-components.5.scd b/docs/sketchybar-components.5.scd index 7493c180..05315a79 100644 --- a/docs/sketchybar-components.5.scd +++ b/docs/sketchybar-components.5.scd @@ -116,7 +116,7 @@ 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 +*$SELECTED* variable, i.e. if the associated space has become active or has resigned being active. @@ -172,7 +172,7 @@ those items. 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 how to + 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: @@ -209,7 +209,7 @@ those items. ## 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)) +owners and names can be listed via (see *sketchybar-query*(5)): ``` sketchybar --query default_menu_items ``` @@ -284,9 +284,9 @@ do sid=$(($i+1)) 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 by synthetically emitting the space focus keyboard shortcuts via -skhd) +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 diff --git a/docs/sketchybar-events.5.scd b/docs/sketchybar-events.5.scd index 0550f964..f6ec9a7d 100644 --- a/docs/sketchybar-events.5.scd +++ b/docs/sketchybar-events.5.scd @@ -19,7 +19,7 @@ used to create more reactive and performant items which react to events rather than to poll changes. Some events send additional information through the *$INFO* environment -variable. When a script is run due to an event the *$SENDER* variable is passed. +variable. When a script is run due to an event, the *$SENDER* variable is passed. This variable holds the event name (see EVENTS) and can be used to distinguish between different events in a script. It is thus possible to have a script that reacts differently to various events (consider: a switch statement via @@ -76,7 +76,7 @@ the system is sleeping. A list of events can be found in EVENTS. See below. *--trigger* _NAME_ [_ENVVAR_=_VALUE_ ... _ENVVAR_=_VALUE_] - Trigger any custom event. Optionally, specify _ENVVAR with value _VALUE_ + Trigger any custom event. Optionally, specify _ENVVAR_ with value _VALUE_ (or a series of such variables) to pass them on to the *script* or *click_script*. @@ -93,11 +93,11 @@ the system is sleeping. :< *returned $INFO* | front_app_switched : When the front application changes (not triggered if a different window of - the same app is focused) + the same app is focused) : front application name | space_change : When the active mission control space changes -: JSON for active spaces on all displays +: list of active spaces on all displays in a JSON structure | display_change : When the active display is changed : new active display id @@ -140,19 +140,19 @@ the system is sleeping. | mouse.scrolled : When the mouse is scrolled over an item : scroll wheel delta -| mouse.scrolled.globa +| mouse.scrolled.global : When the mouse is scrolled over an empty region of the bar : scroll wheel delta # EXAMPLES -A simple plugin that uses the com.spotify.client.PlaybackStateChanged* -*notification sent by Spotify can be found at +A simple plugin that uses the *com.spotify.client.PlaybackStateChanged* +notification sent by Spotify can be found at https://github.com/FelixKratz/SketchyBar/discussions/12#discussioncomment-1455842 -A more advanced plugin that uses the *com.apple.screenIsUnlocked* notification -sent by the system and the animation feature (see *sketchybar-animate*(5)) can -be found at +A more advanced plugin that uses the *com.apple.screenIsUnlocked* notification +sent by the system and the animation feature (see *sketchybar-animate*(5)) can +be found at https://github.com/FelixKratz/SketchyBar/discussions/12?sort=new#discussioncomment-2979651 # SEE ALSO diff --git a/docs/sketchybar-items.5.scd b/docs/sketchybar-items.5.scd index b09dc8e8..10d240f0 100644 --- a/docs/sketchybar-items.5.scd +++ b/docs/sketchybar-items.5.scd @@ -223,7 +223,7 @@ Note: | highlight_color : : 0xff000000 -: Highlight color of the text (e.g. for active space icon +: Highlight color of the text (e.g. for active space icon) | padding_left : : 0 diff --git a/docs/sketchybar-tips.5.scd b/docs/sketchybar-tips.5.scd index d969be52..85ea003e 100644 --- a/docs/sketchybar-tips.5.scd +++ b/docs/sketchybar-tips.5.scd @@ -68,7 +68,7 @@ sketchybar --bar "${bar[@]}" If you are experiencing problems with the configuration process, it might be helpful to work through the following steps: -. Start sketchybar directly from the commandline to see the verbose error or, +. Start sketchybar directly from the command line to see the verbose error or warning messages. . Make sure you have no trailing whitespaces after the newline escape character *\\*. @@ -76,7 +76,7 @@ helpful to work through the following steps: . Reduce the configuration to a minimal example and narrow down the problematic region. . Try running erroneous scripts directly in the command line. -. Query sketchybar for relevant properties and use them to deduce the, +. Query sketchybar for relevant properties and use them to deduce the problems root cause. . Create and file an issue at https://github.com/FelixKratz/SketchyBar/issues. A second pair of eyes might now be the only thing that helps. @@ -127,8 +127,8 @@ The config path for this additional bar is in _$HOME/.config/bottom_bar/_. Of course *bottom_bar* is only an example and can be freely replaced with any other identifier. -You can bootstrap the additional bar by invoking it at the very bottom of your -main bar's sketchybarrc. +You can bootstrap the additional bar by invoking it at the very end of your +main bar's configuration file. ## Performance optimizations diff --git a/docs/sketchybar.1.scd b/docs/sketchybar.1.scd index 9fe308d4..b8c47d91 100644 --- a/docs/sketchybar.1.scd +++ b/docs/sketchybar.1.scd @@ -110,13 +110,13 @@ A sketchybar configuration file is a regular shell script file that resides at _$HOME/.config/sketchybar/sketchybarrc_. It is executed when sketchybar launches. Everything persistent should be set up in this file. -It is possible to play with properties in the commandline and change them on the -fly while the bar is running. Once a fitting value is found, the configuration -can then be included in the configuration file. The configuration is then -restored on restart. +It is possible to play with properties in the command line and change them +on the fly while the bar is running. Once a fitting value is found, the +configuration can then be included in the configuration file. The configuration +is then restored on restart. When configuring the bar, it can be helpful to *stop the brew service* and *run -sketchybar* from the commandline directly to see all relevant error messages +sketchybar* from the command line directly to see all relevant error messages and warnings directly. Refer to @@ -168,7 +168,7 @@ If sketchybar is run from the command line directly with the command *sketchybar*, all outputs and error messages from scripts will be printed in stdout. -The default plugin folder is located in _$HOME/.config/sketchybar/plugins_. +The default plugin folder is located at _$HOME/.config/sketchybar/plugins_. Plugins need to be referenced with absolute paths because relative paths will not be resolved correctly. diff --git a/docs/sketchybar.5.scd b/docs/sketchybar.5.scd index b9e98903..c46aeda6 100644 --- a/docs/sketchybar.5.scd +++ b/docs/sketchybar.5.scd @@ -23,7 +23,7 @@ The possible settings to configure the bar include | border_color : : 0xffff0000 -: Color of the bars border +: Color of the bar's border | position : top, bottom : top @@ -47,7 +47,7 @@ The possible settings to configure the bar include | border_width : : 0 -: Border width of the bars border +: Border width of the bar's border | blur_radius : : 0 @@ -83,7 +83,7 @@ The possible settings to configure the bar include | sticky : : off -: Makes the bar sticky (only use with disabled space change animations [See issue #220] +: Makes the bar sticky (only use with disabled space change animations) | font_smoothing : : off @@ -93,6 +93,10 @@ The possible settings to configure the bar include : off : If the bar should draw a shadow + +For details about *sticky*, see +https://github.com/FelixKratz/SketchyBar/issues/220 + # EXAMPLES ``` From 34d115faa59d0318c4f263c3e8514077365f2075 Mon Sep 17 00:00:00 2001 From: Felix Kratz Date: Sun, 15 Oct 2023 10:51:26 +0200 Subject: [PATCH 4/4] move man docs to man dir --- {docs => man}/sketchybar-animate.5.scd | 0 {docs => man}/sketchybar-components.5.scd | 0 {docs => man}/sketchybar-events.5.scd | 0 {docs => man}/sketchybar-items.5.scd | 0 {docs => man}/sketchybar-popup.5.scd | 0 {docs => man}/sketchybar-query.5.scd | 0 {docs => man}/sketchybar-tips.5.scd | 0 {docs => man}/sketchybar-types.5.scd | 0 {docs => man}/sketchybar.1.scd | 0 {docs => man}/sketchybar.5.scd | 0 10 files changed, 0 insertions(+), 0 deletions(-) rename {docs => man}/sketchybar-animate.5.scd (100%) rename {docs => man}/sketchybar-components.5.scd (100%) rename {docs => man}/sketchybar-events.5.scd (100%) rename {docs => man}/sketchybar-items.5.scd (100%) rename {docs => man}/sketchybar-popup.5.scd (100%) rename {docs => man}/sketchybar-query.5.scd (100%) rename {docs => man}/sketchybar-tips.5.scd (100%) rename {docs => man}/sketchybar-types.5.scd (100%) rename {docs => man}/sketchybar.1.scd (100%) rename {docs => man}/sketchybar.5.scd (100%) diff --git a/docs/sketchybar-animate.5.scd b/man/sketchybar-animate.5.scd similarity index 100% rename from docs/sketchybar-animate.5.scd rename to man/sketchybar-animate.5.scd diff --git a/docs/sketchybar-components.5.scd b/man/sketchybar-components.5.scd similarity index 100% rename from docs/sketchybar-components.5.scd rename to man/sketchybar-components.5.scd diff --git a/docs/sketchybar-events.5.scd b/man/sketchybar-events.5.scd similarity index 100% rename from docs/sketchybar-events.5.scd rename to man/sketchybar-events.5.scd diff --git a/docs/sketchybar-items.5.scd b/man/sketchybar-items.5.scd similarity index 100% rename from docs/sketchybar-items.5.scd rename to man/sketchybar-items.5.scd diff --git a/docs/sketchybar-popup.5.scd b/man/sketchybar-popup.5.scd similarity index 100% rename from docs/sketchybar-popup.5.scd rename to man/sketchybar-popup.5.scd diff --git a/docs/sketchybar-query.5.scd b/man/sketchybar-query.5.scd similarity index 100% rename from docs/sketchybar-query.5.scd rename to man/sketchybar-query.5.scd diff --git a/docs/sketchybar-tips.5.scd b/man/sketchybar-tips.5.scd similarity index 100% rename from docs/sketchybar-tips.5.scd rename to man/sketchybar-tips.5.scd diff --git a/docs/sketchybar-types.5.scd b/man/sketchybar-types.5.scd similarity index 100% rename from docs/sketchybar-types.5.scd rename to man/sketchybar-types.5.scd diff --git a/docs/sketchybar.1.scd b/man/sketchybar.1.scd similarity index 100% rename from docs/sketchybar.1.scd rename to man/sketchybar.1.scd diff --git a/docs/sketchybar.5.scd b/man/sketchybar.5.scd similarity index 100% rename from docs/sketchybar.5.scd rename to man/sketchybar.5.scd