doc: Document the power menu and the clock widgets

Author: max-ishere

docs/CONFIG.md

@@ -0,0 +1,133 @@
+<!--
+SPDX-FileCopyrightText: 2024 max-ishere
+
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+# ReGreet configuration docs
+
+## Clock
+
+The clock widget can be customized to specify the 
+[time display format](https://docs.rs/jiff/0.1.14/jiff/fmt/strtime/index.html#conversion-specifications),
+how often to update the clock, overrides to the system timezone and a custom fixed label width so that the non-monospace
+font does not cause annoying width changes in the UI.
+
+```toml
+[widget.clock]
+# strftime format argument
+format = "%a %H:%M"
+
+# How often to update the text
+resolution = "500ms"
+
+# Override system timezone (IANA Time Zone Database name, aka /etc/zoneinfo path)
+# Remove to use the system time zone.
+timezone = "America/Chicago"
+
+# Ask GTK to make the label at least this wide. This helps keeps the parent element layout and width consistent.
+# Experiment with different widths, the interpretation of this value is entirely up to GTK.
+label_width = 150
+```
+
+## Power menu
+
+The first step in configuring the power menu is to select the backend to use. The backend is specified as part of the
+path under `widget.power-menu.<backend>`. Please note that only 1 backend can be active at a time.
+
+For your convenience, most backends allow you to specify an action that is automatically translated into the supported
+languages. The correct icon is also selected. Actions that will poweroff your system will ask for confirmation before
+they are executed. The actions are listed in the table below.
+
+| Config value    | Confirmation required |
+|-----------------|-----------------------|
+| poweroff        | Yes                   |
+| halt            | Yes                   |
+| reboot          | Yes                   |
+| reboot-firmware | Yes                   |
+| suspend         | No                    |
+| hibernate       | No                    |
+| hybrid-sleep    | No                    |
+
+The convention most backends' configs follow is having a single `actions` key, which is an array of actions. This simple
+structure allows you to easily add, remove, and reorder the buttons in the menu without having to verbosely specify all
+the attributes like you can do with the [custom](#custom) backend.
+
+### Systemd
+
+Machines using Systemd as the init system can specify the following line to use the default configuration.
+
+```toml
+[widget.power-menu.systemd]
+```
+
+The displayed actions can be changed using the `actions` key. [See above](#power-menu) for more details
+
+```toml
+[widget.power-menu.systemd]
+actions = ["suspend", "poweroff", "reboot-firmware"]
+```
+
+### Unix
+
+This backend should work on most systems as it does not use commands shipped with any specific init system. Instead, the
+Linux `shutdown` command is used.
+
+```toml
+[widget.power-menu.unix]
+```
+
+> [!NOTE]
+> The only actions supported by this backend are poweroff, reboot, and halt.
+>
+> When other values are specified they are logged as warnings and silently skipped.
+
+```toml
+[widget.power-menu.systemd]
+actions = ["poweroff", "reboot", "halt"]
+```
+
+### Custom
+
+The custom backend allows you to fully customize the power menu. If none of the other backends suit your needs or
+require additional customizations, consider using this backend.
+
+It is necesary to set the `backend` key to the backend that you are implementing. The backend string can have any value
+and is only used as part of the label in the power menu. The actions can be specified in the `commands` key.
+
+The power menu button (as well as `commands`) has the following fields:
+
+- `String` Label
+- `String` Icon (optional)
+- `bool` Should this entry be confirmed?
+- `Vec<String>` Command to execute
+
+The label, icon and confirmation can be inferred by ReGreet automatically if you set the `action` field.
+
+```toml
+[widget.power-menu.custom]
+backend = "Custom" # Required value
+
+[[widget.power-menu.custom.commands]]
+action = "poweroff"
+command = ["shutdown", "--now"]
+# `action` Infers:
+# label = "..." ## NOTE: label and action are mutually exclusive
+# icon = "..."
+# confirm = ...
+```
+
+Overrides (that are different from the action defaults) can be specified for the icon and the confirm, but not the
+label. The logic is that if you are specifying a custom label, you are likely also specifying a custom command that
+ReGreet does not know how to interpret into the inferable fields.
+
+The icon can be hidden altogether by setting it to an empty string.
+
+```toml
+[[widget.power-menu.custom.commands]]
+action = "poweroff"
+command = ["shutdown", "--now"]
+icon = "" # no icon
+confirm = false
+# Infers:
+# label = Poweroff" ## NOTE: label and action are mutually exclusive
+```

src/gui/widget/power_menu/custom.rs

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-//! A fully customizable power menu widget.
+//! A fully customizable power menu backend.
 
 use super::{Action, PowerMenuInit};
 
@@ -11,13 +11,24 @@ use super::{Action, PowerMenuInit};
 /// A fully-customizable power menu. You can run arbitrary commands and set labels for them. See [`Command`] for a list
 /// of all properties that can be configured
 pub struct CustomPowerMenuConfig {
+    /// A string label in the UI that indicates the backend this menu uses.
+    ///
+    /// For example, if you implement the power menu using `runit` commands, set the backend to Runit.
     backend: String,
     commands: Vec<Command>,
 }
 
+/// A set of customizations that can be done to the power menu item.
+///
+/// Setting [`Self::title`] to [`Title::Action`] allows ReGreet to infer the translated label, the icon to use, and the
+/// need to confirm the action.
+///
+/// However, if the power menu item does not fit any of the known to ReGreet [`Action`]s, you can use the
+/// [`Title::Label`] variant and optionally specify the [`Self::confirm`] and the [`Self::icon`].
 #[derive(Deserialize, Clone)]
 pub struct Command {
-    /// The title of the action.
+    /// The title of the action. This field is flattened in the config, so instead of setting `*command*.title.action`,
+    /// set `*command*.action`.
     #[serde(flatten)]
     title: Title,
 
@@ -27,11 +38,17 @@ pub struct Command {
 
     /// If `true`, a confirmation will be shown before the [`Self::command`] is executed.
     ///
+    /// The [`Option`] is handled according to these rules:
+    ///
     /// If [`Some`], use the value. Otherwise, try to derive the value from the [`Title::Action`], falling back to
     /// `false`. Actions that involve a poweroff are inferred to require confirmation.
     confirm: Option<bool>,
 
     /// The icon name to set for this action. A list of installed icons can be looked up using the `icon-library` app.
+    ///
+    /// If [`None`], the icon is inferred from the value of [`Title::Action`], falling back to no icon.
+    ///
+    /// An empty string can be used to disable the icon for this item.
     icon: Option<String>,
 }
 

src/gui/widget/power_menu/mod.rs

@@ -3,6 +3,32 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 //! A [serde-configurable][`PowerMenuConfig`] power menu.
+//!
+//! See submodules for information on how to configure each power menu backend.
+//!
+//! ## Implementing a custom power menu backend
+//!
+//! Users of ReGreet can use the [`custom`] backend to specify arbitrary commands you want to run. Although this is not
+//! intended, nothing stops you from adding entries unrelated to power management.
+//!
+//! However, if you want to add support for another init system, for example, it is best to implement a custom backend.
+//! Fortunately, this is easy to do.
+//!
+//! You will need to create a config for this backend. Most likely, only having a single `actions: Vec<Action>` field
+//! will be sufficient. For forward compatibility, please do not skip creating a `struct {}` to hold the config (exactly
+//! the `{}` struct format). Having this struct allows future maintainers to add or rename fields more easily without
+//! having to deal with config structure migrations.
+//!
+//! Make sure to implement sensible defaults for the entire struct. In cases where a default value should be inferred
+//! after the config is parsed, use an [`Option`] to detect that the user did not set the value and generate the default
+//! in the [`PowerMenuInit`] implementation.
+//!
+//! Finally, implement a coversion from your custom config struct using the [`PowerMenuInit`] trait. The [`Action`] can
+//! be used to infer a lot of information such as the [icon](`Action::icon`) and the [translated label](`Action::fl`).
+//! The confirmation requirement logic defaults to checking if the action
+//! [involves a poweroff](`Action::is_like_poweroff`).
+//!
+//! Lastly, add your config type as a variant to the [`PowerMenuConfig`].
 
 use custom::CustomPowerMenuConfig;
 use relm4::{
@@ -72,8 +98,8 @@ pub enum MenuState {
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PowerMenuMsg {
-    /// Sent when the user selected a power menu button. If the action requires confirmation (involves a poweroff of the
-    /// system) a confirmation screen is shown ([`PowerMenu::Confirm`] state).
+    /// Sent when the user selected a power menu button. If the action [requires confirmation](`Command::confirm`)
+    /// a confirmation screen is shown ([`MenuState::Confirm`] state).
     Request(usize),
 
     /// A confirmation of a [`PowerMenuMsg::Request`] was cancelled. Has no effect if no confirmation is requested.
@@ -322,6 +348,8 @@ impl Action {
         }
     }
 
+    /// Returns `true` if executing this action would power off the system (meaning reboot counts). Putting the system to
+    /// sleep does not count as it can be easily undone by waking up the system.
     pub const fn is_like_poweroff(&self) -> bool {
         matches!(
             self,
@@ -330,6 +358,7 @@ impl Action {
     }
 }
 
+/// A convenience trait that converts any power menu config into a set of information that the generic UI can display.
 trait PowerMenuInit {
     fn backend(&self) -> String;
     fn commands(self) -> Vec<Command>;

src/gui/widget/power_menu/systemd.rs

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-//! A systemd-aware power menu widget.
+//! The Systemd power menu backend.
 //!
 //! See supported actions as variants of [`Action`].
 
@@ -15,8 +15,12 @@ use super::{Action, Command, PowerMenuInit};
 #[derive(Deserialize, Debug, Clone)]
 #[serde(rename_all = "snake_case")]
 pub struct SystemdPowerMenuConfig {
-    /// The list of actions to show. Order is preserved. The first unique occurance is used, with duplicates discarded.
+    /// The list of actions to show. Order is preserved.
+    ///
+    /// The first unique occurance is used, with duplicates discarded.
     /// E.g. `["poweroff", "reboot", "poweroff"]` Results in this order of widgets: Poweroff, Reboot.
+    ///
+    /// The button labels, icons and `systemctl` commands are automatically selected based on the action you specify.
     #[serde(default = "default_actions")]
     pub actions: Vec<Action>,
 }

src/gui/widget/power_menu/unix.rs

@@ -2,9 +2,7 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-//! A power menu widget that uses the generic `man 8 shutdown` linux command.
-//!
-//! See supported actions as variants of [`Action`].
+//! A power menu backend that uses the generic `man 8 shutdown` linux command.
 
 use std::collections::HashSet;
 
@@ -14,10 +12,15 @@ use super::{Action, Command, PowerMenuInit};
 
 #[derive(Deserialize, Clone)]
 pub struct UnixPowerMenuConfig {
-    /// The list of actions to show. Order is preserved. The first unique occurance is used, with duplicates discarded.
+    /// The list of actions to show. Order is preserved.
+    ///
+    /// The first unique occurance is used, with duplicates discarded.
     /// E.g. `["poweroff", "reboot", "poweroff"]` Results in this order of widgets: Poweroff, Reboot.
     ///
-    /// Please note that only `poweroff`, `reboot`, and `halt` are supported by the unix `shutdown` command.
+    /// The button labels, icons and `systemctl` commands are automatically selected based on the action you specify.
+    ///
+    /// Please note that only `poweroff`, `reboot`, and `halt` are supported by the unix `shutdown` command. Other
+    /// actions are silently filtered out.
     #[serde(default = "default_actions")]
     actions: Vec<Action>,
 }
@@ -60,7 +63,10 @@ impl PowerMenuInit for UnixPowerMenuConfig {
                         "--halt".to_string(),
                         "now".to_string(),
                     ],
-                    _ => return acc,
+                    unsupported => {
+                        info!("{unsupported:?} is not supported in the Unix power menu backend.");
+                        return acc;
+                    }
                 };
 
                 acc.push(Command::new(

src/i18n.rs

@@ -4,7 +4,9 @@
 
 //! # Internationalization
 //!
-//! Firstly Initialize the language selection with [`init`]. Then use the [`fl`] macro to request a string by id.
+//! Firstly Initialize the language selection with [`init`]. Then use the [`fl!`] macro to request a string by id.
+//!
+//! [`fl!`]: crate::fl
 
 use std::sync::LazyLock;