labwc-actions(5)

📦
version 0.20.2 · 12 versions
, in arch rolling

🎀 labwc-actions(5) 🎀

bestie, this is the File Formats Manual page for labwc-actions(5), and it is literally the action cheat sheet. 💅

🌸 NAME 🌸

labwc - actions

✨ ACTIONS ✨

Actions are used in menus and keyboard/mouse bindings. periodt. 🫶

  • <action name="Close" /> — closes the top-most window. bye bestie 👋
  • <action name="Kill" /> — kills the process associated with the current window by sending it the SIGTERM signal. dramatic but necessary 💀
  • <action name="Execute" command="value" /> — executes command. Note that in the interest of backward compatibility, labwc supports <execute> as an alternative to <command> even though openbox documentation states that it is deprecated. Note: tilde (~) is expanded in the command before passing to execvp(). iconic little detail ✨
  • <action name="Exit" /> — exits labwc. closing time 🚪
  • <action name="Focus" /> — gives focus to the window under the cursor. 👀
  • <action name="Unfocus" /> — removes focus from the window that is currently focused. release the spotlight bestie 💅
  • <action name="Raise" /> — restacks the current window above other open windows. main character energy 👑
  • <action name="Lower" /> — restacks the current window below other open windows. humble era 🌸
  • <action name="Iconify" /> — iconifies (minimizes) the focused window. tiny nap time 😴
  • <action name="Move" /> — begins interactive move of the window under the cursor. grab and go 🫶
  • <action name="MoveToEdge" direction="value" snapWindows="value" /> — moves the window until it hits the next edge.
    • direction [left|up|right|down] — direction in which to move.
    • snapWindows [yes|no] — move window until it hits an edge of another window or screen edge. If set to "no", only move to the next screen edge. Default is yes.
  • <action name="Resize" direction="value" /> — begins interactive resize of the window under the cursor.
    • direction [up|down|left|right|up-left|up-right|down-left|down-right] — edge or corner from which to start resizing. If this is not provided, the direction is inferred from the cursor position.
  • <action name="ResizeRelative" left="" right="" top="" bottom="" /> — resizes the window relative to its current size. Values of left, right, top or bottom tell how much to resize on that edge of the window; positive values grow the window, negative values shrink the window.
Note that some applications like terminal emulators may refuse growing or shrinking by small amounts to keep the window size aligned to their internal cell size. tiny pixel perfectionist behavior 🍓
  • <action name="GrowToEdge" direction="value" /> — resizes the window to fill the space between its edge and any other window edge.
    • direction [left|up|right|down] — direction in which to grow.
  • <action name="ShrinkToEdge" direction="value" /> — reverse of GrowToEdge. Shrinks by a maximum of 50%.
    • direction [left|up|right|down] — direction in which to shrink.
  • <action name="MoveTo" x="" y="" /> — moves to position (x, y). coordinates bestie 📍
  • <action name="ResizeTo" width="" height="" /> — resizes the window.
    • width — the width to resize the window to in pixels.
    • height — the height to resize the window to in pixels.
  • <action name="MoveToCursor" /> — moves to be centered on the cursor. Tries to prevent any part of the window from going off-screen. This action is deprecated from v0.7.3. To ensure your config works in future labwc releases, please use:
<action name="AutoPlace" policy="cursor">
  • <action name="MoveRelative" x="" y="" /> — moves the window relative to its current position. Positive value of x moves it right, negative left. Positive value of y moves it down, negative up. slide to the left, slide to the right 🕺
  • <action name="ToggleSnapToEdge" direction="value" combine="value" /> — resizes the window to fill half or quarter the output in the given direction.
    • direction [up|down|left|right|up-left|up-right|down-left|down-right|center] — direction in which to snap the window.
    • combine [yes|no] — allows to snap a window to an output corner by combining two directions. For example, snapping a window to right and then to up places it in the up-right quarter of the output. Default is no.

ToggleSnapToEdge additionally toggles the active window between tiled to the given direction and its untiled position. toggling is the moment ✨

  • <action name="SnapToEdge" direction="value" combine="value" /> — resizes the window to fill half or quarter the output in the given direction.
    • direction [up|down|left|right|up-left|up-right|down-left|down-right|center] — direction in which to snap the window.
    • combine [yes|no] — allows to snap a window to an output corner by combining two directions. For example, snapping a window to right and then to up places it in the up-right quarter of the output. Default is no.
  • <action name="ToggleSnapToRegion" region="value" /> — resizes and moves the active window according to the given region.

