hyprland-wiki/pages/Hypr Ecosystem/hyprlock.md

259 lines
8.5 KiB
Markdown
Raw Permalink Normal View History

---
weight: 4
title: hyprlock
---
2024-02-19 17:52:58 +01:00
hyprlock is a simple, yet fast, multi-threaded and GPU-accelerated screen lock
for Hyprland.
2024-02-19 17:52:58 +01:00
## Configuration
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.
2024-02-19 17:52:58 +01:00
### General
Variables in the `general` category:
| variable | description | type | default |
| -- | -- | -- | -- |
| disable_loading_bar | disables the loading bar on the bottom of the screen while hyprlock is booting up. | bool | false |
| hide_cursor | hides the cursor instead of making it visible | bool | false |
2024-02-21 17:49:51 +01:00
| grace | the amount of seconds for which the lockscreen will unlock on mouse movement. | int | 0 |
2024-02-22 01:36:28 +01:00
| no_fade_in | disables the fadein animation | bool | false |
| no_fade_out | disables the fadeout animation | bool | false |
| ignore_empty_input | skips validation when no password is provided | bool | false |
| immediate_render | makes hyprlock immediately start to draw widgets. Backgrounds will render `background:color` until their `background:path` resource is available | bool | false |
| pam_module | sets the pam module used for authentication. If the module isn't found in `/etc/pam.d`, "su" will be used as a fallback | str | hyprlock |
2024-05-04 19:40:37 +02:00
| text_trim | sets if the text should be trimmed, useful to avoid trailing newline in commands output | bool | true |
2024-02-19 17:52:58 +01:00
## Keyboard Shortcuts and Actions
The following keys and key-combinations describe hyprlock's default behaviour:
| input | description |
| -- | -- |
| ESC | Clear password buffer |
| Ctrl + u | Clear password buffer |
| Ctrl + Backspace | Clear password buffer |
2024-02-19 17:52:58 +01:00
## Widgets
The entire configuration of how hyprlock looks is done via widgets.
```ini
widget_name {
monitor =
# further options
}
```
`monitor` can be left empty for "all monitors"
## Widget List
### General remarks
- All rendered text supports
[pango markup](https://docs.gtk.org/Pango/pango_markup.html).
- Additionally hyprlock will parse `<br/>` for your convenience. (That's a
linebreak) Remember to enable linebreaks in your spans with
`allow_breaks="true"`.
- Positioning is done via halign, valign, position, and zindex. Position is an added
offset to the result of alignment.
- halign: `left`, `center`, `right`, `none`. valign: `top`, `center`,
`bottom`, `none`
- zindex: Widgets with larger numbers will be placed above widgets with smaller numbers. All widgets default to 0, except background which defaults to -1.
2024-03-05 21:30:47 +01:00
### Shadowable
Some widgets are shadowable, meaning they can have a shadow. For those widgets, you get:
2024-03-05 21:30:47 +01:00
| variable | description | type | default |
| -- | -- | -- | -- |
| shadow_passes | passes for shadow, 0 to disable | int | 0 |
| shadow_size | size for shadow | int | 3 |
| shadow_color | shadow color | color | rgb(0,0,0) |
| shadow_boost | boost shadow's opacity | float | 1.2 |
2024-02-19 17:52:58 +01:00
### Background
2024-02-19 21:52:04 +01:00
Draws a background image or fills with color.
If `path` is empty or missing, will use `color`. Otherwise, the image will be
used.
2024-02-19 17:52:58 +01:00
2024-02-21 23:20:56 +01:00
If `path` is `screenshot`, a screenshot of your desktop at launch will be used.
2024-02-19 17:52:58 +01:00
```ini
background {
monitor =
2024-04-24 19:06:50 +02:00
path = /home/me/someImage.png # supports png, jpg, webp (no animations, though)
2024-02-19 21:52:04 +01:00
color = rgba(25, 20, 20, 1.0)
2024-02-21 23:20:56 +01:00
# 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
2024-02-19 17:52:58 +01:00
}
```
2024-03-15 01:45:26 +01:00
### Image
&check; Shadowable
Draws an image.
If `path` is empty or missing, nothing will be shown.
```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
2024-03-15 01:45:26 +01:00
position = 0, 200
halign = center
valign = center
}
```
2024-04-10 18:24:34 +02:00
### Shape
&check; Shadowable
Draws a shape.
2024-04-10 18:24:34 +02:00
```ini
shape {
monitor =
size = 360, 60
color = rgba(17, 17, 17, 1.0)
rounding = -1
border_size = 8
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
}
```
2024-02-19 17:52:58 +01:00
### Input Field
2024-03-05 21:30:47 +01:00
&check; Shadowable
2024-02-19 17:52:58 +01:00
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, 0.0 - 1.0
dots_center = false
dots_rounding = -1 # -1 default circle, -2 follow input-field rounding
2024-02-19 17:52:58 +01:00
outer_color = rgb(151515)
inner_color = rgb(200, 200, 200)
font_color = rgb(10, 10, 10)
2024-02-19 17:52:58 +01:00
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.
2024-02-20 15:42:45 +01:00
hide_input = false
rounding = -1 # -1 means complete rounding (circle/oval)
2024-03-11 16:17:29 +01:00
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
2024-02-19 17:52:58 +01:00
}
```
{{< callout type=info >}}
#### Colors information
When `outline_thickness` set to `0`, the color of the inner box will be changed instead of the outer.
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.
{{< /callout >}}
Available variables for `placeholder_text`:
- `$PROMPT` - prompt text provided by pam. Usually this will be "Password: ", but it depends on your pam configuration.
Available variables for `fail_text`:
- `$FAIL` - pam fail reason
- `$ATTEMPTS` - number of failed authentication attempts
2024-02-19 17:52:58 +01:00
### Label
2024-03-05 21:30:47 +01:00
&check; Shadowable
2024-02-19 17:52:58 +01:00
Draws a label.
```ini
label {
monitor =
2024-02-20 01:12:40 +01:00
text = Hi there, $USER
text_align = center # center/right or any value for default left. multi-line text alignment inside label container
2024-02-19 17:52:58 +01:00
color = rgba(200, 200, 200, 1.0)
font_size = 25
font_family = Noto Sans
rotate = 0 # degrees, counter-clockwise
2024-02-19 17:52:58 +01:00
position = 0, 80
halign = center
valign = center
2024-02-19 17:52:58 +01:00
}
2024-02-20 01:12:40 +01:00
```
Available variables for `text`:
2024-03-31 03:06:31 +02:00
- `$USER` - username (e.g. linux-user)
- `$DESC` - user description (e.g. Linux User)
- `$TIME` - current time (e.g. `13:37`)
- `$PROMPT` - last pam prompt
- `$FAIL` - last pam fail reason
- `$ATTEMPTS` - failed attempts
- `$LAYOUT` - current keyboard layout
2024-02-21 15:11:41 +01:00
`text` also supports launching commands, for example:
2024-02-21 15:11:41 +01:00
```ini
text = cmd[update:1000] echo "<span foreground='##ff2222'>$(date)</span>"
```
2024-02-21 15:11:41 +01:00
Worth noting:
- `update:` - time is in ms.
- label can be forcefully updated by specifying `update:<time>:1` or `update:<time>:true` and sending `SIGUSR2` to hyprlock. `<time>` can be `0` in this case.
- `$ATTEMPTS[<string>]` format can be used to show `<string>` when there are no failed attempts. You can use pango-markup here. `<string>` can be empty to hide.
- `$LAYOUT[<str0>,<str1>,...]` format is available to replace indexed layouts. You can use settings from `hyprland.conf`, e.g. `$LAYOUT[en,ru,de]`. Also, single `!` character will hide layout. E.g. `$LAYOUT[!]` will hide default (0 indexed) and show others.
- Variables seen above are parsed _before_ the command is ran.
2024-02-21 15:13:21 +01:00
- **do not** run commands that never exit. This will hang the AsyncResourceGatherer and you won't have a good time.
2024-02-21 15:11:41 +01:00
## User Signals
2024-02-21 15:11:41 +01:00
- `SIGUSR1` - unlocks hyprlock. For example, you can switch to a another tty and run `pkill -USR1 hyprlock`.
- `SIGUSR2` - updates labels and images. See above.