JakeStanger/ironbar
1
1
Fork 0
mirror of https://github.com/JakeStanger/ironbar.git synced 2024-08-16 01:40:39 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #597 from JakeStanger/docs/modules

Browse Source 
docs: add rustdoc comments to all module options
This commit is contained in:
Jake Stanger 2024-05-23 21:52:10 +01:00 committed by GitHub
commit 63ca68988f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
24 changed files with 833 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
src/config/common.rs
View File

@ -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<String>,
/// 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<String>,
/// 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<String>,
/// 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<String>,
/// 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<DynamicBool>,
/// 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`
/// <br>
/// **Default**: `slide_start`
pub transition_type: Option<TransitionType>,
/// 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<u32>,
/// A [script](scripts) to run when the module is left-clicked.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
///
/// # Example
///
/// ```corn
/// { on_click_left = "echo 'event' >> log.txt" }
/// ```
pub on_click_left: Option<ScriptInput>,
/// A [script](scripts) to run when the module is right-clicked.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// /// # Example
///
/// ```corn
/// { on_click_right = "echo 'event' >> log.txt" }
/// ```
pub on_click_right: Option<ScriptInput>,
/// A [script](scripts) to run when the module is middle-clicked.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_click_middle = "echo 'event' >> log.txt" }
/// ```
pub on_click_middle: Option<ScriptInput>,
/// A [script](scripts) to run when the module is scrolled up on.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_scroll_up = "echo 'event' >> log.txt" }
/// ```
pub on_scroll_up: Option<ScriptInput>,
/// A [script](scripts) to run when the module is scrolled down on.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_scroll_down = "echo 'event' >> log.txt" }
/// ```
pub on_scroll_down: Option<ScriptInput>,
/// A [script](scripts) to run when the cursor begins hovering over the module.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_mouse_enter = "echo 'event' >> log.txt" }
/// ```
pub on_mouse_enter: Option<ScriptInput>,
/// A [script](scripts) to run when the cursor stops hovering over the module.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_mouse_exit = "echo 'event' >> log.txt" }
/// ```
pub on_mouse_exit: Option<ScriptInput>,
pub tooltip: Option<String>,
/// Prevents the popup from opening on-click for this widget.
#[serde(default)]
pub disable_popup: bool,
}

138
src/config/mod.rs
View File

@ -116,12 +116,6 @@ impl ModuleConfig {
}
}
#[derive(Debug, Deserialize, Clone)]
pub enum BarEntryConfig {
Single(BarConfig),
Monitors(HashMap<String, MonitorConfig>),
}
#[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<String>,
/// The bar's position on screen.
///
/// **Valid options**: `top`, `bottom`, `left`, `right`
/// <br>
/// **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<bool>,
/// 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<u64>,
/// 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<String>,
/// 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<Vec<ModuleConfig>>,
pub center: Option<Vec<ModuleConfig>>,
pub end: Option<Vec<ModuleConfig>>,
#[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<Vec<ModuleConfig>>,
/// 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<Vec<ModuleConfig>>,
}
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<HashMap<Box<str>, 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<HashMap<String, MonitorConfig>>,
}

55
src/config/truncate.rs
View File

@ -20,13 +20,68 @@ impl From<EllipsizeMode> 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`
/// <br>
/// **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`
/// <br>
/// **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<i32>,
/// The maximum number of characters to show
/// before truncating.
///
/// Leave unset to let GTK automatically handle.
///
/// **Default**: `null`
max_length: Option<i32>,
},
}

17
src/modules/cairo.rs
View File

@ -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<CommonConfig>,
}

16
src/modules/clipboard.rs
View File

@ -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<TruncateMode>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

28
src/modules/clock.rs
View File

@ -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:
/// <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
///
/// **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:
/// <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
///
/// **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)
/// <br>
/// **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`
/// <br>
/// **Default**: `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

17
src/modules/custom/box.rs
View File

@ -7,9 +7,26 @@ use serde::Deserialize;
#[derive(Debug, Deserialize, Clone)]
pub struct BoxWidget {
/// Widget name.
///
/// **Default**: `null`
name: Option<String>,
/// Widget class name.
///
/// **Default**: `null`
class: Option<String>,
/// Whether child widgets should be horizontally or vertically added.
///
/// **Valid options**: `horizontal`, `vertical`, `h`, `v`
/// <br />
/// **Default**: `horizontal`
orientation: Option<ModuleOrientation>,
/// Modules and widgets to add to this box.
///
/// **Default**: `null`
widgets: Option<Vec<WidgetConfig>>,
}

32
src/modules/custom/button.rs
View File