ToggleSnapToRegion additionally toggles the active window between tiled to the given region and its untiled position.

See labwc-config(5) for further information on how to define regions. iykyk 🦋

  • <action name="SnapToRegion" region="value" /> — resizes and moves the active window according to the given region.

See labwc-config(5) for further information on how to define regions. 🦋

  • <action name="UnSnap" /> — resizes and moves the active window back to its untiled or unmaximized position if it had been maximized or tiled to a direction or region. reverse card, bestie 🃏
  • NextWindow, PreviousWindow, NextWindowImmediate, PreviousWindowImmediate — cycle focus to next/previous window, respectively. the group chat of window actions 💬
<action name="NextWindow" workspace="current" output="all"
identifier="all" />
<action name="PreviousWindow" workspace="current" output="all"
identifier="all" />
<action name="NextWindowImmediate" workspace="current" output="all"
identifier="all" />
<action name="PreviousWindowImmediate" workspace="current" output="all"
identifier="all" />
  • Default keybinds for NextWindow and PreviousWindow are Alt-Tab and Shift-Alt-Tab. While cycling through windows, the arrow keys move the selected window forwards/backwards and the escape key halts the cycling. ⬅️➡️
  • NextWindowImmediate and PreviousWindowImmediate skip the Window Switcher and OSD, useful for binding to keys without modifiers.
  • workspace [all|current] — this determines whether to cycle through windows on all workspaces or the current workspace. Default is "current".
  • output [all|focused|cursor] — this determines whether to cycle through windows on all outputs, the focused output, or the output under the cursor. Default is "all".
  • identifier [all|current] — this determines whether to cycle through all windows or only windows of the same application as the currently focused window. Default is "all".
  • <action name="Reconfigure" /> — re-loads configuration and theme files. refresh era 🔄
  • <action name="ShowMenu" menu="root-menu" /> — shows a menu. menu moment fr 🍓
<action name="ShowMenu" menu="MENU">
  <atCursor>yes|no</atCursor>
  <position>
    <x>X</x>
    <y>Y</y>
  </position>
</action>
  • menu — the name of the menu to show. The menus "root-menu", "client-menu", "client-send-to-menu" and "client-list-combined-menu" are guaranteed to exist, but others may be defined explicitly. See labwc-menu(5) for more information.
  • atCursor [yes|no] — when opening a menu, open the menu at the location of the mouse cursor. When set to no, the menu will appear at the upper-left corner of the window associated with the action or underneath the window button that opened the menu. Default is yes.
  • position — show the menu in the specified position on the monitor that has cursor focus, see below.

The position tag has two sub-tags. <x> and <y> specify a position and take either a pixel value, the string "center" which will center the menu in that dimension, or a relative value specified as a percentage. A relative value is interpreted in terms of the monitor the menu will be shown on, and will be relative to the left/top edge of the menu window and monitor for positive values, and to the right/bottom edge for negative values.

The example below demonstrates how the root-menu can be opened from a bottom aligned panel using the command wtype -M logo -k Space:

<keybind key="W-Space">
  <action name="ShowMenu">
  <menu>root-menu</menu>
  <position>
    <x>0</x>
    <y>-0</y>
  </position>
  </action>
</keybind>
  • <action name="SetDecorations" decorations="value" forceSSD="no" /> — sets decorations of the focused window.
    • decorations [full|border|none] — full enables the whole server side decorations. With border, only the borders and invisible resize area are enabled. none disables everything.
    • forceSSD [yes|no] — if this is no, this action will be ignored for windows that have client side decorations if it would increase the amount of decoration. Default is no.
  • <action name="ToggleDecorations" /> — toggles decorations of the focused window.

This is a 3-state action which can be executed multiple times:

  • Only the titlebar will be hidden, borders and resize area are kept
  • Remaining decorations will be disabled
  • Decorations will be shown normally

