Dispatchers

Dispatchers

Dispatchers return tables that describe an action you want to make. They do not invoke any action immediately, and their contents are not guaranteed to be stable at all. Their purpose is to be fed into hl.bind() or hl.dispatch().

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

To use a dispatcher (any of hl.dsp.*) inside a function, you need to wrap it in hl.dispatch() for it to be executed. Simply writing hl.dsp.whatever() on its own will do nothing.

hl.bind("ALT + Tab", function()
    hl.dispatch(hl.dsp.window.cycle_next())
    hl.dispatch(hl.dsp.window.bring_to_top())
end)

hl.bind("ALT + Tab", function()
    hl.dsp.window.cycle_next()
    hl.dsp.window.bring_to_top()
end)

Parameter explanation

Dispatchers

General

hl.dsp. contains:

hl.bind("...", function()
    hl.timer(function()
        hl.dispatch(hl.dsp.dpms({ action = "disable" }))
    end, {timeout = 500, type = "oneshot"})
end)

Window

hl.dsp.window. contains:

Workspace

hl.dsp.workspace. contains:

Group

hl.dsp.group. contains:

Cursor

hl.dsp.cursor. contains:

Grouped (tabbed) windows

Hyprland allows you to make a group from the current active window with the hl.dsp.group.toggle() bind dispatcher.

A group is like i3wm’s “tabbed” container. It takes the space of one window, and you can toggle the windows within it.

You can lock a group with the lock dispatcher in order to stop new windows from entering this group.

You can prevent a window from being added to a group or becoming a group with the window.deny_from_group dispatcher.

Special workspaces

A special workspace is what is called a “scratchpad” in some other places. It is a workspace that you can toggle on/off on any monitor.

For example, to move a window to a named special workspace you can use the following syntax:

hl.bind("SUPER + SHIFT + S", hl.dsp.window.move({ workspace = "special:magic" }))
-- Show/hide the workspace, and any windows on it:
hl.bind("SUPER + S", hl.dsp.workspace.toggle_special("magic"))

Executing with rules

The exec_cmd 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.

hl.bind("SUPER + E", hl.dsp.exec_cmd("kitty", { float = true, move = {0, 0} }))

set_prop

Props are any of the dynamic effects of Window Rules.

For example:

hl.dsp.window.set_prop({ prop = "no_anim", value = "1" })
hl.dsp.window.set_prop({ prop = "no_anim", value = "1", window = "class:abc" })

Some props are read-only, and take their values ether from window rules, or if no rules match, fall back to other relevant (writable) props according to window state:

• border_color: set from active_border_color, inactive_border_color
• opacity: set from opacity, opacity_inactive, opacity_fullscreen, opacity_override, opacity_inactive_override, opacity_fullscreen_override

fullscreen_state

The fullscreen_state dispatcher decouples the state that Hyprland maintains for a window from the fullscreen state that is communicated to the client.

internal is a reference to the state maintained by Hyprland. client is a reference to the state that the application receives.

For example:

• {internal = 2, client = 0} fullscreens the application but pretends to the client that it is still in non-fullscreen mode. This can be useful to prevent Chromium-based browsers from going into presentation mode when they detect they have been fullscreened.
• {internal = 0, client = 2} keeps the window non-fullscreen, but pretends to the client that is is now in fullscreen mode.

Restore client maximized state

This is not a user accessible mode, but a state that occurs when a client requests fullscreen when the internal mode of that window is maximized.

When this happens, the next request to un-fullscreen the window will cause the window to become maximized instead. A practical example of this is when you fullscreen a video you’re watching on a maximized window.

Fullscreen Handlers

Some layouts, like scrolling, provide their own fullscreen handling that overrides the default.

You can use both layout-handled and default-handled fullscreen modes in these layouts, via the layout_aware option in fullscreen dispatchers.

Lua code can see which fullscreen handler a given window is using. For example:

local win = hl.get_active_window()
if win.fullscreen_handler == "default" then
    -- do stuff
end