From 62c6debab37753fe69e71b674984d15b865a9863 Mon Sep 17 00:00:00 2001 From: Maximilian Seidler <78690852+PaideiaDilemma@users.noreply.github.com> Date: Sat, 9 Nov 2024 17:54:46 +0100 Subject: [PATCH] hyprlock: document widget options in tables (#854) Allows for more accurate documentation. The type and default_value columns are usefull to have. This commit also adds documentation for which options support gradient values. --- pages/Hypr Ecosystem/hyprlock.md | 244 ++++++++++++++++++++++--------- 1 file changed, 171 insertions(+), 73 deletions(-) diff --git a/pages/Hypr Ecosystem/hyprlock.md b/pages/Hypr Ecosystem/hyprlock.md index f179c47..a4c7245 100644 --- a/pages/Hypr Ecosystem/hyprlock.md +++ b/pages/Hypr Ecosystem/hyprlock.md @@ -11,6 +11,14 @@ for Hyprland. Configuration is done via the config file at `~/.config/hypr/hyprlock.conf`. It is not required, but recommended. Without it, locking shows the current screen. +### Variable types + +Hyprlock uses the following types in addition to [Hyprland's variable types](../../Configuring/Variables#Variable_types). + +| type | description | +| -- | -- | +| layoutxy | vec2 with an optional `%` suffix, allowing users to specify sizes as percentages of the output size. | + ### General Variables in the `general` category: @@ -78,6 +86,7 @@ widget_name { - pixels: `10, 10` or `10px, 10px` - percentages: `10%, 10%` - mixed: `10%, 5px` +- Supported image formats are png, jpg and webp (no animations though) ### Shadowable @@ -99,23 +108,40 @@ used. If `path` is `screenshot`, a screenshot of your desktop at launch will be used. +| variable | description | type | default | +|--|--|--|--| +| monitor | monitor to draw on | str | [[Empty]] | +| path | image path, `screenshot` or empty to fill with `color` | str | [[Empty]] | +| color | fallback background color | color | rgba(17, 17, 17, 1.0) | +| blur_passes | the amount of passes to perform. 0 disables blurring | int | 0 | +| blur_size | blur size (distance) | int | 7 | +| noise | how much noise to apply | float | 0.0117 | +| contrast | contrast modulation for blur | float | 0.8916 | +| brightness | brightness modulation for blur | float | 0.8172 | +| vibrancy | Increase saturation of blurred colors | float | 0.1696 | +| vibrancy_darkness | How strong the effect of vibrancy is on dark areas | float | 0.05 | +| zindex | z-index of the widget | int | -1 | + +{{< callout type=info >}} + +Blur options are taken from hyprland. +See [Variables/#blur](../../Configuring/Variables/#blur). + +{{< /callout >}} + +{{% details title="Example background" closed="true" %}} + ```ini background { monitor = - path = /home/me/someImage.png # supports png, jpg, webp (no animations, though) + path = screenshot color = rgba(25, 20, 20, 1.0) - - # all these options are taken from hyprland, see https://wiki.hyprland.org/Configuring/Variables/#blur for explanations - blur_passes = 0 # 0 disables blurring - blur_size = 7 - noise = 0.0117 - contrast = 0.8916 - brightness = 0.8172 - vibrancy = 0.1696 - vibrancy_darkness = 0.0 + blur_passes = 2 } ``` +{{% /details %}} + ### Image ✓ Shadowable @@ -124,17 +150,30 @@ Draws an image. If `path` is empty or missing, nothing will be shown. +| variable | description | type | default | +|--|--|--|--| +| monitor | monitor to draw on | str | [[Empty]] | +| path | image path | str | [[Empty]] | +| size | size scale based on the lesser side of the image | int | 150 | +| rounding | negative values result in a circle | int | -1 | +| border_size | border size | int | 0 | +| border_color | border color | gradient | rgba(221, 221, 221, 1.0) | +| rotate | rotation in degrees, counter-clockwise | int | 0 | +| reload_time | seconds between reloading, 0 to reload with SIGUSR2 | int | -1 | +| reload_cmd | command to get new path. if empty, old path will be used. don't run "follow" commands like tail -F | str | [[Empty]] | +| position | position of the image | layoutxy | 0, 0 | +| halign | horizontal alignment | str | center | +| valign | vertical alignment | str | center | +| zindex | z-index of the widget | int | 0 | + +{{% details title="Example image" closed="true" %}} + ```ini image { monitor = path = /home/me/cutie.png - size = 150 # lesser side if not 1:1 ratio - rounding = -1 # negative values mean circle - border_size = 4 - border_color = rgb(221, 221, 221) - rotate = 0 # degrees, counter-clockwise - reload_time = -1 # seconds between reloading, 0 to reload with SIGUSR2 - reload_cmd = # command to get new path. if empty, old path will be used. don't run "follow" commands like tail -F + size = 150 + rounding = 0 # no rounding position = 0, 200 halign = center @@ -142,22 +181,40 @@ image { } ``` +{{% /details %}} + ### Shape ✓ Shadowable Draws a shape. +| variable | description | type | default | +|--|--|--|--| +| monitor | monitor to draw on | str | [[Empty]] | +| size | size of the shape | layoutxy | 100, 100 | +| color | color of the shape | color | rgba(17, 17, 17, 1.0) | +| rounding | negative values result in a circle | int | -1 | +| rotate | rotation in degrees, counter-clockwise | int | 0 | +| border_size | border size | int | 0 | +| border_color | border color | gradient | rgba(0, 207, 230, 1.0) | +| xray | if true, make a "hole" in the background (rectangle of specified size, no rotation) | bool | false | +| position | position of the shape | layoutxy | 0, 0 | +| halign | horizontal alignment | str | center | +| valign | vertical alignment | str | center | +| zindex | z-index of the widget | int | 0 | + + +{{% details title="Example shape" closed="true" %}} + ```ini shape { monitor = size = 360, 60 - color = rgba(17, 17, 17, 1.0) - rounding = -1 - border_size = 8 + color = rgba(0, 0, 0, 0.0) # no fill + rounding = -1 # circle + border_size = 4 border_color = rgba(0, 207, 230, 1.0) - rotate = 0 - xray = false # if true, make a "hole" in the background (rectangle of specified size, no rotation) position = 0, 80 halign = center @@ -165,48 +222,48 @@ shape { } ``` +{{% /details %}} + ### Input Field ✓ Shadowable Draws a password input field. -```ini -input-field { - monitor = - size = 200, 50 - outline_thickness = 3 - dots_size = 0.33 # Scale of input-field height, 0.2 - 0.8 - dots_spacing = 0.15 # Scale of dots' absolute size, -1.0 - 1.0 - dots_center = false - dots_rounding = -1 # -1 default circle, -2 follow input-field rounding - dots_fade_time = 200 # Milliseconds until a dot fully fades in - dots_text_format = # Text character used for the input indicator. Leave empty for a rectangle that will be rounded via dots_rounding (default). - outer_color = rgb(151515) - inner_color = rgb(200, 200, 200) - font_color = rgb(10, 10, 10) - font_family = Noto Sans # Font used for placeholder_text, fail_text and dots_text_format. - fade_on_empty = true - fade_timeout = 1000 # Milliseconds before fade_on_empty is triggered. - placeholder_text = Input Password... # Text rendered in the input box when it's empty. - hide_input = false - rounding = -1 # -1 means complete rounding (circle/oval) - check_color = rgb(204, 136, 34) - fail_color = rgb(204, 34, 34) # if authentication failed, changes outer_color and fail message color - fail_text = $FAIL ($ATTEMPTS) # can be set to empty - fail_timeout = 2000 # milliseconds before fail_text and fail_color disappears - fail_transition = 300 # transition time in ms between normal outer_color and fail_color - capslock_color = -1 - numlock_color = -1 - bothlock_color = -1 # when both locks are active. -1 means don't change outer color (same for above) - invert_numlock = false # change color if numlock is off - swap_font_color = false # see below - - position = 0, -20 - halign = center - valign = center -} -``` +| variable | description | type | default | +|--|--|--|--| +| monitor | monitor to draw on | str | [[Empty]] | +| size | size of the input field. | layoutxy | 400, 90 | +| outline_thickness | thickness of the outline | int | 4 | +| dots_size | size of the dots. [0.2 - 0.8] | float | 0.25 | +| dots_spacing | spacing between dots. [-1.0 - 1.0] | float | 0.15 | +| dots_center | whether to center the dots. align left otherwise | bool | true | +| dots_rounding | rounding of the dots | int | -1 | +| dots_fade_time | Milliseconds until a dot fully fades in | int | 200 | +| dots_text_format | text character(s) used for the input indicator, rounded rectangles are the default. | str | [[Empty]] | +| outer_color | border color | gradient | rgba(17, 17, 17, 1.0) | +| inner_color | color of the inner box | color | rgba(200, 200, 200, 1.0) | +| font_color | color of the font | color | rgba(10, 10, 10, 1.0) | +| font_family | font family | str | Noto Sans | +| fade_on_empty | fade the input field when empty | bool | true | +| fade_timeout | milliseconds before `fade_on_empty` is triggered | int | 2000 | +| placeholder_text | text rendered in the input box when it's empty | str | `Input Password...` | +| hide_input | render an input indicator similar to swaylock instead of dots when set to true | bool | false | +| rounding | -1 means complete rounding (circle/oval) | int | -1 | +| check_color | color accent when waiting for waiting for the authentication result | gradient | rgba(204, 136, 34, 1.0) | +| fail_color | color accent when authentication fails | gradient | rgba(204, 34, 34, 1.0) | +| fail_text | text rendered when authentication fails | str | `$FAIL ($ATTEMPTS)` | +| fail_timeout | milliseconds before `fail_text` and `fail_color` disappears | int | 2000 | +| fail_transition | transition time in ms between normal `outer_color` and `fail_color` | int | 300 | +| capslock_color | color accent when capslock is active | gradient | [[Empty]] | +| numlock_color | color accent when numlock is active | gradient | [[Empty]] | +| bothlock_color | color accent when both locks are active | gradient | [[Empty]] | +| invert_numlock | change color if numlock is off | bool | false | +| swap_font_color | swap font and inner colors on color change events | bool | false | +| position | position of the input field | layoutxy | 0, 0 | +| halign | horizontal alignment | str | center | +| valign | vertical alignment | str | center | +| zindex | z-index of the widget | int | 0 | {{< callout type=info >}} @@ -218,6 +275,7 @@ Behaviour of `swap_font_color` is as follows: - `outline_thickness` is `0`: if set, font color will be swapped with inner one on color change events (e.g. Caps-lock on or password check). - `outline_thickness` is not `0`: if set, font and inner colors will be swapped on password check and authentication failure. +- `swap_font_color` will narrow the accent colors from a gradient to a single color by using the first specified color. {{< /callout >}} @@ -230,27 +288,48 @@ Available variables for `fail_text`: - `$FAIL` - pam fail reason - `$ATTEMPTS` - number of failed authentication attempts +{{% details title="Example input-field" closed="true" %}} + +```ini +input-field { + monitor = + size = 20%, 5% + outline_thickness = 3 + inner_color = rgba(0, 0, 0, 0.0) # no fill + + outer_color = rgba(33ccffee) rgba(00ff99ee) 45deg + check_color=rgba(00ff99ee) rgba(ff6633ee) 120deg + fail_color=rgba(ff6633ee) rgba(ff0066ee) 40deg + + font_color = rgb(143, 143, 143) + fade_on_empty = false + rounding = 15 + + position = 0, -20 + halign = center + valign = center +} +``` +{{% /details %}} + ### Label ✓ Shadowable Draws a label. -```ini -label { - monitor = - text = Hi there, $USER - text_align = center # center/right or any value for default left. multi-line text alignment inside label container - color = rgba(200, 200, 200, 1.0) - font_size = 25 - font_family = Noto Sans - rotate = 0 # degrees, counter-clockwise - - position = 0, 80 - halign = center - valign = center -} -``` +| variable | description | type | default | +|--|--|--|--| +| monitor | monitor to draw on | str | [[Empty]] | +| text | text to render | str | Sample Text | +| text_align | multi-line text alignment inside label container. center/right or any value for default left. | str | center | +| color | color of the text | color | rgba(254, 254, 254, 1.0) | +| font_size | size of the font | int |16 | +| font_family | font family | str | Sans | +| rotate | rotation in degrees, counter-clockwise | int | 0 | +| position | position of the label | layoutxy | 0, 0 | +| halign | horizontal alignment | str | center | +| valign | vertical alignment | str | center | Available variables for `text`: @@ -279,6 +358,25 @@ Worth noting: - Variables seen above are parsed _before_ the command is ran. - **do not** run commands that never exit. This will hang the AsyncResourceGatherer and you won't have a good time. +{{% details title="Example label" closed="true" %}} + +```ini +label { + monitor = + text = Hi there, $USER + color = rgba(200, 200, 200, 1.0) + font_size = 25 + font_family = Noto Sans + + position = 0, 80 + halign = center + valign = center +} +``` + +{{% /details %}} + + ## User Signals - `SIGUSR1` - unlocks hyprlock. For example, you can switch to a another tty and run `pkill -USR1 hyprlock`.