By disabling the theme configuration keepBorder the first step will be removed and the action only toggles between on and off. three-state slay 💅

  • <action name="ToggleFullscreen" /> — toggles fullscreen state of the focused window. big screen energy 🔥
  • <action name="ToggleMaximize" direction="value" /> — toggles maximize state of the focused window. Supported directions are "both" (default), "horizontal", and "vertical".
  • <action name="Maximize" direction="value" /> — maximizes the focused window in the direction(s) specified. Supported directions are "both" (default), "horizontal", and "vertical".
  • <action name="UnMaximize" direction="value" /> — unmaximizes the focused window in the direction(s) specified and returns it to its pre-maximized dimensions. Supported directions are "both" (default), "horizontal", and "vertical".
  • <action name="ToggleAlwaysOnTop" /> — toggles always-on-top of the focused window. stay on top, no cap 👑
  • <action name="ToggleAlwaysOnBottom" /> — toggles between layers always-on-bottom and normal. When a window is in the always-on-bottom layer, it is rendered below all other top-level windows. It is anticipated that this action will be useful when defining window-rules for desktop-management tools that do not support the wlr-layer-shell protocol. bottom layer bestie 🫶
  • <action name="ToggleOmnipresent" /> — toggles omnipresent (visible on all workspaces / sticky) for the focused window. everywhere all at once ✨
  • <action name="ToggleKeybinds" /> — stops handling keybinds/mousebinds other than ToggleKeybinds itself. This can be used to allow A-Tab and similar keybinds/mousebinds to be delivered to Virtual Machines, VNC clients or nested compositors. A second call will restore all original keybinds/mousebinds.

This action will only affect the window that had keyboard focus when the binding was executed. Thus when switching to another window, all the usual keybinds will function again until switching back to the original window. There can be multiple windows with this mode set. keybind custody battle, but make it cute 💀

<action name="ToggleTearing" />

Toggles tearing for the focused window, flipping it between enabled and disabled. This overrides the preference (the tearing hint) that comes from the focused window itself, so it's you calling the shots 💅

Needs the config option allowTearing to be on, otherwise this does nothing. And when allowTearing is set to fullscreen or fullscreenForced, tearing will still only be enabled if the active window is in fullscreen mode — no sneaky windowed tearing, bestie.

<action name="FocusOutput" output="HDMI-A-1" direction="value" wrap="no" />

Gives focus to the topmost window on another output, and warps the cursor to the center of that window. Very "take me to the other screen" energy 🦋

  • output — if you specify it, focus goes to that exact output and direction is just ignored, like, completely.
  • direction — if output is omitted, this can be one of "left", "right", "up" or "down", meaning focus should go to the next output in that direction (if one even exists 👀).
  • wrap [yes|no] — when you're using the direction attribute, wrap around from right-to-left or top-to-bottom, and vice versa. Default is no.

If the target output doesn't contain any windows, the cursor will just be centered on the output. Iconic, minimal, still works 🎀

<action name="MoveToOutput" output="HDMI-A-1" direction="value" wrap="no" />

Moves the active window to another output — unless the window state is fullscreen, in which case, nope, it stays put 🫶

  • output — if specified, the window gets sent straight to that output and direction is ignored.
  • direction — if output is omitted, it may be one of "left", "right", "up" or "down", meaning the window should be moved to the next output in that direction (if one exists).
  • wrap [yes|no] — when using the direction attribute, wrap around from right-to-left or top-to-bottom, and vice versa. Default is no.

<action name="FitToOutput" />

Resizes the active window's size to the width and height of the output — but only when the window size exceeds the output size. So it's a "you're too big for this screen, bestie, sit down" action 😭✨

<action name="GoToDesktop" to="value" wrap="yes" toggle="no" />

Switches to a workspace. The classic. The main character move 👑

  • to — the workspace to switch to. Supported values are "current", "last", "left", "right", "left-occupied", "right-occupied", or the full name of a workspace, or its index (starting at 1) as configured in rc.xml.
  • wrap [yes|no] — wrap around from last desktop to first, and vice versa. Default is yes.
  • toggle [yes|no] — toggles to “last” if you're already on the workspace that would be the actual destination. Default is no.

<action name="SendToDesktop" to="value" follow="yes" wrap="yes" />

Sends the active window to a workspace. Not you moving — the window moving. Big difference 💅

  • to — the workspace to send the window to. Supported values are the same as for GoToDesktop.
  • follow [yes|no] — also switch to the specified workspace. Default is yes.
  • wrap [yes|no] — wrap around from last desktop to first, and vice versa. Default is yes.

<action name="VirtualOutputAdd" output_name="value" />

Adds a virtual output (headless backend). Okay this one is lowkey the coolest thing on the whole page, stay with me 🧚

