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.
hyprwm · Nov 9, 2024 · 62c6deb · 62c6deb
1 parent da02535
commit 62c6deb
Showing 1 changed file with 169 additions and 71 deletions.
diff --git 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
 
 &check; Shadowable
@@ -124,89 +150,120 @@ 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
     valign = center
 }
 ```
 
+{{% /details %}}
+
 ### Shape
 
 &check; 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
     valign = center
 }
 ```
 
+{{% /details %}}
+
 ### Input Field
 
 &check; 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 = <i>Input Password...</i> # 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 = <i>$FAIL <b>($ATTEMPTS)</b></i> # 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 | `<i>Input Password...</i>` |
+| 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 | `<i>$FAIL <b>($ATTEMPTS)</b></i>` |
+| 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
 
-### Label
-
-&check; Shadowable
-
-Draws a label.
+{{% details title="Example input-field" closed="true" %}}
 
 ```ini
-label {
+input-field {
     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
+    size = 20%, 5%
+    outline_thickness = 3
+    inner_color = rgba(0, 0, 0, 0.0) # no fill
 
-    position = 0, 80
+    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
+
+&check; Shadowable
+
+Draws a label.
+
+| 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`.