@@ 3,6 3,18 @@
`statusbar` is a library and a program for easy generation of swaybar/i3bar
content.
+## Project Goals
+
+The project goals are:
+
+1. To offer a variety of widgets that meet the needs of most users.
+2. To make it easy to extend the collection of widgets, either by using an
+ external program or the project's library.
+3. To ensure that configuring widgets, including those built by other users,
+ is simple. All configuration options supported by the swaybar protocol
+ should be supported by this project.
+4. To deliver comprehensive documentation.
+
## statusbar - The Program
### Installation
@@ 64,69 76,112 @@ bar {
}
```
-## Available Widgets
+### Default Configuration
+
+In the above example, the first section of the configuration file refers to
+the DefaultConfig widget. Despite its somewhat misleading name, it does not
+describe an actual widget. Instead, all the configuration options provided in
+this section are used to initialize other widgets, unless their configuration
+overwrites them. The settings that can be used to describe the default
+configuration are listed and explained in the next section below. In the
+example, no options were provided, so the section could have been omitted.
+
+### Common options
+
+Options described in this section can be set for every widget, as well
+as in the special widget DefaultConfig (described above). This options are
+also described in the [swaybar-protocol(7)](https://man.archlinux.org/man/swaybar-protocol.7).
+
+- `color` - Sets the text color of the widget using #rrggbbaa or #rrggbb
+ notation.
+
+- `background` - Sets the background color of the widget.
-Currently, the statusbar provides three widgets, and more will be added soon.
+- `border` - Sets the border color for the widget.
-### DefaultConfig
+- `borderTop` - Sets the height in pixels of the top border. The default value
+ is 1.
-The DefaultConfig is not a real widget. Instead, all the configuration options
-given in this section of the config file are used to initialize widgets.
-In the example above, no options were given, but you users can use each option
-described in the "Common options" section below.
+- `borderBottom` - Sets the height in pixels of the bottom border. The default
+ value is 1.
+
+- `borderLeft` - Sets the width in pixels of the left border. The default
+ value is 1.
+
+- `borderRight` - Sets the width in pixels of the right border. The default
+ value is 1.
+
+- `minWidth` - Sets the minimum width to use for the widget. The width can be
+ specified in pixels or as a string to allow for dynamic calculation based on
+ the width of the text.
+
+- `separator` - Specifies whether the bar separator should be drawn after the
+ widget. Refer to [sway-bar(5)](https://man.archlinux.org/man/sway-bar.5) for
+ more information on how to set the separator text.
+
+- `separatorBlockWidth` - Sets the amount of pixels to leave blank after the
+ block. The separator text will be displayed centered in this gap. The
+ default value is 9 pixels.
+
+- `align` - Specifies how the text should be aligned inside the block if it
+ does not span the full width. The options are left (default), right, or
+ center.
+
+## Available Widgets
+
+Currently, the statusbar provides following widgets.
### BatteryMonitor
The BatteryMonitor widget is used to display the status and level of the
-system battery. Users have the option to customize its appearance using the
-following settings:
-
-- `format`: This setting determines the format in which the battery status is
- shown. The default format is `{icon} {level}`. Users can include `{status}`
- in the format to display the battery status. By default, the statuses are
- displayed as "Full," "Not charging," "Charging," "Discharging," and
- "Unknown." However, users can specify their preferred labels for each status
- using the options `statusFull`, `statusNotCharging`, `statusCharging`, and
- `statusDischarging`. The placeholder for the battery level can also include
- a formatting verb, as defined in the [Golang's fmt package
+system battery. It offers the following options for customization:
+
+- `format`: This option determines how the battery status is displayed. The
+ default format is `{icon} {level}`. It can also include a `{status}`
+ indicator that shows text describing the battery status. By default, the
+ statuses are displayed as "Full," "Not charging," "Charging," "Discharging,"
+ and "Unknown." However, these labels can be changed using the `statusFull`,
+ `statusNotCharging`, `statusCharging`, and `statusDischarging` options
+ described below. The `{level}` placeholder can also include a formatting
+ verb, as defined in the [Golang's fmt package
documentation](https://pkg.go.dev/fmt#hdr-Printing). For example, you can
- use {level:%2d} to format the level as a two-digit integer.
+ use {level:%2d} to format the level with at least two-digit (the
+ default formatting is `%d`).
-- `statusIcons`: This option allows to specify four icons (ie. Unicode points)
- that correspond to the "Full", "Not charging", "Charging", and "Discharging"
- statuses. The default icons are `FNCD`.
+- `statusIcons`: Specifies four icons (Unicode points) that correspond to the
+ "Full," "Not charging," "Charging," and "Discharging" statuses. These icons
+ are used in place of the `{icon}` placeholder. The default icons are `FNCD`.
-- `chargingIcons`: This setting allows users to specify icons that are
- displayed instead of the `C` icon defined using the `statusIcons` option.
- Users can provide as many icons as they like. These icons should represent
+- `chargingIcons`: If provided, these icons are displayed instead of the `C`
+ icon defined using the `statusIcons` option. The icons should represent
different battery levels, starting with the icon that represents the lowest
- level.
+ level. There is no limit to the number of icons that can be used.
-- `dischargingIcons`: This setting allows users to specify icons that are
- displayed instead of the `D` icon defined using the `statusIcons` option.
+- `dischargingIcons`: Similar to the `chargingIcons` above. Specifies icons
+ that are displayed instead of the `D` icon defined using the `statusIcons`
+ option.
- `statusFull`, `statusNotCharging`, `statusCharging`, `statusDischarging`:
These options allows to specify labels for the "Full", "Not charging",
"Charging", and "Discharging" statuses.
-- `colors`: This setting allows users to specify the colors in which the
- widget is rendered, depending on the battery levels. For example, if this
- option is set to `#9e1828,10,#968a38,20,#ccc`, the widget will appear red
- when the level is below or equal to 10, yellow if the level is between 10
- and 20 (inclusive), and light gray otherwise.
+- `colors`: This option specifies the colors in which the widget will be
+ rendered based on the battery levels. For instance, if you set this option
+ to `#9e1828,10,#968a38,20,#ccc`, the widget will appear red when the battery
+ level is below or equal to 10, yellow when the level is between 10 and 20
+ (inclusive), and light gray otherwise.
- `criticalLevel`: If this option is set above 0, the user will receive an
urgent notification when the battery level falls below the provided value.
Notifications are sent using D-bus.
-- `notificationTitle`: This option allows users to customize the title of the
- notification sent when the battery level reaches a critically low level. The
- default title is: "Critical Battery Level"
+- `notificationTitle`: Provides the title of the notification sent when the
+ battery level reaches a critically low level. The default title is:
+ "Critical Battery Level"
-- `notificationBody`: This setting allows users to customize notifications
- body. The default message is: "Your battery level is critically low.\nPlease
- connect your device to a power source immediately to avoid any unexpected
- shutdowns."
+- `notificationBody`: Specifies the notification body. The default message is:
+ "Your battery level is critically low.\nPlease connect your device to
+ a power source immediately to avoid any unexpected shutdowns."
- `notificationIcon`: This option allows to set notification icon.
@@ 167,7 222,7 @@ necessary, and will display two digits for the fractional part. Please note
that the width and precision specification should be followed by the 'f'
suffix, but no '%' prefix should be included.
-## TemperatureMonitor
+### TemperatureMonitor
The TemperatureMonitor widget displays temperature and/or fan speed. It offers
the following settings:
@@ 231,43 286,20 @@ following options:
This option allows you to specify a list of application IDs that will not be
appended.
-### Common options
-
-Options described in this section can be set for every widget, as well
-as in the special widget DefaultConfig (described above). This options are
-also described in the [swaybar-protocol(7)](https://man.archlinux.org/man/swaybar-protocol.7).
+## statusbar - The Library
-- `color` - Sets the text color of the widget using #rrggbbaa or #rrggbb
- notation.
-- `background` - Sets the background color of the widget.
-- `border` - Sets the border color for the widget.
-- `borderTop` - Sets the height in pixels of the top border. The default value
- is 1.
-- `borderBottom` - Sets the height in pixels of the bottom border. The default
- value is 1.
-- `borderLeft` - Sets the width in pixels of the left border. The default
- value is 1.
-- `borderRight` - Sets the width in pixels of the right border. The default
- value is 1.
-- `minWidth` - Sets the minimum width to use for the widget. The width can be
- specified in pixels or as a string to allow for dynamic calculation based on
- the width of the text.
-- `separator` - Specifies whether the bar separator should be drawn after the
- widget. Refer to [sway-bar(5)](https://man.archlinux.org/man/sway-bar.5) for
- more information on how to set the separator text.
-- `separatorBlockWidth` - Sets the amount of pixels to leave blank after the
- block. The separator text will be displayed centered in this gap. The
- default value is 9 pixels.
-- `align` - Specifies how the text should be aligned inside the block if it
- does not span the full width. The options are left (default), right, or
- center.
+If a widget is missing from the above collection, you have two options
+to add it:
-## statusbar - The Library
+1. If there is already a program that provides the required functionality, you
+ can utilize the ExternalProgram widget.
+2. Alternatively, you can implement the missing widget using the statusbar
+ library.
-If there is a widget that you believe is missing from the project, you can
-easily implement it yourself. To illustrate this, let's build an application
-that, in addition to all the standard widgets, provides a StaticText widget
-that displays static text taken from the configuration file.
+The following example illustrates how to implement a program that adds a new
+widget called StaticText to the standard collection. This widget displays
+a text provided in the standard configuration files and supports all the
+common configuration options.
```go
package main
@@ 349,9 381,6 @@ forget to update the swaybar configuration (as described in the
## Contributions
-I am currently working on developing additional widgets to include in
-the standard distribution of the program. If you have any ideas for new
-widgets, it would be wise to discuss them first to avoid duplicating work.
If you notice any bugs or have any suggestions, feel free to contact me.
I welcome patches.