For example, it can be used to overlay a virtual output on a real output, but with a different resolution (this can be done with wlr-randr or wdisplays). After that, the virtual output can be selected for screen sharing (casting), effectively sharing only that region of the screen. Selective sharing, we love to see it 🌈

It must be noted that overlaying a virtual output and a real output is not endorsed or explicitly supported by wlroots. For example, after configuring the virtual output, the real output must be reconfigured as well (for the overlay configuration to work correctly). This is the example configuration:
<keybind key="W-v">
  <action name="VirtualOutputAdd" output_name="ScreenCasting" />
  <action name="Execute" command='sh -c "wlr-randr --output ScreenCasting --pos 0,0 --scale 2 --custom-mode 3840x2110; wlr-randr --output eDP-1 --pos 0,0 --scale 2 --mode 3840x2160"' />
</keybind>
<keybind key="W-c">
  <action name="VirtualOutputRemove" />
</keybind>

Note that the vertical resolution of "ScreenCasting" output is just 50px smaller than "eDP-1" output, to cut off the bottom panel from screen sharing. Tiny difference, huge payoff 🔥

Virtual output is also useful for extending the desktop to (maybe mobile) remote systems like tablets. E.g. simply adding a virtual output, attaching wayvnc to it and running a VNC client on the remote system. Tablet second-screen era 🫶

  • output_name — the name of the virtual output. Providing a virtual output name is beneficial for further automation. Default is "HEADLESS-X".

<action name="VirtualOutputRemove" output_name="value" />

Removes a virtual output (headless backend). Bye bestie 👋

  • output_name — the name of the virtual output. If not supplied, it will remove the last virtual output added.

<action name="AutoPlace" policy="value" />

Repositions the window according to the placement policy you want. You're the placement director now 🎬

  • policy [automatic|cursor|center|cascade] — use the specified policy, which has the same meaning as the corresponding value for <placement><policy>. Default is automatic.

<action name="Shade" />

<action name="Unshade" />

<action name="ToggleShade" />

Set, unset, or toggle, respectively, the "shaded" state of the active window. When shaded, the window contents are hidden, leaving only the titlebar visible — like rolling up a lil window blind, hence the name, iykyk 🎀

Full-screen windows, or those without server-side decorations (including those for which the server-side titlebar has been hidden), are not eligible for shading. Sorry, no shading for you 💀

<action name="WarpCursor" to="output" x="center" y="center" />

Warps the cursor to a position relative to the active output or window. Teleportation but make it a keybind ✨

  • to [output|window] — specifies the target area of the warp. Default is "output".
  • x [center|value] — specifies the horizontal warp position within the target area. "center": moves the cursor to the horizontal center of the target area. Positive or negative integers warp the cursor to a position offset by the specified number of pixels from the left or right edge of the target area, respectively. Default is "center".
  • y [center|value] — the equivalent for the vertical warp position within the target area. Default is "center".

<action name="HideCursor" />

Hides the pointer or stylus cursor. The cursor becomes visible again on following pointer actions, stylus actions or touchpad gestures — so it's not gone forever, it's just shy 🙈

Use together with the WarpCursor action to not just hide the cursor but to additionally move it away, to prevent e.g. hover effects. Chef's kiss combo 🍓

<action name="EnableScrollWheelEmulation" />

<action name="DisableScrollWheelEmulation" />

<action name="ToggleScrollWheelEmulation">

Enable, disable or toggle scroll wheel emulation on cursor motion, respectively. This can be useful for trackball mouses, to use the rotating ball not just for moving the cursor, but also for (mouse wheel) scrolling. Trackball girlies, this one's for you 🫶

See also <libinput><scrollFactor> in labwc-config(5) for fine tuning the scroll speed.

<action name="EnableTabletMouseEmulation" />

<action name="DisableTabletMouseEmulation" />

<action name="ToggleTabletMouseEmulation">

Enable, disable or toggle mouse emulation for drawing tablets, respectively. Drawing tablet? Living its best mouse life 💜

<action name="ToggleMagnify">

Toggles the screen magnifier on or off at the last magnification level used. Picks up right where you left off, respectful queen 👑

<action name="ToggleShowDesktop" />

Minimizes all windows in the current workspace so that the desktop becomes visible. On calling the action again, the hidden windows are unminimized — provided that, since the initial ShowDesktop:

  • (a) no windows have been unminimized;
  • (b) workspaces have not been switched; and
  • (c) no new applications have been started.

