hyprland-wiki/pages/Configuring/Binds.md

357 lines
8.5 KiB
Markdown
Raw Normal View History

---
weight: 5
title: Binds
---
2022-09-24 15:32:40 +02:00
## Basic
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bind=MODS,key,dispatcher,params
```
for example,
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bind=SUPER_SHIFT,Q,exec,firefox
```
will bind opening firefox to <key>SUPER</key> + <key>SHIFT</key> + <key>Q</key>
{{< callout type=info >}}
2022-09-24 15:32:40 +02:00
For binding keys without a modkey, leave it empty:
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bind=,Print,exec,grim
```
{{< /callout >}}
2022-09-24 15:32:40 +02:00
2024-03-17 13:44:39 +01:00
_For a complete mod list, see [Variables](../Variables/#variable-types)._
_The dispatcher list can be found in
2024-03-17 13:44:39 +01:00
[Dispatchers](../Dispatchers/#list-of-dispatchers)._
2022-09-24 15:32:40 +02:00
## Uncommon syms / binding with a keycode
See the
[xkbcommon-keysyms.h header](https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h)
for all the keysyms. The name you should use is the segment after `XKB_KEY_`.
2022-09-24 15:32:40 +02:00
If you are unsure of what your key's name is, you can use `xev` or `wev` to find
that information.
2022-09-24 15:32:40 +02:00
If you want to bind by a keycode, you can just input it in the KEY position with
a `code:` prefix, e.g.:
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2023-03-23 14:06:03 +01:00
bind=SUPER,code:28,exec,amongus
2022-09-24 15:32:40 +02:00
```
Will bind <key>SUPER</key> + <key>T</key>. (<key>T</key> is keycode 28.) - You
can also use `xev` or `wev` to find keycodes.
## Misc
### Unbind
2022-09-24 15:32:40 +02:00
You can also unbind with `unbind`, e.g.:
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
unbind=SUPER,O
```
May be useful for dynamic keybindings with `hyprctl`.
```sh
hyprctl keyword unbind SUPER,O
```
### Mouse buttons
2022-09-24 15:32:40 +02:00
You can also bind mouse buttons, by prefacing the mouse keycode with `mouse:`,
for example:
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bind=SUPER,mouse:272,exec,amongus
```
will bind it to <key>SUPER</key> + <key>LMB</key>.
### Only modkeys
2022-09-24 15:32:40 +02:00
For binding only modkeys, you need to use the TARGET modmask (with the
activating mod) and the `r` flag, e.g.:
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bindr=SUPERALT,Alt_L,exec,amongus
```
### Mouse wheel
You can also bind the mouse wheel with `mouse_up` and `mouse_down` (or
`mouse_left` and `mouse_right` if your wheel supports horizontal scrolling):
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bind=SUPER,mouse_down,workspace,e-1
```
2022-09-24 15:32:40 +02:00
(control the reset time with `binds:scroll_event_delay`)
### Switches
2022-10-04 21:11:56 +02:00
Useful for binding e.g. the lid close/open event:
```ini
# trigger when the switch is toggled
2022-10-04 21:11:56 +02:00
bindl=,switch:[switch name],exec,swaylock
# trigger when the switch is turning on
bindl=,switch:on:[switch name],exec,hyprctl keyword monitor "eDP-1, disable"
# trigger when the switch is turning off
bindl=,switch:off:[switch name],exec,hyprctl keyword monitor "eDP-1, 2560x1600, 0x0, 1"
2022-10-04 21:11:56 +02:00
```
2022-10-04 21:11:56 +02:00
check out your switches in `hyprctl devices`.
### Multiple binds to one key
2022-10-30 23:50:10 +01:00
You can trigger multiple actions with one keybind by assigning multiple binds to
one combination, e.g.:
2022-10-30 23:50:10 +01:00
```
# to switch between windows in a floating workspace
bind = SUPER,Tab,cyclenext, # change focus to another window
bind = SUPER,Tab,bringactivetotop, # bring it to the top
```
The keybinds will be executed in the order they were created. (top to bottom)
## Bind flags
2022-09-24 15:32:40 +02:00
`bind` supports flags in this format:
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bind[flags]=...
```
e.g.:
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bindrl=MOD,KEY,exec,amongus
```
Flags:
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
l -> locked, aka. works also when an input inhibitor (e.g. a lockscreen) is active.
r -> release, will trigger on release of a key.
2022-09-24 15:32:40 +02:00
e -> repeat, will repeat when held.
n -> non-consuming, key/mouse events will be passed to the active window in addition to triggering the dispatcher.
2022-09-24 15:32:40 +02:00
m -> mouse, see below
2023-08-25 12:36:26 +02:00
t -> transparent, cannot be shadowed by other binds.
2023-10-17 21:10:49 +02:00
i -> ignore mods, will ignore modifiers.
2022-09-24 15:32:40 +02:00
```
Example Usage:
```ini
2023-03-24 14:04:10 +01:00
# Example volume button that allows press and hold, volume limited to 150%
binde=, XF86AudioRaiseVolume, exec, wpctl set-volume -l 1.5 @DEFAULT_AUDIO_SINK@ 5%+
# Example volume button that will activate even while an input inhibitor is active
bindl=, XF86AudioLowerVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-
# Start wofi opens wofi on first press, closes it on second
bindr=SUPER, SUPER_L, exec, pkill wofi || wofi
# See Mouse Binds section for bindm usage
```
## Mouse Binds
Mouse binds are binds that heavily rely on a mouse, usually its movement. They
will have one less arg, and look for example like this:
2022-09-24 15:32:40 +02:00
```ini
2022-09-24 15:32:40 +02:00
bindm=ALT,mouse:272,movewindow
```
this will create a bind with <key>ALT</key> + <key>LMB</key> to move the window
with your mouse.
_Available mouse binds_:
2022-09-24 15:32:40 +02:00
2023-08-08 18:53:03 +02:00
| Name | Description | Params |
| --- | --- | --- |
| movewindow | moves the active window | none |
2023-08-08 18:53:03 +02:00
| resizewindow | resizes the active window | 1 - resize and keep window aspect ratio, 2 - resize and ignore `keepaspectratio` window rule/prop, none or anything else for normal resize |
2022-09-24 15:32:40 +02:00
_Common mouse buttons' codes:_
```txt
2022-09-24 15:32:40 +02:00
LMB -> 272
RMB -> 273
```
_for more, you can of course use `wev` to check._
2022-09-24 15:32:40 +02:00
{{< callout type=info >}}
2022-09-24 15:32:40 +02:00
Mouse binds, despite their name, behave like normal binds. You are free to use
whatever keys / mods you please. When held, the mouse function will be
activated.
{{< /callout >}}
2022-09-24 15:32:40 +02:00
## Binding mods
2022-09-24 15:32:40 +02:00
You can bind a mod alone like this:
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bindr=ALT,Alt_L,exec,amongus
```
## Global Keybinds
### Classic
2022-09-24 15:32:40 +02:00
Yes, you heard this right, Hyprland does support global keybinds for ALL apps,
including OBS, Discord, Firefox, etc.
2024-03-17 13:44:39 +01:00
See the [`pass` dispatcher](../Dispatchers/#list-of-dispatchers) for keybinds.
2022-09-24 15:32:40 +02:00
Let's take OBS as an example: the "Start/Stop Recording" keybind is set to
<key>SUPER</key> + <key>F10</key>, and you want to make it work globally.
2022-09-24 15:32:40 +02:00
Simply add
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bind = SUPER,F10,pass,^(com\.obsproject\.Studio)$
```
2022-09-24 15:32:40 +02:00
to your config and you're done.
`pass` will pass the PRESS and RELEASE events by itself, no need for a `bindr`.
This also means that push-to-talk will work flawlessly with one pass, e.g.:
2022-09-24 16:03:37 +02:00
```ini
2022-09-24 15:32:40 +02:00
bind=,mouse:276,pass,^(TeamSpeak 3)$
```
Will pass MOUSE5 to TeamSpeak3.
{{< callout >}}
2022-09-24 15:32:40 +02:00
XWayland is a bit wonky. Make sure that what you're passing is a "global Xorg
keybind", otherwise passing from a different XWayland app may not work.
It works flawlessly with all native Wayland applications though.
{{< /callout >}}
### DBus Global Shortcuts
2023-04-11 00:02:23 +02:00
Some applications may already support the GlobalShortcuts portal in
xdg-desktop-portal.
2023-04-09 14:53:09 +02:00
If that's the case, then it's recommended to use this method instead of `pass`.
Open your desired app and issue `hyprctl globalshortcuts`. This will give you a
list of currently registered shortcuts with their description(s).
2023-04-09 14:53:09 +02:00
Choose whichever you like, for example `coolApp:myToggle`
Bind it to whatever you want with the `global` dispatcher:
```
bind = SUPERSHIFT, A, global, coolApp:myToggle
```
{{< callout type=info >}}
Please note that this function will _only_ work with
2024-03-17 13:44:39 +01:00
[XDPH](../../Hypr-Ecosystem/xdg-desktop-portal-hyprland).
2023-04-11 00:02:23 +02:00
{{</ callout >}}
## Submaps
2022-09-24 15:32:40 +02:00
2022-12-25 16:16:04 +01:00
If you want keybind submaps, also known as _modes_ or _groups_, for example if
you press <key>ALT</key> + <key>R</key>, you can enter a "resize" mode, resize
with arrow keys, and leave with escape, do it like this:
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2022-10-18 17:08:17 +02:00
# will switch to a submap called resize
bind=ALT,R,submap,resize
2022-09-24 15:32:40 +02:00
2022-10-18 17:08:17 +02:00
# will start a submap called "resize"
submap=resize
2022-09-24 15:32:40 +02:00
2022-10-18 17:08:17 +02:00
# sets repeatable binds for resizing the active window
2022-09-24 15:32:40 +02:00
binde=,right,resizeactive,10 0
binde=,left,resizeactive,-10 0
binde=,up,resizeactive,0 -10
binde=,down,resizeactive,0 10
2022-10-18 17:08:17 +02:00
# use reset to go back to the global submap
bind=,escape,submap,reset
2022-09-24 15:32:40 +02:00
2022-10-18 17:08:17 +02:00
# will reset the submap, meaning end the current one and return to the global one
submap=reset
2022-09-24 15:32:40 +02:00
# keybinds further down will be global again...
```
{{< callout type=warning >}}
Do not forget a keybind to reset the keymap while inside it! (In this case,
`escape`)
{{< /callout >}}
2022-09-24 15:32:40 +02:00
If you get stuck inside a keymap, you can use `hyprctl dispatch submap reset` to
go back. If you do not have a terminal open, tough luck buddy. You have been
warned.
2022-10-18 17:08:17 +02:00
You can also set the same keybind to perform multiple actions, such as resize
and close the submap, like so:
```ini
bind=ALT,R,submap,resize
submap=resize
bind=,right,resizeactive,10 0
bind=,right,submap,reset
# ...
submap=reset
```
This works because the binds are executed in the order they appear, and
assigning multiple actions per bind is possible.
## Catch-All
You can also define a keybind via the special `catchall` keyword, which
activates no matter which key is pressed. This can be used to prevent any keys
from passing to your active application while in a submap or to exit it
immediately when any unknown key is pressed:
```ini
bind=,catchall,submap,reset
```
## Example Binds
### Media
These binds set the expected behavior for regular keyboard media volume keys,
including when the screen is locked:
```ini
bindel=, XF86AudioRaiseVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+
bindel=, XF86AudioLowerVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-
bindl=, XF86AudioMute, exec, wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle
```