Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

hyprlock: document widget options in tables #854

Merged
merged 1 commit into from
Nov 9, 2024
Merged

hyprlock: document widget options in tables #854

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
240 changes: 169 additions & 71 deletions pages/Hypr Ecosystem/hyprlock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
vaxerski marked this conversation as resolved.
Show resolved Hide resolved

| 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:
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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 >}}

Expand All @@ -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 >}}

Expand All @@ -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`:

Expand Down Expand Up @@ -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`.
Expand Down