Break any of those and it's not going back to how it was, bestie 😭

<action name="ZoomIn">

<action name="ZoomOut">

Increase or decrease the magnification level for the screen magnifier. If the magnifier is currently off, ZoomIn will enable it at the lowest magnification, equal to (1 + the magnifier increment set in the theme). If the magnifier is on and at the lowest magnification, ZoomOut will turn it off. Round and round we go 🌸

<action name="None" />

If used as the only action for a binding: clears an earlier defined binding. The polite way to say "never mind" 💅

<action name="DebugToggleKeyStateIndicator" />

Toggles visibility of the key-state on-screen display (OSD).

Note: this is for debugging purposes only. It's giving developer tools, not lifestyle 🌈

🎀 CONDITIONAL ACTIONS 🎀

Okay so these are the boss-level actions: actions that run other actions. Meta, right? You use them inside keyboard/mouse bindings. It's giving "if this then that" but make it window manager 💅

🦋 <action name="If">

This is the big one. It runs one set of actions if the focused window matches your criteria, and a totally different set if it doesn't. Like a vibe check for your window, bestie.

The arguments are as follows:

<action name="If">
  <query />
  <prompt message="" />
  <then><action /></then>
  <else><action /></else>
</action>

🌸 query

Defines a query with zero or more conditions. All conditions have to evaluate as true for the window to match this query — no partial credit, it's all or nothing. You can define multiple queries, too.

Pattern matching goes according to glob(7) and is case-insensitive. Slay.

The conditions are as follows:

  • identifier — the XDG shell app_id for Wayland clients, or WM_CLASS for XWayland clients.
  • title — the XDG shell title for Wayland clients, or WM_NAME for XWayland clients.
  • type — internal heuristics for Wayland clients, NET_WM_WINDOW_TYPE for XWayland clients.
  • shaded [yes|no] — whether or not the client is rolled up.
  • maximized [both|horizontal|vertical|none] — whether the client is maximized along both axes, just the horizontal axis, just the vertical axis, or neither axis (none).
  • iconified [yes|no] — whether or not the client is iconified.
  • focused [yes|no] — whether or not the client is focused.
  • omnipresent [yes|no] — whether or not the client is visible on all desktops.
  • desktop — the desktop the client is currently on. This can be the number or name of a desktop, or the special relative values "current", "other", "left", "right", "left-occupied", "right-occupied" or "last". Heads up: the "left", "right", "left-occupied" and "right-occupied" directions will not wrap. No looping around, bestie 🫶
  • tiled [up|right|down|left|up-left|up-right|down-left|down-right|center|any] — whether the client is tiled (snapped) along the indicated screen edge.
  • tiled_region — whether the client is tiled (snapped) to the indicated region. And the indicated region may be a glob, so go wild ✨
  • decoration [full|border|none] — whether the client has full server-side decorations, borders only, or no server-side decorations at all.
  • monitor [current|left|right|<monitor_name>] — whether the client is on a monitor relative to the currently focused monitor (current, left, or right), or on a monitor with the supplied <monitor_name>.

This argument is optional. 💫

🎀 prompt

Displays a yes/no prompt dialog (labnag by default). If "yes" is selected, the then branch gets taken; same deal with "no" and else. This argument is optional.

Okay important lore: the syntax here is different to Openbox, where a prompt element isn't tied to If-actions but would just be a child of the downstream action. The reason for the difference is increased flexibility and functionality, gained by optionally using an else branch. iykyk 😌
<keybind key="W-q">
  <action name="If">
    <prompt message="Quit?" />
    <then>
      <action name="Exit" />
    </then>
  </action>
</keybind>

💖 then

A list of actions to be executed if the window matches any query. This argument is optional.

💜 else

A list of actions to be executed if the window does not match any query. This argument is optional.

🌈 <action name="ForEach">

Literally identical to the "If" action, except it applies to all windows, not just the focused one. Main character energy for your entire window list 👑

The ForEach action has another optional none branch which gets executed when no window has been matched by the query. This lets you do things like implement run-or-raise functionality. No cap, that's a genuinely iconic use case 🚀

⭐ SEE ALSO ⭐

labwc(1), labwc-config(5), labwc-theme(5), glob(7)

That's the whole page, bestie — you made it to the end 🎉 This was labwc-actions(5) from 2026-08-22, and honestly? She ate. Go forth and bind your keys with confidence 💅✨🦋

📦 where this page comes from