swiftbar/SwiftBar
1
1
Fork 0
mirror of https://github.com/swiftbar/SwiftBar.git synced 2024-09-11 16:05:33 +03:00
Code Issues Projects Releases Wiki Activity

Update README.md

Browse Source 
Minor markup tweaks and copy-edits for grammar, phrasing, and clarity.
This commit is contained in:
Zearin 2021-01-01 12:10:03 -05:00 committed by GitHub
parent 997edb5b0b
commit b48c707867
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 53 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
README.md
View File

@ -1,5 +1,5 @@
<p align="center"> <p align="center">
<img width="155" height="150" src="Resources/logo.png"> <img width="155" height="150" alt="SwiftBar Logo" src="Resources/logo.png">
</p> </p>
# SwiftBar # SwiftBar
@ -25,25 +25,25 @@ Runs on macOS Catalina (10.15) and up.
## ...or build it from source ## ...or build it from source
- Clone or download a copy of this repository - Clone or download a copy of this repository
- Open SwiftBar/SwiftBar.xcodeproj - Open `SwiftBar/SwiftBar.xcodeproj`
- Press play - Press play
## Plugin Repository ## Plugin Repository
SwiftBar bundled with Plugin Repository, you can access it at Swiftbar → Get Plugins... SwiftBar is bundled with a Plugin Repository. You can access it at Swiftbar → Get Plugins...
<p align="center"> <p align="center">
<img width="600" height="500" src="Resources/Plugin Repository.jpg"> <img width="600" height="500" alt="A screenshot of SwiftBar’s Plugin Repository" src="Resources/Plugin Repository.jpg">
</p> </p>
## Creating Plugins ## Creating Plugins
To add a new plugin to SwiftBar you need to create an executable script following the required format (see below) and put it into `Plugin Folder`. To add a new plugin to SwiftBar, you need to create an executable script following the required format (see below) and put it into `Plugin Folder`.
### Plugin Folder ### Plugin Folder
With the first launch, Swiftbar will ask you to set the `Plugin Folder`, SwiftBar will try to import every file in this folder as a plugin. With the first launch, Swiftbar will ask you to set the `Plugin Folder`. SwiftBar will try to import every file in this folder as a plugin.
**Important**: **Important**:
* hidden folders are ignored * hidden folders are ignored
@ -57,15 +57,15 @@ Plugin files must adopt the following format:
{name}.{time}.{ext} {name}.{time}.{ext}
``` ```
* name - anything you want * **name** - Anything you want.
* time - refresh interval, optional, should be a number + duration modifier (see below) * **time** - Refresh interval (optional). Should be a number + duration modifier (see below)
* ext - file extension * **ext** - File extension.
Duration modifier: Duration modifiers:
* s - seconds, i.e. 1s - refresh every second * **s** - seconds, e.g. 1s - refresh every second
* m - minute, i.e. 10m - refresh every ten minutes * **m** - minute, e.g. 10m - refresh every ten minutes
* h - hour, i.e. 3h - refresh every three hours * **h** - hour, e.g. 3h - refresh every three hours
* d - day, i.e. 1d - refresh every day * **d** - day, e.g. 1d - refresh every day
Example filename: `date.1m.sh` Example filename: `date.1m.sh`
@ -73,28 +73,28 @@ Example filename: `date.1m.sh`
Plugin is an executable script in the language of your choice. When SwiftBar detects a new file in `Plugin Folder` it makes this file executable if needed and runs it. Plugin is an executable script in the language of your choice. When SwiftBar detects a new file in `Plugin Folder` it makes this file executable if needed and runs it.
Script should produce output (STDOUT) in the required format (see next chapter), error should be redirected to STDERR. Script should produce output (`STDOUT`) in the required format (see next chapter). Script errors should be redirected to `STDERR`.
Plugin API is adopted from the [BitBar](https://github.com/matryer/bitbar), which means that SwiftBar can run any existing BitBar plugin. Plugin API is adopted from the [BitBar](https://github.com/matryer/bitbar), which means that SwiftBar can run any existing BitBar plugin.
### Script Output ### Script Output
When parsing plugin output SwiftBar recognizes the following blocks: When parsing plugin output SwiftBar recognizes the following blocks:
- Header - responsible for what you see in the menu bar - **Header**: responsible for what you see in the menu bar
- Body - responsible for dropdown menu contents - **Body**: responsible for dropdown menu contents
`Header` is everything before first `---`, each `---` after the first one will be interpreted as a menu separator. `Header` is everything before first `---`. Each `---` after the first one will be interpreted as a menu separator.
You have one or more lines in the header. You have one or more lines in the header.
The simplest plugin looks like this: The simplest plugin looks like this:
``` ```bash
echo "This is Menu Title" echo "This is Menu Title"
``` ```
If you provide multiple titles, the provided titles will be cycled in the menu bar and shown in the dropdown menu: If you provide multiple titles, the provided titles will be cycled in the menu bar and shown in the dropdown menu:
``` ```bash
echo "This is a primary Menu Title" echo "This is a primary Menu Title"
echo "This is a secondary Menu Title" echo "This is a secondary Menu Title"
echo "This is a n-th Menu Title" echo "This is a n-th Menu Title"
@ -102,49 +102,49 @@ echo "This is a n-th Menu Title"
echo "This is not a Menu Title, this will be showed in the drop-down menu only" echo "This is not a Menu Title, this will be showed in the drop-down menu only"
``` ```
Script output for both header and body is split by line(`\n`), each line must follow this format: Script output for both header and body is split by line (`\n`). Each line must follow this format:
``` ```
<Item Title> | [param = ...] <Item Title> | [param = ...]
``` ```
where: Where:
- "Item Title" can be any string, this will be used as a menu item title. - **"Item Title"** can be any string, this will be used as a menu item title.
- [param = ...] is an optional set of parameters\modificators, each parameter is a key-value separated by `=`. Use `|` to separate parameters from the title. - **[param = ...]** is an optional set of parameters\modificators. Each parameter is a key-value separated by `=`. Use `|` to separate parameters from the title.
Here is the list of supported parameters: Here is the list of supported parameters:
**Text Formatting**: **Text Formatting**:
| Parameter | Value | Description | | Parameter | Value | Description |
| ------------- | ------------- |------------- | | ------------- | ------------- |------------- |
| `color` | CSS color or HEX, `light_color,dark_color` |Sets item text color, if only one color provided it will be used for both light and dark appearance. | | `color` | CSS color or HEX, `light_color,dark_color` | Sets item text color. If only one color is provided, it is used for both light and dark appearance. |
| `sfcolor` | CSS color or HEX, `light_color,dark_color` |Sets SF Symbol color, if only one color provided it will be used for both light and dark appearance. | | `sfcolor` | CSS color or HEX, `light_color,dark_color` | Sets SF Symbol color. If only one color is provided, it is used for both light and dark appearance. |
| `font` | macOS font name| Sets font name to use in item text| | `font` | macOS font name | Sets font name to use in item text |
| `size` | Number| Sets item text size| | `size` | Number | Sets item text size |
| `length`| Number| Trims item text to a provided number of characters, the full title will be displayed in a tooltip | | `length`| Number | Trims item text to a provided number of characters. The full title will be displayed in a tooltip. |
| `trim` | True | Trims whitespace characters| | `trim` | True | Trims whitespace characters |
| `ansi` | True | Enables support of ANSI color codes. **Conflicts with** `symbolize` | | `ansi` | True | Enables support of ANSI color codes. **Conflicts with:** `symbolize` |
| `emojize` | False | Disables parsing of GitHub style emojis, i.e. `:mushroom:` into 🍄. **Requires** `symbolize=false` | | `emojize` | False | Disables parsing of GitHub style Emojis (e.g., `:mushroom:` into 🍄). **Requires:** `symbolize=false`. |
| `symbolize` | False | Disables parsing of [SF Symbols](https://developer.apple.com/sf-symbols/) i.e. "SF Symbols Test :sun.max: :cloud.fill: :gamecontroller.fill: :bookmark: :sun.dust:" <img width="218" alt="CleanShot 2020-12-13 at 14 40 33@2x" src="https://user-images.githubusercontent.com/222100/102021898-2d80e780-3d51-11eb-9e99-c71e92d14837.png"> Always `False` on Catalina| | `symbolize` | False | Disables parsing of [SF Symbols](https://developer.apple.com/sf-symbols/) (e.g., `"SF Symbols Test :sun.max: :cloud.fill: :gamecontroller.fill: :bookmark: :sun.dust:"` → <img width="218" alt="Screenshot of SF Symbols" src="https://user-images.githubusercontent.com/222100/102021898-2d80e780-3d51-11eb-9e99-c71e92d14837.png">). Always `False` on Catalina. |
**Visuals**: **Visuals**:
| Parameter | Value | Description | | Parameter | Value | Description |
| ------------- | ------------- |------------- | | ------------- | ------------- |------------- |
| `dropdown` | False | Applicable to items in `Header`, when set to False item will not be displayed in dropdown menu, but will be cycled in the menu bar| | `dropdown` | False | Only applicable to items in `Header`. When set to False, item will not be displayed in dropdown menu, but will be cycled in the menu bar. |
| `alternate` |True| Marks a line as an alternative to the previous one for when the Option key is pressed in the dropdown| | `alternate` | True | Marks a line as an alternative to the previous one for when the Option key (<kbd style="font-size:medium">⌥</kbd>) is pressed in the dropdown.|
| `image` | Image encoded in Base64| Sets an image for item| | `image` | Image encoded in Base64| Sets an image for item.|
| `templateImage`| Image encoded in Base64| Same as `image`, but the image is a template image. Template images consist of black and clear colors (and an alpha channel). Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance.| | `templateImage` | Image encoded in Base64| Same as `image`, but the image is a template image. Template images consist of black and clear colors (and an alpha channel). Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance.|
| `sfimage` | SFSymbol name| Sets an image for item from [SF Symbol](https://developer.apple.com/sf-symbols/). Only available on Big Sur and above.| | `sfimage` | SFSymbol name| Sets an image for item from [SF Symbol](https://developer.apple.com/sf-symbols/). Only available on Big Sur and above.|
| `checked` | True | Sets a checkmark in front of the item| | `checked` | True | Sets a checkmark in front of the item.|
| `tooltip` | Text | Sets a tooltip for the item | | `tooltip` | Text | Sets a tooltip for the item. |
**Actions**: **Actions**:
| Parameter | Value | Description | | Parameter | Value | Description |
| ------------- | ------------- |------------- | | ------------- | ------------- |------------- |
| `refresh` | True | Plugin Script will be executed on item click | | `refresh` | True | Plugin Script will be executed on item click |
| `href` | Absolute URL | Sets an URL to open when item clicked | | `href` | Absolute URL | Sets an URL to open when item clicked |
| `bash` | Absolute file path| Executable script to run in Shell | | `bash` | Absolute file path | Executable script to run in Shell |
| `terminal` | False | `bash` script will be run in the background, instead of launching the Terminal | | `terminal` | False | `bash` script will be run in the background, instead of launching the Terminal |
| `params` | `param0=`,`param1=`,`param10=`... | Parameters for `bash` script | | `params` | `param0=`,`param1=`,`param10=`... | Parameters for `bash` script |
| `shortcut` | CMD+OPT+T | Hotkey assigned to item, if item is in header hotkey will show the menu, otherwise hotkey will launch associated action| | `shortcut` | <kbd style="font-size:medium"><kbd style="font-size:medium">⌘</kbd>+<kbd style="font-size:medium">⌥</kbd>+<kbd style="font-size:medium">T</kbd></kbd> | Hotkey assigned to item. If item is in header, hotkey will show the menu; otherwise, hotkey will launch associated action. |
### Environment Variables ### Environment Variables
@ -156,14 +156,14 @@ When running a plugin, SwiftBar sets the following environment variables:
| `SWIFTBAR_BUILD` | The running SwiftBar build number (`CFBundleVersion`) | | `SWIFTBAR_BUILD` | The running SwiftBar build number (`CFBundleVersion`) |
| `SWIFTBAR_PLUGINS_PATH` | The path to the `Plugin Folder` | | `SWIFTBAR_PLUGINS_PATH` | The path to the `Plugin Folder` |
| `SWIFTBAR_PLUGIN_PATH` | The path to the running plugin | | `SWIFTBAR_PLUGIN_PATH` | The path to the running plugin |
| `OS_APPEARANCE` | Current macOS appearance, `Light` or `Dark` | | `OS_APPEARANCE` | Current macOS appearance (`Light` or `Dark`) |
| `OS_VERSION_MAJOR` | The first part of the macOS version, e.g. `11` for macOS 11.0.1 | | `OS_VERSION_MAJOR` | The first part of the macOS version (e.g., `11` for macOS 11.0.1). |
| `OS_VERSION_MINOR` | The second part of the macOS version, e.g. `0` for macOS 11.0.1 | | `OS_VERSION_MINOR` | The second part of the macOS version (e.g., `0` for macOS 11.0.1). |
| `OS_VERSION_PATCH` | The third part of the macOS version, e.g. `1` for macOS 11.0.1 | | `OS_VERSION_PATCH` | The third part of the macOS version (e.g., `1` for macOS 11.0.1). |
### Script Metadata ### Script Metadata
It is recommended to include metadata in plugin script, metadata is used in the About Plugin screen in SwiftBar. It is recommended to include metadata in plugin script. Metadata is used in the About Plugin screen in SwiftBar.
SwiftBar adopts metadata format suggested by BitBar: SwiftBar adopts metadata format suggested by BitBar:
``` ```
# <bitbar.title>Title goes here</bitbar.title> # <bitbar.title>Title goes here</bitbar.title>
@ -189,18 +189,18 @@ SwiftBar supports these optional metadata flags to hide default menu items:
# <swiftbar.hideSwiftBar>true</swiftbar.hideSwiftBar> # <swiftbar.hideSwiftBar>true</swiftbar.hideSwiftBar>
``` ```
Option+Click will show all items Option+Click will show all items:
![SwiftBar](https://user-images.githubusercontent.com/222100/101261866-267e2780-3708-11eb-9042-a57ad0ac6c78.gif) ![SwiftBar](https://user-images.githubusercontent.com/222100/101261866-267e2780-3708-11eb-9042-a57ad0ac6c78.gif)
## URL Scheme ## URL Scheme
| Endpoint | Parameter | Description | Example | | Endpoint | Parameter | Description | Example |
| ------------- | ------------- |------------- | ------------- | | ------------- | ------------- |------------- | ------------- |
|refreshallplugins|none|Force refresh all loaded plugins|swiftbar://refreshallplugins| | refreshallplugins | none | Force refresh all loaded plugins | `swiftbar://refreshallplugins` |
|refreshplugin|`name` plugin [name](#plugin-naming)|Force refresh plugin by name|swiftbar://refreshplugin?name=myplugin| | refreshplugin | `name` plugin [name](#plugin-naming) | Force refresh plugin by name | `swiftbar://refreshplugin?name=myplugin` |
|refreshplugin|`index` plugin index in menubar, starting from 0 |Force refresh plugin by its position in menubar|swiftbar://refreshplugin?index=1| | refreshplugin | `index` plugin index in menubar, starting from `0` | Force refresh plugin by its position in menubar | `swiftbar://refreshplugin?index=1` |
|addplugin|`src` source url to plugin file|Add plugin to Swiftbar from URL|swiftbar://addplugin?src=https://coolplugin| | addplugin | `src` source URL to plugin file | Add plugin to Swiftbar from URL | `swiftbar://addplugin?src=https://coolplugin` |
|notify|`plugin` plugin [name](#plugin-naming), notification fields `title`, `subtitile`, `body` and disable sound `silent=true` |Show notification|swiftbar://notify?plugin=MyPlugin&title=title&subtitle=subtitle&body=body&silent=true| | notify | `plugin` plugin [name](#plugin-naming), notification fields `title`, `subtitle`, `body` and disable sound `silent=true` | Show notification | `swiftbar://notify?plugin=MyPlugin&title=title&subtitle=subtitle&body=body&silent=true` |
@ -211,7 +211,7 @@ Use macOS `Console.app` to view SwiftBar logs.
## Acknowledgements ## Acknowledgements
SwiftBar uses these opensource libraries: SwiftBar uses these open source libraries:
* [HotKey](https://github.com/soffes/HotKey) * [HotKey](https://github.com/soffes/HotKey)
* [LaunchAtLogin](https://github.com/sindresorhus/LaunchAtLogin) * [LaunchAtLogin](https://github.com/sindresorhus/LaunchAtLogin)
* [Sparkle](https://github.com/sparkle-project/Sparkle) * [Sparkle](https://github.com/sparkle-project/Sparkle)