hyprland-wiki/pages/Configuring/Dispatchers.md

203 lines
12 KiB
Markdown
Raw Permalink Normal View History

---
weight: 6
title: Dispatchers
---
2022-09-24 15:32:40 +02:00
Please keep in mind some layout-specific dispatchers will be listed in the
layout pages (See the sidebar).
## Parameter explanation
2022-09-24 15:32:40 +02:00
| Param type | Description |
| --- | --- |
2024-04-21 16:19:54 +02:00
| window | a window. Any of the following: class regex (by default, optionally `class:`), `initialclass:` initial class regex, `title:` title regex, `initialtitle` initial title regex, `pid:` the pid, `address:` the address, `activewindow` an active window, `floating` the first floating window on the current workspace, `tiled` the first tiled window on the current workspace |
2022-09-24 15:32:40 +02:00
| workspace | see below. |
| direction | `l` `r` `u` `d` left right up down |
2022-11-10 13:22:49 +01:00
| monitor | One of: direction, ID, name, `current`, relative (e.g. `+1` or `-1`) |
| resizeparams | relative pixel delta vec2 (e.g. `10 -10`), optionally a percentage of the window size (e.g. `20 25%`) or `exact` followed by an exact vec2 (e.g. `exact 1280 720`), optionally a percentage of the screen size (e.g. `exact 50% 50%`) |
| floatvalue | a relative float delta (e.g `-0.2` or `+0.2`) or `exact` followed by a the exact float value (e.g. `exact 0.5`) |
| zheight | `top` or `bottom` |
2024-05-24 20:59:09 +02:00
| mod | `SUPER`, `SUPER_ALT`, etc. |
| key | `g`, `code:42`, `42` or mouse clicks (`mouse:272`) |
2022-09-24 15:32:40 +02:00
## List of Dispatchers
2022-09-24 15:32:40 +02:00
| Dispatcher | Description | Params |
| --- | --- | --- |
| exec | executes a shell command | command (supports rules, see [below]({{< relref "#executing-with-rules" >}})) |
| execr | executes a raw shell command (does not support rules) | command |
2022-09-24 15:32:40 +02:00
| pass | passes the key (with mods) to a specified window. Can be used as a workaround to global keybinds not working on Wayland. | window |
2024-05-24 20:59:09 +02:00
| sendshortcut | sends specified keys (with mods) to an optionally specified window. Can be used like pass | mod, key[, window] |
2022-09-24 15:32:40 +02:00
| killactive | closes (not kills) the active window | none |
| closewindow | closes a specified window | window |
| workspace | changes the workspace | workspace |
| movetoworkspace | moves the focused window to a workspace | workspace OR `workspace,window` for a specific window |
| movetoworkspacesilent | same as above, but doesn't switch to the workspace | workspace OR `workspace,window` for a specific window |
2022-09-24 15:32:40 +02:00
| togglefloating | toggles the current window's floating state | left empty / `active` for current, or `window` for a specific window |
| setfloating | sets the current window's floating state to true | left empty / `active` for current, or `window` for a specific window |
| settiled | sets the current window's floating state to false | left empty / `active` for current, or `window` for a specific window |
| fullscreen | toggles the focused window's fullscreen mode | 0 - fullscreen (takes your entire screen), 1 - maximize (keeps gaps and bar(s)) |
| fullscreenstate | sets the focused window's fullscreen mode and the one sent to the client | `internal client`, where internal and client can be `-1` - current, `0` - none, `1` - maximize, `2` - fullscreen, `3` - maximize and fullscreen |
| dpms | sets all monitors' DPMS status. Do not use with a keybind directly. | `on`, `off`, or `toggle`. For specific monitor add monitor name after a space |
| pin | pins a window (i.e. show it on all workspaces) _note: floating only_ | left empty / `active` for current, or `window` for a specific window |
2022-09-24 15:32:40 +02:00
| movefocus | moves the focus in a direction | direction |
| movewindow | moves the active window in a direction or to a monitor. For floating windows, moves the window to the screen edge in that direction | direction or `mon:` and a monitor, optionally followed by a space and `silent` to prevent the focus from moving with the window|
| swapwindow | swaps the active window with another window in the given direction | direction |
| centerwindow | center the active window _note: floating only_ | none (for monitor center) or 1 (to respect monitor reserved area) |
2022-09-24 15:32:40 +02:00
| resizeactive | resizes the active window | resizeparams |
| moveactive | moves the active window | resizeparams |
| resizewindowpixel | resizes a selected window | `resizeparams,window`, e.g. `100 100,^(kitty)$` |
| movewindowpixel | moves a selected window | `resizeparams,window` |
2023-12-24 15:10:29 +01:00
| cyclenext | focuses the next window on a workspace | none (for next) or `prev` (for previous) additionally `tiled` for only tiled, `floating` for only floating. `prev tiled` is ok. |
2022-09-24 15:32:40 +02:00
| swapnext | swaps the focused window with the next window on a workspace | none (for next) or `prev` (for previous) |
| tagwindow | apply tag to current or the first window matching | `tag [window]`, e.g. `+code ^(foot)$`, `music` |
2022-09-24 15:32:40 +02:00
| focuswindow | focuses the first window matching | window |
| focusmonitor | focuses a monitor | monitor |
| splitratio | changes the split ratio | floatvalue |
2022-09-24 15:32:40 +02:00
| movecursortocorner | moves the cursor to the corner of the active window | direction, 0 - 3, bottom left - 0, bottom right - 1, top right - 2, top left - 3 |
| movecursor | moves the cursor to a specified position | `x y` |
| renameworkspace | rename a workspace | `id name`, e.g. `2 work` |
2022-09-24 15:32:40 +02:00
| exit | exits the compositor with no questions asked. | none |
| forcerendererreload | forces the renderer to reload all resources and outputs | none |
| movecurrentworkspacetomonitor | Moves the active workspace to a monitor | monitor |
| focusworkspaceoncurrentmonitor | Focuses the requested workspace on the current monitor, swapping the current workspace to a different monitor if necessary. If you want XMonad/Qtile-style workspace switching, replace `workspace` in your config with this. | workspace |
2022-09-24 15:32:40 +02:00
| moveworkspacetomonitor | Moves a workspace to a monitor | workspace and a monitor separated by a space |
| swapactiveworkspaces | Swaps the active workspaces between two monitors | two monitors separated by a space |
| bringactivetotop | _Deprecated_ in favor of alterzorder. Brings the current window to the top of the stack | none |
| alterzorder | Modify the window stack order of the active or specified window. Note: this cannot be used to move a floating window behind a tiled one. | zheight[,window] |
2022-11-27 23:45:15 +01:00
| togglespecialworkspace | toggles a special workspace on/off | none (for the first) or name for named (name has to be a special workspace's name) |
| focusurgentorlast | Focuses the urgent window or the last window | none |
| togglegroup | toggles the current active window into a group | none |
| changegroupactive | switches to the next window in a group. | b - back, f - forward, or index start at 1 |
| focuscurrentorlast | Switch focus from current to previously focused window | none |
| lockgroups | Locks the groups (all groups will not accept new windows) | `lock` for locking, `unlock` for unlocking, `toggle` for toggle |
| lockactivegroup | Lock the focused group (the current group will not accept new windows or be moved to other groups) | `lock` for locking, `unlock` for unlocking, `toggle` for toggle |
2023-02-26 14:57:09 +01:00
| moveintogroup | Moves the active window into a group in a specified direction. No-op if there is no group in the specified direction. | direction |
2024-02-17 23:44:40 +01:00
| moveoutofgroup | Moves the active window out of a group. No-op if not in a group | left empty / `active` for current, or `window` for a specific window |
2023-09-16 13:59:07 +02:00
| movewindoworgroup | Behaves as `moveintogroup` if there is a group in the given direction. Behaves as `moveoutofgroup` if there is no group in the given direction relative to the active group. Otherwise behaves like `movewindow`. | direction |
2023-07-13 17:56:21 +02:00
| movegroupwindow | Swaps the active window with the next or previous in a group | `b` for back, anything else for forward |
| denywindowfromgroup | Prohibit the active window from becoming or being inserted into group | `on`, `off` or, `toggle` |
| setignoregrouplock | Temporarily enable or disable binds:ignore_group_lock | `on`, `off`, or `toggle` |
2024-03-17 13:44:39 +01:00
| global | Executes a Global Shortcut using the GlobalShortcuts portal. See [here](../Binds/#global-keybinds) | name |
| submap | Change the current mapping group. See [Submaps](../Binds/#submaps) | `reset` or name |
2024-06-15 16:21:02 +02:00
| event | Emits a custom event to socket2 in the form of `custom>>yourdata` | the data to send |
{{< callout type=warning >}}
2022-09-24 15:32:40 +02:00
2024-07-30 21:59:15 +02:00
It is NOT recommended to set DPMS with a keybind directly, as it might cause
undefined behavior. Instead, consider something like
2022-09-24 15:32:40 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind = MOD, KEY, exec, sleep 1 && hyprctl dispatch dpms off
2022-09-24 15:32:40 +02:00
```
{{< /callout >}}
### Grouped (tabbed) windows
Hyprland allows you to make a group from the current active window with the
`togglegroup` bind dispatcher.
A group is like i3wms “tabbed” container. It takes the space of one window, and
you can change the window to the next one in the tabbed “group” with the
`changegroupactive` bind dispatcher.
The new groups border colors are configurable with the appropriate `col.`
settings in the `group` config section.
You can lock a group with the `lockactivegroup` dispatcher in order to stop new
windows from entering this group. In addition, the `lockgroups` dispatcher can be
used to toggle an independent global group lock that will prevent new windows
from entering any groups, regardless of their local group lock stat.
You can prevent a window from being added to a group or becoming a group with the
`denywindowfromgroup` dispatcher. `movewindoworgroup` will behave like
`movewindow` if the current active window or window in direction has this property
set.
## Workspaces
You have nine choices:
- ID: e.g. `1`, `2`, or `3`
- Relative ID: e.g. `+1`, `-3` or `+100`
2024-07-30 21:59:15 +02:00
- workspace on monitor, relative with `+` or `-`, absolute with `~`: e.g. `m+1`,
`m-2` or `m~3`
2024-07-30 21:59:15 +02:00
- workspace on monitor including empty workspaces, relative with `+` or `-`,
absolute with `~`: e.g. `r+1` or `r~3`
2024-07-30 21:59:15 +02:00
- open workspace, relative with `+` or `-`, absolute with `~`: e.g. `e+1`,
`e-10`, or `e~2`
- Name: e.g. `name:Web`, `name:Anime` or `name:Better anime`
- Previous workspace: `previous`, or `previous_per_monitor`
2024-07-30 21:59:15 +02:00
- First available empty workspace: `empty`, suffix with `m` to only search
on monitor. and/or `n` to make it the *next* available empty workspace. e.g.
`emptynm`
2022-11-27 23:45:15 +01:00
- Special Workspace: `special` or `special:name` for named special workspaces.
{{< callout type=warning >}}
`special` is supported ONLY on `movetoworkspace` and `movetoworkspacesilent`.
Any other dispatcher will result in undocumented behavior.
{{< /callout >}}
{{< callout >}}
Numerical workspaces (e.g. `1`, `2`, `13371337`) are allowed **ONLY** between 1
and 2147483647 (inclusive)
2022-11-10 13:17:08 +01:00
Neither `0` nor negative numbers are allowed.
{{< /callout >}}
## Special Workspace
2022-11-27 23:45:15 +01:00
A special workspace is what is called a "scratchpad" in some other places. A
workspace that you can toggle on/off on any monitor.
{{< callout type=info >}}
You can define multiple named special workspaces, but the amount of those is
limited to 97 at a time.
{{< /callout >}}
For example, to move a window/application to a special workspace you can use the
following syntax:
2024-07-30 21:59:15 +02:00
```ini
bind = SUPER, C, movetoworkspace, special
#The above syntax will move the window to a special workspace upon pressing 'SUPER'+'C'.
#To see the hidden window you can use the togglespecialworkspace dispatcher mentioned above.
```
## Executing with rules
The `exec` dispatcher supports adding rules. Please note some windows might work
2024-07-30 21:59:15 +02:00
better, some worse. It records the PID of the spawned process and uses that.
For example, if your process forks and then the fork opens a window, this will
not work. Rules will only be applied once. This means dynamic rules will be
overridden as soon as a property of the window changes (e.g. switching focus).
To make dynamic rules stick around use `hyprctl setprop` (see
[Using hyprctl](../Using-hyprctl)).
2022-11-10 14:41:48 +01:00
The syntax is:
2024-07-30 21:59:15 +02:00
```ini
2022-11-10 14:41:48 +01:00
bind = mod, key, exec, [rules...] command
```
For example:
2024-07-30 21:59:15 +02:00
```ini
bind = SUPER, E, exec, [workspace 2 silent; float; move 0 0] kitty
2022-11-10 14:41:48 +01:00
```