@ -11,13 +11,43 @@ use super::{CustomWidget, CustomWidgetContext, ExecEvent, WidgetConfig};
#[derive(Debug, Deserialize, Clone)]
pub struct ButtonWidget {
/// Widget name.
///
/// **Default**: `null`
name: Option<String>,
/// Widget class name.
///
/// **Default**: `null`
class: Option<String>,
/// 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<String>,
/// Command to execute. More on this [below](#commands).
///
/// **Default**: `null`
on_click: Option<String>,
widgets: Option<Vec<WidgetConfig>>,
/// Orientation of the button.
///
/// **Valid options**: `horizontal`, `vertical`, `h`, `v`
/// <br />
/// **Default**: `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
/// Modules and widgets to add to this box.
///
/// **Default**: `null`
widgets: Option<Vec<WidgetConfig>>,
}
impl CustomWidget for ButtonWidget {

18
src/modules/custom/image.rs
View File

@ -10,9 +10,27 @@ use super::{CustomWidget, CustomWidgetContext};
#[derive(Debug, Deserialize, Clone)]
pub struct ImageWidget {
/// Widget name.
///
/// **Default**: `null`
name: Option<String>,
/// Widget class name.
///
/// **Default**: `null`
class: Option<String>,
/// 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,
}

21
src/modules/custom/label.rs
View File

@ -10,9 +10,29 @@ use super::{CustomWidget, CustomWidgetContext};
#[derive(Debug, Deserialize, Clone)]
pub struct LabelWidget {
/// Widget name.
///
/// **Default**: `null`
name: Option<String>,
/// Widget class name.
///
/// **Default**: `null`
class: Option<String>,
/// 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`
/// <br />
/// **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);
{

22
src/modules/custom/mod.rs
View File

@ -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<WidgetConfig>,
/// Widgets to add to the popup container
/// Modules and widgets to add to the popup container.
///
/// **Default**: `null`
popup: Option<Vec<WidgetConfig>>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}
#[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),
}

35
src/modules/custom/progress.rs
View File

@ -14,14 +14,49 @@ use super::{CustomWidget, CustomWidgetContext};
#[derive(Debug, Deserialize, Clone)]
pub struct ProgressWidget {
/// Widget name.
///
/// **Default**: `null`
name: Option<String>,
/// Widget class name.
///
/// **Default**: `null`
class: Option<String>,
/// Orientation of the progress bar.
///
/// **Valid options**: `horizontal`, `vertical`, `h`, `v`
/// <br />
/// **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<String>,
/// 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<ScriptInput>,
/// 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<i32>,
}

49
src/modules/custom/slider.rs
View File

@ -17,18 +17,67 @@ use super::{CustomWidget, CustomWidgetContext, ExecEvent};
#[derive(Debug, Deserialize, Clone)]
pub struct SliderWidget {
/// Widget name.
///
/// **Default**: `null`
name: Option<String>,
/// Widget class name.
///
/// **Default**: `null`
class: Option<String>,
/// Orientation of the slider.
///
/// **Valid options**: `horizontal`, `vertical`, `h`, `v`
/// <br />
/// **Default**: `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
/// Script to run to get the slider value.
/// Output must be a valid number.
///
/// **Default**: `null`
value: Option<ScriptInput>,
/// 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<String>,
/// 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<f64>,
/// The slider length.
/// GTK will automatically determine the size if left blank.
///
/// **Default**: `null`
length: Option<i32>,
/// Whether to show the value label above the slider.
///
/// **Default**: `true`
#[serde(default = "crate::config::default_true")]
show_label: bool,
}

11
src/modules/focused.rs
View File

@ -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<TruncateMode>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

5
src/modules/label.rs
View File

@ -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<CommonConfig>,
}

18
src/modules/launcher/mod.rs
View File

@ -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<Vec<String>>,
/// 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<CommonConfig>,
}

71
src/modules/music/config.rs
View File

@ -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<TruncateMode>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

32
src/modules/notifications.rs
View File

@ -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<CommonConfig>,
}
#[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,
}

17
src/modules/script.rs
View File

@ -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`
/// <br />
/// **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<CommonConfig>,
}

47
src/modules/sysinfo.rs
View File

@ -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<String>,
/// 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`
/// <br>
/// **Default** : `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
/// The orientation by which the labels are laid out.
///
/// **Valid options**: `horizontal`, `vertical, `h`, `v`
/// <br>
/// **Default** : `horizontal`
direction: Option<ModuleOrientation>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}
#[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,
}

13
src/modules/tray/mod.rs
View File

@ -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`
/// <br>
/// **Default**: `left_to_right` if bar is horizontal, `top_to_bottom` if bar is vertical
#[serde(default, deserialize_with = "deserialize_orientation")]
direction: Option<PackDirection>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

8
src/modules/upower.rs
View File

@ -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<CommonConfig>,
}

27
src/modules/volume.rs
View File

@ -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<CommonConfig>,
}
@ -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,
}

49
src/modules/workspaces.rs
View File

@ -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<HashMap<String, String>>,
/// 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<String>,
/// 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`
/// <br>
/// **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<CommonConfig>,
}