From c7743b28c68919e5bb1d8b9c53d63fb53fd3b081 Mon Sep 17 00:00:00 2001 From: Jake Stanger Date: Sun, 19 May 2024 15:16:01 +0100 Subject: [PATCH] docs: add rustdoc comments to all module options This part of an upcoming effort to generate documentation from code. Pushing this out before that stage so that the JSON schema is fully documented. --- src/config/common.rs | 135 +++++++++++++++++++++++++++++++- src/config/mod.rs | 138 ++++++++++++++++++++++++++++----- src/config/truncate.rs | 55 +++++++++++++ src/modules/cairo.rs | 17 ++++ src/modules/clipboard.rs | 16 ++++ src/modules/clock.rs | 28 ++++++- src/modules/custom/box.rs | 17 ++++ src/modules/custom/button.rs | 32 +++++++- src/modules/custom/image.rs | 18 +++++ src/modules/custom/label.rs | 21 ++++- src/modules/custom/mod.rs | 22 +++++- src/modules/custom/progress.rs | 35 +++++++++ src/modules/custom/slider.rs | 49 ++++++++++++ src/modules/focused.rs | 11 +++ src/modules/label.rs | 5 ++ src/modules/launcher/mod.rs | 18 +++++ src/modules/music/config.rs | 71 +++++++++++++---- src/modules/notifications.rs | 32 ++++++++ src/modules/script.rs | 17 +++- src/modules/sysinfo.rs | 47 ++++++++++- src/modules/tray/mod.rs | 13 ++++ src/modules/upower.rs | 8 ++ src/modules/volume.rs | 27 +++++++ src/modules/workspaces.rs | 49 +++++++++++- 24 files changed, 833 insertions(+), 48 deletions(-) diff --git a/src/config/common.rs b/src/config/common.rs index 25a8944..d1446e2 100644 --- a/src/config/common.rs +++ b/src/config/common.rs @@ -7,26 +7,153 @@ use gtk::{EventBox, Orientation, Revealer, RevealerTransitionType}; use serde::Deserialize; use tracing::trace; -/// Common configuration options -/// which can be set on every module. +/// The following are module-level options which are present on **all** modules. +/// +/// Each module also provides options specific to its type. +/// For details on those, check the relevant module documentation. +/// +/// For information on the Script type, and embedding scripts in strings, +/// see [here](script). +/// For information on styling, please see the [styling guide](styling-guide). #[derive(Debug, Default, Deserialize, Clone)] pub struct CommonConfig { - pub class: Option, + /// Sets the unique widget name, + /// allowing you to target it in CSS using `#name`. + /// + /// It is best practise (although not required) to ensure that the value is + /// globally unique throughout the Ironbar instance + /// to avoid clashes. + /// + /// **Default**: `null` pub name: Option, + /// Sets one or more CSS classes, + /// allowing you to target it in CSS using `.class`. + /// + /// Unlike [name](#name), the `class` property is not expected to be unique. + /// + /// **Default**: `null` + pub class: Option, + + /// Shows this text on hover. + /// Supports embedding scripts between `{{double braces}}`. + /// + /// Note that full dynamic string support is not currently supported. + /// + /// **Default**: `null` + pub tooltip: Option, + + /// Shows the module only if the dynamic boolean evaluates to true. + /// + /// This allows for modules to be dynamically shown or hidden + /// based on custom events. + /// + /// **Default**: `null` pub show_if: Option, + + /// The transition animation to use when showing/hiding the widget. + /// + /// Note this has no effect if `show_if` is not configured. + /// + /// **Valid options**: `slide_start`, `slide_end`, `crossfade`, `none` + ///
+ /// **Default**: `slide_start` pub transition_type: Option, + + /// The length in milliseconds + /// of the transition animation to use when showing/hiding the widget. + /// + /// Note this has no effect if `show_if` is not configured. + /// + /// **Default**: `250` pub transition_duration: Option, + /// A [script](scripts) to run when the module is left-clicked. + /// + /// **Supported script types**: `oneshot`. + ///
+ /// **Default**: `null` + /// + /// # Example + /// + /// ```corn + /// { on_click_left = "echo 'event' >> log.txt" } + /// ``` pub on_click_left: Option, + + /// A [script](scripts) to run when the module is right-clicked. + /// + /// **Supported script types**: `oneshot`. + ///
+ /// **Default**: `null` + /// /// # Example + /// + /// ```corn + /// { on_click_right = "echo 'event' >> log.txt" } + /// ``` pub on_click_right: Option, + + /// A [script](scripts) to run when the module is middle-clicked. + /// + /// **Supported script types**: `oneshot`. + ///
+ /// **Default**: `null` + /// # Example + /// + /// ```corn + /// { on_click_middle = "echo 'event' >> log.txt" } + /// ``` pub on_click_middle: Option, + + /// A [script](scripts) to run when the module is scrolled up on. + /// + /// **Supported script types**: `oneshot`. + ///
+ /// **Default**: `null` + /// # Example + /// + /// ```corn + /// { on_scroll_up = "echo 'event' >> log.txt" } + /// ``` pub on_scroll_up: Option, + + /// A [script](scripts) to run when the module is scrolled down on. + /// + /// **Supported script types**: `oneshot`. + ///
+ /// **Default**: `null` + /// # Example + /// + /// ```corn + /// { on_scroll_down = "echo 'event' >> log.txt" } + /// ``` pub on_scroll_down: Option, + + /// A [script](scripts) to run when the cursor begins hovering over the module. + /// + /// **Supported script types**: `oneshot`. + ///
+ /// **Default**: `null` + /// # Example + /// + /// ```corn + /// { on_mouse_enter = "echo 'event' >> log.txt" } + /// ``` pub on_mouse_enter: Option, + + /// A [script](scripts) to run when the cursor stops hovering over the module. + /// + /// **Supported script types**: `oneshot`. + ///
+ /// **Default**: `null` + /// # Example + /// + /// ```corn + /// { on_mouse_exit = "echo 'event' >> log.txt" } + /// ``` pub on_mouse_exit: Option, - pub tooltip: Option, + /// Prevents the popup from opening on-click for this widget. #[serde(default)] pub disable_popup: bool, } diff --git a/src/config/mod.rs b/src/config/mod.rs index 44ee8db..e906a40 100644 --- a/src/config/mod.rs +++ b/src/config/mod.rs @@ -116,12 +116,6 @@ impl ModuleConfig { } } -#[derive(Debug, Deserialize, Clone)] -pub enum BarEntryConfig { - Single(BarConfig), - Monitors(HashMap), -} - #[derive(Debug, Clone)] pub enum MonitorConfig { Single(BarConfig), @@ -155,32 +149,107 @@ pub struct MarginConfig { pub top: i32, } +/// The following is a list of all top-level bar config options. +/// +/// These options can either be written at the very top object of your config, +/// or within an object in the [monitors](#monitors) config, +/// depending on your [use-case](#2-pick-your-use-case). +/// #[derive(Debug, Deserialize, Clone)] pub struct BarConfig { - #[serde(default)] - pub position: BarPosition, - #[serde(default = "default_true")] - pub anchor_to_edges: bool, - #[serde(default = "default_bar_height")] - pub height: i32, - #[serde(default)] - pub margin: MarginConfig, + /// A unique identifier for the bar, used for controlling it over IPC. + /// If not set, uses a generated integer suffix. + /// + /// **Default**: `bar-n` pub name: Option, + /// The bar's position on screen. + /// + /// **Valid options**: `top`, `bottom`, `left`, `right` + ///
+ /// **Default**: `bottom` + #[serde(default)] + pub position: BarPosition, + + /// Whether to anchor the bar to the edges of the screen. + /// Setting to false centers the bar. + /// + /// **Default**: `true` + #[serde(default = "default_true")] + pub anchor_to_edges: bool, + + /// The bar's height in pixels. + /// + /// Note that GTK treats this as a target minimum, + /// and if content inside the bar is over this, + /// it will automatically expand to fit. + /// + /// **Default**: `42` + #[serde(default = "default_bar_height")] + pub height: i32, + + /// The margin to use on each side of the bar, in pixels. + /// Object which takes `top`, `bottom`, `left` and `right` keys. + /// + /// **Default**: `0` on all sides. + /// + /// # Example + /// + /// The following would set a 10px margin around each edge. + /// + /// ```corn + /// { + /// margin.top = 10 + /// margin.bottom = 10 + /// margin.left = 10 + /// margin.right = 10 + /// } + /// ``` + #[serde(default)] + pub margin: MarginConfig, + + /// The size of the gap in pixels + /// between the bar and the popup window. + /// + /// **Default**: `5` + #[serde(default = "default_popup_gap")] + pub popup_gap: i32, + + /// Whether the bar should be hidden when Ironbar starts. + /// + /// **Default**: `false`, unless `autohide` is set. #[serde(default)] pub start_hidden: Option, + + /// The duration in milliseconds before the bar is hidden after the cursor leaves. + /// Leave unset to disable auto-hide behaviour. + /// + /// **Default**: `null` #[serde(default)] pub autohide: Option, - /// GTK icon theme to use. + /// The name of the GTK icon theme to use. + /// Leave unset to use the default Adwaita theme. + /// + /// **Default**: `null` pub icon_theme: Option, + /// An array of modules to append to the start of the bar. + /// Depending on the orientation, this is either the top of the left edge. + /// + /// **Default**: `[]` pub start: Option>, - pub center: Option>, - pub end: Option>, - #[serde(default = "default_popup_gap")] - pub popup_gap: i32, + /// An array of modules to append to the center of the bar. + /// + /// **Default**: `[]` + pub center: Option>, + + /// An array of modules to append to the end of the bar. + /// Depending on the orientation, this is either the bottom or right edge. + /// + /// **Default**: `[]` + pub end: Option>, } impl Default for BarConfig { @@ -224,10 +293,41 @@ impl Default for BarConfig { #[derive(Debug, Deserialize, Clone, Default)] pub struct Config { + /// A map of [ironvar](ironvar) keys and values + /// to initialize Ironbar with on startup. + /// + /// **Default**: `{}` + /// + /// # Example + /// + /// The following initializes an ironvar called `foo` set to `bar` on startup: + /// + /// ```corn + /// { ironvar_defaults.foo = "bar" } + /// ``` + /// + /// The variable can then be immediately fetched without needing to be manually set: + /// + /// ```sh + /// $ ironbar get foo + /// ok + /// bar + /// ``` pub ironvar_defaults: Option, String>>, + /// The configuration for the bar. + /// Setting through this will enable a single identical bar on each monitor. #[serde(flatten)] pub bar: BarConfig, + + /// A map of monitor names to configs. + /// + /// The config values can be either: + /// + /// - a single object, which denotes a single bar for that monitor, + /// - an array of multiple objects, which denotes multiple for that monitor. + /// + /// Providing this option overrides the single, global `bar` option. pub monitors: Option>, } diff --git a/src/config/truncate.rs b/src/config/truncate.rs index fed4ffc..87451e4 100644 --- a/src/config/truncate.rs +++ b/src/config/truncate.rs @@ -20,13 +20,68 @@ impl From for GtkEllipsizeMode { } } +/// Some modules provide options for truncating text. +/// This is controlled using a common `TruncateMode` type, +/// which is defined below. +/// +/// The option can be configured in one of two modes. +/// #[derive(Debug, Deserialize, Clone, Copy)] #[serde(untagged)] pub enum TruncateMode { + /// Auto mode lets GTK decide when to ellipsize. + /// + /// To use this mode, set the truncate option to a string + /// declaring the location to truncate text from and place the ellipsis. + /// + /// # Example + /// + /// ```corn + /// { truncate = "start" } + /// ``` + /// + /// **Valid options**: `start`, `middle`, `end` + ///
+ /// **Default**: `null` Auto(EllipsizeMode), + + /// Length mode defines a fixed point at which to ellipsize. + /// + /// Generally you will want to set only one of `length` or `max_length`, + /// but you can set both if required. + /// + /// # Example + /// + /// ```corn + /// { + /// truncate.mode = "start" + /// truncate.length = 50 + /// truncate.max_length = 70 + /// } + /// ``` Length { + /// The location to truncate text from and place the ellipsis. + /// **Valid options**: `start`, `middle`, `end` + ///
+ /// **Default**: `null` mode: EllipsizeMode, + + /// The fixed width (in characters) of the widget. + /// + /// The widget will be expanded to this width + /// if it would have otherwise been smaller. + /// + /// Leave unset to let GTK automatically handle. + /// + /// **Default**: `null` length: Option, + + /// The maximum number of characters to show + /// before truncating. + /// + /// Leave unset to let GTK automatically handle. + /// + /// **Default**: `null` max_length: Option, }, } diff --git a/src/modules/cairo.rs b/src/modules/cairo.rs index 9e21aec..3ce42bb 100644 --- a/src/modules/cairo.rs +++ b/src/modules/cairo.rs @@ -19,16 +19,33 @@ use tracing::{debug, error}; #[derive(Debug, Clone, Deserialize)] pub struct CairoModule { + /// The path to the Lua script to load. + /// This can be absolute, or relative to the working directory. + /// + /// The script must contain the entry `draw` function. + /// + /// **Required** path: PathBuf, + /// The number of milliseconds between each draw call. + /// + /// **Default**: `200` #[serde(default = "default_frequency")] frequency: u64, + /// The canvas width in pixels. + /// + /// **Default**: `42` #[serde(default = "default_size")] width: u32, + + /// The canvas height in pixels. + /// + /// **Default**: `42` #[serde(default = "default_size")] height: u32, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/clipboard.rs b/src/modules/clipboard.rs index ae34a03..6365088 100644 --- a/src/modules/clipboard.rs +++ b/src/modules/clipboard.rs @@ -18,18 +18,34 @@ use tracing::{debug, error}; #[derive(Debug, Deserialize, Clone)] pub struct ClipboardModule { + /// The icon to show on the bar widget button. + /// Supports [image](images) icons. + /// + /// **Default**: `󰨸` #[serde(default = "default_icon")] icon: String, + /// The size to render the icon at. + /// Note this only applies to image-type icons. + /// + /// **Default**: `32` #[serde(default = "default_icon_size")] icon_size: i32, + /// The maximum number of items to keep in the history, + /// and to show in the popup. + /// + /// **Default**: `10` #[serde(default = "default_max_items")] max_items: usize, // -- Common -- + /// See [truncate options](module-level-options#truncate-mode). + /// + /// **Default**: `null` truncate: Option, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/clock.rs b/src/modules/clock.rs index 602c6e4..a5be924 100644 --- a/src/modules/clock.rs +++ b/src/modules/clock.rs @@ -17,23 +17,47 @@ use crate::{glib_recv, module_impl, send_async, spawn, try_send}; #[derive(Debug, Deserialize, Clone)] pub struct ClockModule { - /// Date/time format string. - /// Default: `%d/%m/%Y %H:%M` + /// The format string to use for the date/time shown on the bar. + /// Pango markup is supported. /// /// Detail on available tokens can be found here: /// + /// + /// **Default**: `%d/%m/%Y %H:%M` #[serde(default = "default_format")] format: String, + /// The format string to use for the date/time shown in the popup header. + /// Pango markup is supported. + /// + /// Detail on available tokens can be found here: + /// + /// + /// **Default**: `%H:%M:%S` #[serde(default = "default_popup_format")] format_popup: String, + /// The locale to use when formatting dates. + /// + /// Note this will not control the calendar - + /// for that you must set `LC_TIME`. + /// + /// **Valid options**: See [here](https://docs.rs/pure-rust-locales/0.8.1/pure_rust_locales/enum.Locale.html#variants) + ///
+ /// **Default**: `$LC_TIME` or `$LANG` or `'POSIX'` #[serde(default = "default_locale")] locale: String, + /// The orientation to display the widget contents. + /// Setting to vertical will rotate text 90 degrees. + /// + /// **Valid options**: `horizontal`, `vertical` + ///
+ /// **Default**: `horizontal` #[serde(default)] orientation: ModuleOrientation, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/custom/box.rs b/src/modules/custom/box.rs index dca848a..7e448f4 100644 --- a/src/modules/custom/box.rs +++ b/src/modules/custom/box.rs @@ -7,9 +7,26 @@ use serde::Deserialize; #[derive(Debug, Deserialize, Clone)] pub struct BoxWidget { + /// Widget name. + /// + /// **Default**: `null` name: Option, + + /// Widget class name. + /// + /// **Default**: `null` class: Option, + + /// Whether child widgets should be horizontally or vertically added. + /// + /// **Valid options**: `horizontal`, `vertical`, `h`, `v` + ///
+ /// **Default**: `horizontal` orientation: Option, + + /// Modules and widgets to add to this box. + /// + /// **Default**: `null` widgets: Option>, } diff --git a/src/modules/custom/button.rs b/src/modules/custom/button.rs index 199420d..9382da2 100644 --- a/src/modules/custom/button.rs +++ b/src/modules/custom/button.rs @@ -11,13 +11,43 @@ use super::{CustomWidget, CustomWidgetContext, ExecEvent, WidgetConfig}; #[derive(Debug, Deserialize, Clone)] pub struct ButtonWidget { + /// Widget name. + /// + /// **Default**: `null` name: Option, + + /// Widget class name. + /// + /// **Default**: `null` class: Option, + + /// Widget text label. Pango markup and embedded scripts are supported. + /// + /// This is a shorthand for adding a label widget to the button. + /// Ignored if `widgets` is set. + /// + /// This is a [Dynamic String](dynamic-values#dynamic-string). + /// + /// **Default**: `null` label: Option, + + /// Command to execute. More on this [below](#commands). + /// + /// **Default**: `null` on_click: Option, - widgets: Option>, + + /// Orientation of the button. + /// + /// **Valid options**: `horizontal`, `vertical`, `h`, `v` + ///
+ /// **Default**: `horizontal` #[serde(default)] orientation: ModuleOrientation, + + /// Modules and widgets to add to this box. + /// + /// **Default**: `null` + widgets: Option>, } impl CustomWidget for ButtonWidget { diff --git a/src/modules/custom/image.rs b/src/modules/custom/image.rs index e5d099d..fffac2d 100644 --- a/src/modules/custom/image.rs +++ b/src/modules/custom/image.rs @@ -10,9 +10,27 @@ use super::{CustomWidget, CustomWidgetContext}; #[derive(Debug, Deserialize, Clone)] pub struct ImageWidget { + /// Widget name. + /// + /// **Default**: `null` name: Option, + + /// Widget class name. + /// + /// **Default**: `null` class: Option, + + /// Image source. + /// + /// This is an [image](image) via [Dynamic String](dynamic-values#dynamic-string). + /// + /// **Required** src: String, + + /// The width/height of the image. + /// Aspect ratio is preserved. + /// + /// **Default**: `32` #[serde(default = "default_size")] size: i32, } diff --git a/src/modules/custom/label.rs b/src/modules/custom/label.rs index ca551c8..65f303b 100644 --- a/src/modules/custom/label.rs +++ b/src/modules/custom/label.rs @@ -10,9 +10,29 @@ use super::{CustomWidget, CustomWidgetContext}; #[derive(Debug, Deserialize, Clone)] pub struct LabelWidget { + /// Widget name. + /// + /// **Default**: `null` name: Option, + + /// Widget class name. + /// + /// **Default**: `null` class: Option, + + /// Widget text label. Pango markup and embedded scripts are supported. + /// + /// This is a [Dynamic String](dynamic-values#dynamic-string). + /// + /// **Required** label: String, + + /// Orientation of the label. + /// Setting to vertical will rotate text 90 degrees. + /// + /// **Valid options**: `horizontal`, `vertical`, `h`, `v` + ///
+ /// **Default**: `horizontal` #[serde(default)] orientation: ModuleOrientation, } @@ -24,7 +44,6 @@ impl CustomWidget for LabelWidget { let label = build!(self, Self::Widget); label.set_angle(self.orientation.to_angle()); - label.set_use_markup(true); { diff --git a/src/modules/custom/mod.rs b/src/modules/custom/mod.rs index dc54e83..5cffb00 100644 --- a/src/modules/custom/mod.rs +++ b/src/modules/custom/mod.rs @@ -29,19 +29,28 @@ use tracing::{debug, error}; #[derive(Debug, Deserialize, Clone)] pub struct CustomModule { - /// Widgets to add to the bar container + /// Modules and widgets to add to the bar container. + /// + /// **Default**: `[]` bar: Vec, - /// Widgets to add to the popup container + + /// Modules and widgets to add to the popup container. + /// + /// **Default**: `null` popup: Option>, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } #[derive(Debug, Deserialize, Clone)] pub struct WidgetConfig { + /// One of a custom module native Ironbar module. #[serde(flatten)] widget: WidgetOrModule, + + /// See [common options](module-level-options#common-options). #[serde(flatten)] common: CommonConfig, } @@ -49,18 +58,27 @@ pub struct WidgetConfig { #[derive(Debug, Deserialize, Clone)] #[serde(untagged)] pub enum WidgetOrModule { + /// A custom-module specific basic widget Widget(Widget), + /// A native Ironbar module, such as `clock` or `focused`. + /// All widgets are supported, including their popups. Module(ModuleConfig), } #[derive(Debug, Deserialize, Clone)] #[serde(tag = "type", rename_all = "snake_case")] pub enum Widget { + /// A container to place nested widgets inside. Box(BoxWidget), + /// A text label. Pango markup is supported. Label(LabelWidget), + /// A clickable button, which can run a command when clicked. Button(ButtonWidget), + /// An image or icon from disk or http. Image(ImageWidget), + /// A draggable slider. Slider(SliderWidget), + /// A progress bar. Progress(ProgressWidget), } diff --git a/src/modules/custom/progress.rs b/src/modules/custom/progress.rs index 16f46f8..199ea8c 100644 --- a/src/modules/custom/progress.rs +++ b/src/modules/custom/progress.rs @@ -14,14 +14,49 @@ use super::{CustomWidget, CustomWidgetContext}; #[derive(Debug, Deserialize, Clone)] pub struct ProgressWidget { + /// Widget name. + /// + /// **Default**: `null` name: Option, + + /// Widget class name. + /// + /// **Default**: `null` class: Option, + + /// Orientation of the progress bar. + /// + /// **Valid options**: `horizontal`, `vertical`, `h`, `v` + ///
+ /// **Default**: `horizontal` #[serde(default)] orientation: ModuleOrientation, + + /// Text label to show for the progress bar. + /// + /// This is a [Dynamic String](dynamic-values#dynamic-string). + /// + /// **Default**: `null` label: Option, + + /// Script to run to get the progress bar value. + /// Output must be a valid percentage. + /// + /// Note that this expects a numeric value between `0`-`max` as output. + /// + /// **Default**: `null` value: Option, + + /// The maximum progress bar value. + /// + /// **Default**: `100` #[serde(default = "default_max")] max: f64, + + /// The progress bar length, in pixels. + /// GTK will automatically determine the size if left blank. + /// + /// **Default**: `null` length: Option, } diff --git a/src/modules/custom/slider.rs b/src/modules/custom/slider.rs index 6bb3634..c533719 100644 --- a/src/modules/custom/slider.rs +++ b/src/modules/custom/slider.rs @@ -17,18 +17,67 @@ use super::{CustomWidget, CustomWidgetContext, ExecEvent}; #[derive(Debug, Deserialize, Clone)] pub struct SliderWidget { + /// Widget name. + /// + /// **Default**: `null` name: Option, + + /// Widget class name. + /// + /// **Default**: `null` class: Option, + + /// Orientation of the slider. + /// + /// **Valid options**: `horizontal`, `vertical`, `h`, `v` + ///
+ /// **Default**: `horizontal` #[serde(default)] orientation: ModuleOrientation, + + /// Script to run to get the slider value. + /// Output must be a valid number. + /// + /// **Default**: `null` value: Option, + + /// Command to execute when the slider changes. + /// More on this [below](#slider). + /// + /// Note that this will provide the floating point value as an argument. + /// If your input program requires an integer, you will need to round it. + /// + /// **Default**: `null` on_change: Option, + + /// Minimum slider value. + /// + /// **Default**: `0` #[serde(default = "default_min")] min: f64, + + /// Maximum slider value. + /// + /// **Default**: `100` #[serde(default = "default_max")] max: f64, + + /// If the increment to change when scrolling with the mousewheel. + /// If left blank, GTK will use the default value, + /// determined by the current environment. + /// + /// **Default**: `null` step: Option, + + /// The slider length. + /// GTK will automatically determine the size if left blank. + /// + /// **Default**: `null` length: Option, + + /// Whether to show the value label above the slider. + /// + /// **Default**: `true` #[serde(default = "crate::config::default_true")] show_label: bool, } diff --git a/src/modules/focused.rs b/src/modules/focused.rs index 6c21434..9fb43d2 100644 --- a/src/modules/focused.rs +++ b/src/modules/focused.rs @@ -14,18 +14,29 @@ use tracing::debug; #[derive(Debug, Deserialize, Clone)] pub struct FocusedModule { /// Whether to show icon on the bar. + /// + /// **Default**: `true` #[serde(default = "crate::config::default_true")] show_icon: bool, /// Whether to show app name on the bar. + /// + /// **Default**: `true` #[serde(default = "crate::config::default_true")] show_title: bool, /// Icon size in pixels. + /// + /// **Default**: `32` #[serde(default = "default_icon_size")] icon_size: i32, + // -- common -- + /// See [truncate options](module-level-options#truncate-mode). + /// + /// **Default**: `null` truncate: Option, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/label.rs b/src/modules/label.rs index dde6f46..2a8a20c 100644 --- a/src/modules/label.rs +++ b/src/modules/label.rs @@ -10,8 +10,13 @@ use tokio::sync::mpsc; #[derive(Debug, Deserialize, Clone)] pub struct LabelModule { + /// The text to show on the label. + /// This is a [Dynamic String](dynamic-values#dynamic-string). + /// + /// **Required** label: String, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/launcher/mod.rs b/src/modules/launcher/mod.rs index 03599b1..7d9a48a 100644 --- a/src/modules/launcher/mod.rs +++ b/src/modules/launcher/mod.rs @@ -22,20 +22,38 @@ use tracing::{debug, error, trace}; pub struct LauncherModule { /// List of app IDs (or classes) to always show regardless of open state, /// in the order specified. + /// + /// **Default**: `null` favorites: Option>, + /// Whether to show application names on the bar. + /// + /// **Default**: `false` #[serde(default = "crate::config::default_false")] show_names: bool, + /// Whether to show application icons on the bar. + /// + /// **Default**: `true` #[serde(default = "crate::config::default_true")] show_icons: bool, + /// Size in pixels to render icon at (image icons only). + /// + /// **Default**: `32` #[serde(default = "default_icon_size")] icon_size: i32, + /// Whether items should be added from right-to-left + /// instead of left-to-right. + /// + /// This includes favourites. + /// + /// **Default**: `false` #[serde(default = "crate::config::default_false")] reversed: bool, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/music/config.rs b/src/modules/music/config.rs index c772684..6d3de79 100644 --- a/src/modules/music/config.rs +++ b/src/modules/music/config.rs @@ -6,34 +6,50 @@ use std::path::PathBuf; #[derive(Debug, Deserialize, Clone)] pub struct Icons { /// Icon to display when playing. + /// + /// **Default**: `` #[serde(default = "default_icon_play")] pub(crate) play: String, /// Icon to display when paused. + /// + /// **Default**: `` #[serde(default = "default_icon_pause")] pub(crate) pause: String, /// Icon to display for previous button. + /// + /// **Default**: `󰒮` #[serde(default = "default_icon_prev")] pub(crate) prev: String, /// Icon to display for next button. + /// + /// **Default**: `󰒭` #[serde(default = "default_icon_next")] pub(crate) next: String, - /// Icon to display under volume slider + /// Icon to display under volume slider. + /// + /// **Default**: `󰕾` #[serde(default = "default_icon_volume")] pub(crate) volume: String, - /// Icon to display nex to track title + /// Icon to display nex to track title. + /// + /// **Default**: `󰎈` #[serde(default = "default_icon_track")] pub(crate) track: String, - /// Icon to display nex to album name + /// Icon to display nex to album name. + /// + /// **Default**: `󰀥` #[serde(default = "default_icon_album")] pub(crate) album: String, - /// Icon to display nex to artist name + /// Icon to display nex to artist name. + /// + /// **Default**: `󰠃` #[serde(default = "default_icon_artist")] pub(crate) artist: String, } @@ -73,33 +89,62 @@ pub struct MusicModule { pub(crate) player_type: PlayerType, /// Format of current song info to display on the bar. + /// + /// Info on formatting tokens [below](#formatting-tokens). + /// + /// **Default**: `{title} / {artist}` #[serde(default = "default_format")] pub(crate) format: String, - /// Player state icons + /// Player state icons. + /// + /// See [icons](#icons). #[serde(default)] pub(crate) icons: Icons, - // -- MPD -- - /// TCP or Unix socket address. - #[serde(default = "default_socket")] - pub(crate) host: String, - /// Path to root of music directory. - #[serde(default = "default_music_dir")] - pub(crate) music_dir: PathBuf, - + /// Whether to show the play/pause status icon + /// on the bar. + /// + /// **Default**: `true` #[serde(default = "crate::config::default_true")] pub(crate) show_status_icon: bool, + /// Size to render the icons at, in pixels (image icons only). + /// + /// **Default** `32` #[serde(default = "default_icon_size")] pub(crate) icon_size: i32, + /// Size to render the album art image at inside the popup, in pixels. + /// + /// **Default**: `128` #[serde(default = "default_cover_image_size")] pub(crate) cover_image_size: i32, + // -- MPD -- + /// *[MPD Only]* + /// TCP or Unix socket address of the MPD server. + /// For TCP, this should include the port number. + /// + /// **Default**: `localhost:6600` + #[serde(default = "default_socket")] + pub(crate) host: String, + + /// *[MPD Only]* + /// Path to root of the MPD server's music directory. + /// This is required for displaying album art. + /// + /// **Default**: `$HOME/Music` + #[serde(default = "default_music_dir")] + pub(crate) music_dir: PathBuf, + // -- Common -- + /// See [truncate options](module-level-options#truncate-mode). + /// + /// **Default**: `null` pub(crate) truncate: Option, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/notifications.rs b/src/modules/notifications.rs index 1a60ca1..18e5c2a 100644 --- a/src/modules/notifications.rs +++ b/src/modules/notifications.rs @@ -11,28 +11,60 @@ use tracing::error; #[derive(Debug, Deserialize, Clone)] pub struct NotificationsModule { + /// Whether to show the current notification count. + /// + /// **Default**: `true` #[serde(default = "crate::config::default_true")] show_count: bool, + /// SwayNC state icons. + /// + /// See [icons](#icons). #[serde(default)] icons: Icons, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } #[derive(Debug, Deserialize, Clone)] struct Icons { + /// Icon to show when the panel is closed, with no notifications. + /// + /// **Default**: `󰍥` #[serde(default = "default_icon_closed_none")] closed_none: String, + + /// Icon to show when the panel is closed, with notifications. + /// + /// **Default**: `󱥂` #[serde(default = "default_icon_closed_some")] closed_some: String, + + /// Icon to show when the panel is closed, with DnD enabled. + /// Takes higher priority than count-based icons. + /// + /// **Default**: `󱅯` #[serde(default = "default_icon_closed_dnd")] closed_dnd: String, + + /// Icon to show when the panel is open, with no notifications. + /// + /// **Default**: `󰍡` #[serde(default = "default_icon_open_none")] open_none: String, + + /// Icon to show when the panel is open, with notifications. + /// + /// **Default**: `󱥁` #[serde(default = "default_icon_open_some")] open_some: String, + + /// Icon to show when the panel is open, with DnD enabled. + /// Takes higher priority than count-based icons. + /// + /// **Default**: `󱅮` #[serde(default = "default_icon_open_dnd")] open_dnd: String, } diff --git a/src/modules/script.rs b/src/modules/script.rs index 0f83490..cd96142 100644 --- a/src/modules/script.rs +++ b/src/modules/script.rs @@ -12,14 +12,29 @@ use tracing::error; #[derive(Debug, Deserialize, Clone)] pub struct ScriptModule { /// Path to script to execute. + /// + /// This can be an absolute path, + /// or relative to the working directory. + /// + /// **Required** cmd: String, - /// Script execution mode + + /// Script execution mode. + /// See [modes](#modes) for more info. + /// + /// **Valid options**: `poll`, `watch` + ///
+ /// **Default**: `poll` #[serde(default = "default_mode")] mode: ScriptMode, + /// Time in milliseconds between executions. + /// + /// **Default**: `5000` #[serde(default = "default_interval")] interval: u64, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/sysinfo.rs b/src/modules/sysinfo.rs index 4b0966f..026cbf2 100644 --- a/src/modules/sysinfo.rs +++ b/src/modules/sysinfo.rs @@ -15,33 +15,76 @@ use tokio::time::sleep; #[derive(Debug, Deserialize, Clone)] pub struct SysInfoModule { - /// List of formatting strings. + /// List of strings including formatting tokens. + /// For available tokens, see [below](#formatting-tokens). + /// + /// **Required** format: Vec, - /// Number of seconds between refresh + + /// Number of seconds between refresh. + /// + /// This can be set as a global interval, + /// or passed as an object to customize the interval per-system. + /// + /// **Default**: `5` #[serde(default = "Interval::default")] interval: Interval, + /// The orientation of text for the labels. + /// + /// **Valid options**: `horizontal`, `vertical, `h`, `v` + ///
+ /// **Default** : `horizontal` #[serde(default)] orientation: ModuleOrientation, + /// The orientation by which the labels are laid out. + /// + /// **Valid options**: `horizontal`, `vertical, `h`, `v` + ///
+ /// **Default** : `horizontal` direction: Option, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } #[derive(Debug, Deserialize, Copy, Clone)] pub struct Intervals { + /// The number of seconds between refreshing memory data. + /// + /// **Default**: `5` #[serde(default = "default_interval")] memory: u64, + + /// The number of seconds between refreshing CPU data. + /// + /// **Default**: `5` #[serde(default = "default_interval")] cpu: u64, + + /// The number of seconds between refreshing temperature data. + /// + /// **Default**: `5` #[serde(default = "default_interval")] temps: u64, + + /// The number of seconds between refreshing disk data. + /// + /// **Default**: `5` #[serde(default = "default_interval")] disks: u64, + + /// The number of seconds between refreshing network data. + /// + /// **Default**: `5` #[serde(default = "default_interval")] networks: u64, + + /// The number of seconds between refreshing system data. + /// + /// **Default**: `5` #[serde(default = "default_interval")] system: u64, } diff --git a/src/modules/tray/mod.rs b/src/modules/tray/mod.rs index 3c43ec0..23c4bee 100644 --- a/src/modules/tray/mod.rs +++ b/src/modules/tray/mod.rs @@ -20,15 +20,28 @@ use tracing::{debug, error, warn}; #[derive(Debug, Deserialize, Clone)] pub struct TrayModule { + /// Requests that icons from the theme be used over the item-provided item. + /// Most items only provide one or the other so this will have no effect in most circumstances. + /// + /// **Default**: `true` #[serde(default = "crate::config::default_true")] prefer_theme_icons: bool, + /// Size in pixels to display the tray icons as. + /// + /// **Default**: `16` #[serde(default = "default_icon_size")] icon_size: u32, + /// Direction to display the tray items. + /// + /// **Valid options**: `top_to_bottom`, `bottom_to_top`, `left_to_right`, `right_to_left` + ///
+ /// **Default**: `left_to_right` if bar is horizontal, `top_to_bottom` if bar is vertical #[serde(default, deserialize_with = "deserialize_orientation")] direction: Option, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/upower.rs b/src/modules/upower.rs index f2b1939..34baf27 100644 --- a/src/modules/upower.rs +++ b/src/modules/upower.rs @@ -23,12 +23,20 @@ const MINUTE: i64 = 60; #[derive(Debug, Deserialize, Clone)] pub struct UpowerModule { + /// The format string to use for the widget button label. + /// For available tokens, see [below](#formatting-tokens). + /// + /// **Default**: `{percentage}%` #[serde(default = "default_format")] format: String, + /// The size to render the icon at, in pixels. + /// + /// **Default**: `24` #[serde(default = "default_icon_size")] icon_size: i32, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } diff --git a/src/modules/volume.rs b/src/modules/volume.rs index f11fa60..221d327 100644 --- a/src/modules/volume.rs +++ b/src/modules/volume.rs @@ -15,15 +15,27 @@ use tokio::sync::mpsc; #[derive(Debug, Clone, Deserialize)] pub struct VolumeModule { + /// The format string to use for the widget button label. + /// For available tokens, see [below](#formatting-tokens). + /// + /// **Default**: `{icon} {percentage}%` #[serde(default = "default_format")] format: String, + /// Maximum value to allow volume sliders to reach. + /// Pulse supports values > 100 but this may result in distortion. + /// + /// **Default**: `100` #[serde(default = "default_max_volume")] max_volume: f64, + /// Volume state icons. + /// + /// See [icons](#icons). #[serde(default)] icons: Icons, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, } @@ -34,12 +46,27 @@ fn default_format() -> String { #[derive(Debug, Clone, Deserialize)] pub struct Icons { + /// Icon to show for high volume levels. + /// + /// **Default**: `󰕾` #[serde(default = "default_icon_volume_high")] volume_high: String, + + /// Icon to show for medium volume levels. + /// + /// **Default**: `󰖀` #[serde(default = "default_icon_volume_medium")] volume_medium: String, + + /// Icon to show for low volume levels. + /// + /// **Default**: `󰕿` #[serde(default = "default_icon_volume_low")] volume_low: String, + + /// Icon to show for muted outputs. + /// + /// **Default**: `󰝟` #[serde(default = "default_icon_muted")] muted: String, } diff --git a/src/modules/workspaces.rs b/src/modules/workspaces.rs index b1a20de..91d0cd6 100644 --- a/src/modules/workspaces.rs +++ b/src/modules/workspaces.rs @@ -45,26 +45,69 @@ impl Default for Favorites { #[derive(Debug, Deserialize, Clone)] pub struct WorkspacesModule { /// Map of actual workspace names to custom names. + /// + /// Custom names can be [images](images). + /// + /// If a workspace is not present in the map, + /// it will fall back to using its actual name. name_map: Option>, - /// Array of always shown workspaces, and what monitor to show on + /// Workspaces which should always be shown. + /// This can either be an array of workspace names, + /// or a map of monitor names to arrays of workspace names. + /// + /// **Default**: `{}` + /// + /// # Example + /// + /// ```corn + /// // array format + /// { + /// type = "workspaces" + /// favorites = ["1", "2", "3"] + /// } + /// + /// // map format + /// { + /// type = "workspaces" + /// favorites.DP-1 = ["1", "2", "3"] + /// favorites.DP-2 = ["4", "5", "6"] + /// } + /// ``` #[serde(default)] favorites: Favorites, - /// List of workspace names to never show + /// A list of workspace names to never show. + /// + /// This may be useful for scratchpad/special workspaces, for example. + /// + /// **Default**: `[]` #[serde(default)] hidden: Vec, - /// Whether to display buttons for all monitors. + /// Whether to display workspaces from all monitors. + /// When false, only shows workspaces on the current monitor. + /// + /// **Default**: `false` #[serde(default = "crate::config::default_false")] all_monitors: bool, + /// The method used for sorting workspaces. + /// `added` always appends to the end, `alphanumeric` sorts by number/name. + /// + /// **Valid options**: `added`, `alphanumeric` + ///
+ /// **Default**: `alphanumeric` #[serde(default)] sort: SortOrder, + /// The size to render icons at (image icons only). + /// + /// **Default**: `32` #[serde(default = "default_icon_size")] icon_size: i32, + /// See [common options](module-level-options#common-options). #[serde(flatten)] pub common: Option, }