hyprland-wiki/pages/Configuring/Dispatchers.md

12 KiB
Raw Permalink Blame History

weight title
6 Dispatchers

Please keep in mind some layout-specific dispatchers will be listed in the layout pages (See the sidebar).

Parameter explanation

Param type Description
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
workspace see below.
direction l r u d left right up down
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
mod SUPER, SUPER_ALT, etc.
key g, code:42, 42 or mouse clicks (mouse:272)

List of Dispatchers

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
pass passes the key (with mods) to a specified window. Can be used as a workaround to global keybinds not working on Wayland. window
sendshortcut sends specified keys (with mods) to an optionally specified window. Can be used like pass mod, key[, window]
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
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
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)
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
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.
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
focuswindow focuses the first window matching window
focusmonitor focuses a monitor monitor
splitratio changes the split ratio floatvalue
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
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
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]
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
moveintogroup Moves the active window into a group in a specified direction. No-op if there is no group in the specified direction. direction
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
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
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
global Executes a Global Shortcut using the GlobalShortcuts portal. See here name
submap Change the current mapping group. See Submaps reset or name
event Emits a custom event to socket2 in the form of custom>>yourdata the data to send

{{< callout type=warning >}}

It is NOT recommended to set DPMS with a keybind directly, as it might cause undefined behavior. Instead, consider something like

bind = MOD, KEY, exec, sleep 1 && hyprctl dispatch dpms off

{{< /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

  • workspace on monitor, relative with + or -, absolute with ~: e.g. m+1, m-2 or m~3

  • workspace on monitor including empty workspaces, relative with + or -, absolute with ~: e.g. r+1 or r~3

  • 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

  • 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

  • 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)

Neither 0 nor negative numbers are allowed.

{{< /callout >}}

Special Workspace

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:

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 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).

The syntax is:

bind = mod, key, exec, [rules...] command

For example:

bind = SUPER, E, exec, [workspace 2 silent; float; move 0 0] kitty