.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "labwc-actions" "5" "2024-12-26"
.PP
.SH NAME
.PP
labwc - actions
.PP
.SH ACTIONS
.PP
Actions are used in menus and keyboard/mouse bindings.\&
.PP
\fB<action name="Close" />\fR
.RS 4
Close top-most window.\&
.PP
.RE
\fB<action name="Kill" />\fR
.RS 4
Kill the process associated with the current window by sending it the
SIGTERM signal.\&
.PP
.RE
\fB<action name="Execute" command="value" />\fR
.RS 4
Execute 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().\&
.PP
.RE
\fB<action name="Exit" />\fR
.RS 4
Exit labwc.\&
.PP
.RE
\fB<action name="Focus" />\fR
.RS 4
Give focus to window under cursor.\&
.PP
.RE
\fB<action name="Unfocus" />\fR
.RS 4
Remove focus from the window that is currently focused.\&
.PP
.RE
\fB<action name="Raise" />\fR
.RS 4
Restack the current window above other open windows.\&
.PP
.RE
\fB<action name="Lower" />\fR
.RS 4
Restack the current window below other open windows.\&
.PP
.RE
\fB<action name="Iconify" />\fR
.RS 4
Iconify (minimize) focused window.\&
.PP
.RE
\fB<action name="Move" />\fR
.RS 4
Begin interactive move of window under cursor.\&
.PP
.RE
\fB<action name="MoveToEdge" direction="value" snapWindows="value" />\fR
.RS 4
Move window until it hits the next edge.\&
.PP
\fBdirection\fR [left|up|right|down] Direction in which to move.\&
.PP
\fBsnapWindows\fR [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.\&
.PP
.RE
\fB<action name="Resize" />\fR
.RS 4
Begin interactive resize of window under cursor.\&
.PP
.RE
\fB<action name="ResizeRelative" left="" right="" top="" bottom="" />\fR
.RS 4
Resize window relative to its current size.\& Values of left, right,
top or bottom tell how much to resize on that edge of window,
positive values grow window, negative shrink window.\&
.PP
.RE
\fB<action name="GrowToEdge" direction="value" />\fR
.RS 4
Resize window to fill the space between its edge and any other
window edge.\&
.PP
\fBdirection\fR [left|up|right|down] Direction in which to grow.\&
.PP
.RE
\fB<action name="ShrinkToEdge" direction="value" />\fR
.RS 4
Reverse of GrowToEdge.\& Shrinks by a maximum of 50%.\&
.PP
\fBdirection\fR [left|up|right|down] Direction in which to shrink.\&
.PP
.RE
\fB<action name="MoveTo" x="" y="" />\fR
.RS 4
Move to position (x, y).\&
.PP
.RE
\fB<action name="ResizeTo" width="" height="" />\fR
.RS 4
Resize window.\&
.PP
\fBwidth\fR The width to resize the window to in pixels.\&
.PP
\fBheight\fR The height to resize the window to in pixels.\&
.PP
.RE
\fB<action name="MoveToCursor" />\fR
.RS 4
Move to be centered on 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:
\fB<action name="AutoPlace" policy="cursor">\fR
.PP
.RE
\fB<action name="MoveRelative" x="" y="" />\fR
.RS 4
Move window relative to its current position.\& Positive value of x moves
it right, negative left.\& Positive value of y moves it down, negative up.\&
.PP
.RE
\fB<action name="ToggleSnapToEdge" direction="value" />\fR
.br
\fB<action name="SnapToEdge" direction="value" />\fR
.RS 4
Resize window to fill half the output in the given direction.\& Supports
directions "left", "up", "right", "down" and "center".\&
.PP
ToggleSnapToEdge additionally toggles the active window between
tiled to the given direction and its untiled position.\&
.PP
.RE
\fB<action name="ToggleSnapToRegion" region="value" />\fR
.br
\fB<action name="SnapToRegion" region="value" />\fR
.RS 4
Resize and move active window according to the given region.\&
.PP
ToggleSnapToRegion additionally toggles the active window between
tiled to the given region and its untiled position.\&
.PP
See labwc-config(5) for further information on how to define regions.\&
.PP
.RE
\fB<action name="UnSnap" />\fR
.RS 4
Resize and move the active window back to its untiled or unmaximized
position if it had been maximized or tiled to a direction or region.\&
.PP
.RE
\fB<action name="NextWindow" />\fR
.br
\fB<action name="PreviousWindow" />\fR
.RS 4
Cycle focus to next/previous window respectively.\&
.br
	Default keybind for NextWindow is Alt-Tab.\&
.PP
The shift key is used to reverse direction while cycling.\&
.PP
The arrow keys are used to move forwards/backwards while cycling.\&
.PP
.RE
\fB<action name="Reconfigure" />\fR
.RS 4
Re-load configuration and theme files.\&
.PP
.RE
\fB<action name="ShowMenu" menu="value" atCursor="yes" />\fR
.RS 4
Show a menu.\&
.PP
\fBmenu\fR 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.\&
.PP
\fBatCursor\fR [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.\&
.PP
\fBposition\fR Show the menu in the specified position on the monitor
that has cursor focus, see below.\&
.PP
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.\&
.PP
.RE
\fB<action name="SetDecorations" decorations="value" forceSSD="no" />\fR
.RS 4
Set decorations of focused window.\&
.PP
\fBdecorations\fR [full|border|none] \fBfull\fR enables the whole server side
decorations.\& With \fBborder\fR.\& only the borders and invisible resize area
are enabled.\& \fBnone\fR disables everything.\&
.PP
\fBforceSSD\fR [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.\&
.PP
.RE
\fB<action name="ToggleDecorations" />\fR
.RS 4
Toggle decorations of focused window.\&
.PP
This is a 3-state action which can be executed multiple times:
.PD 0
.IP \(bu 4
Only the titlebar will be hidden, borders and resize area are kept
.IP \(bu 4
Remaining decorations will be disabled
.IP \(bu 4
Decorations will be shown normally
.PD
.PP
By disabling the theme configuration '\&keepBorder'\& the first step
will be removed and the action only toggles between on and off.\&
.PP
.RE
\fB<action name="ToggleFullscreen" />\fR
.RS 4
Toggle fullscreen state of focused window.\&
.PP
.RE
\fB<action name="ToggleMaximize" direction="value" />\fR
.RS 4
Toggle maximize state of focused window.\& Supported directions are
"both" (default), "horizontal", and "vertical".\&
.PP
.RE
\fB<action name="Maximize" direction="value" />\fR
.RS 4
Maximize focused window in the direction(s) specified.\& Supported
directions are "both" (default), "horizontal", and "vertical".\&
.PP
.RE
\fB<action name="UnMaximize" direction="value" />\fR
.RS 4
Unmaximize focused window in the direction(s) specified and return it to
its pre-maximized dimensions.\& Supported directions are "both" (default),
"horizontal", and "vertical".\&
.PP
.RE
\fB<action name="ToggleAlwaysOnTop" />\fR
.RS 4
Toggle always-on-top of focused window.\&
.PP
.RE
\fB<action name="ToggleAlwaysOnBottom" />\fR
.RS 4
Toggle 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.\&
.PP
.RE
\fB<action name="ToggleOmnipresent" />\fR
.RS 4
Toggle omnipresent (visible on all workspaces / sticky) for the focused
window.\&
.PP
.RE
\fB<action name="ToggleKeybinds" />\fR
.RS 4
Stop handling keybinds other than ToggleKeybinds itself.\&
This can be used to allow A-Tab and similar keybinds to be delivered
to Virtual Machines, VNC clients or nested compositors.\&
A second call will restore all original keybinds.\&
.PP
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.\&
.PP
.RE
\fB<action name="ToggleTearing" />\fR
.RS 4
Toggles tearing for the focused window between enabled and disabled.\&
This overrides the preference (tearing hint) from the focused window.\&
.PP
Requires the config option '\&allowTearing'\&.\& When '\&allowTearing'\& is set
to '\&fullscreen'\& or '\&fullscreenForced'\&, tearing will still only be
enabled if the active window is in fullscreen mode.\&
.PP
.RE
\fB<action name="FocusOutput" output="HDMI-A-1" direction="value" wrap="no" />\fR
.RS 4
Give focus to topmost window on other output and warp the cursor
to the center of the window.\&
.PP
If \fBoutput\fR is specified, the focus is given to the specified output and
\fBdirection\fR is ignored.\& If \fBoutput\fR is omitted, \fBdirection\fR may be one
of "left", "right", "up" or "down" to indicate that the focus should be
given to the next output in that direction (if one exists).\&
.PP
\fBwrap\fR [yes|no] When using the direction attribute, wrap around
from right-to-left or top-to-bottom, and vice versa.\& Default is no.\&
.PP
If the target output does not contain any windows, the cursor will
be centered on the output.\&
.PP
.RE
\fB<action name="MoveToOutput" output="HDMI-A-1" direction="value" wrap="no" />\fR
.RS 4
Moves active window to other output, unless the window state is
fullscreen.\&
.PP
If \fBoutput\fR is specified, the window will be sent directly to the
specified output and \fBdirection\fR is ignored.\& If \fBoutput\fR is omitted,
\fBdirection\fR may be one of "left", "right", "up" or "down" to indicate
that the window should be moved to the next output in that direction
(if one exists).\&
.PP
\fBwrap\fR [yes|no] When using the direction attribute, wrap around from
right-to-left or top-to-bottom, and vice versa.\& Default no.\&
.PP
.RE
\fB<action name="FitToOutput" />\fR
.RS 4
Resizes active window size to width and height of the output when the
window size exceeds the output size.\&
.PP
.RE
\fB<action name="GoToDesktop" to="value" wrap="yes" />\fR
.RS 4
Switch to workspace.\&
.PP
\fBto\fR The workspace to switch to.\& Supported values are "current", "last",
"left", "right" or the full name of a workspace or its index (starting
at 1) as configured in rc.\&xml.\&
.PP
\fBwrap\fR [yes|no] Wrap around from last desktop to first, and vice
versa.\& Default yes.\&
.PP
.RE
\fB<action name="SendToDesktop" to="value" follow="yes" wrap="yes" />\fR
.RS 4
Send active window to workspace.\&
.PP
\fBto\fR The workspace to send the window to.\& Supported values are the same
as for GoToDesktop.\&
.PP
\fBfollow\fR [yes|no] Also switch to the specified workspace.\& Default yes.\&
.PP
\fBwrap\fR [yes|no] Wrap around from last desktop to first, and vice
versa.\& Default yes.\&
.PP
.RE
\fB<action name="VirtualOutputAdd" output_name="value" />\fR
.RS 4
Add virtual output (headless backend).\&
.PP
For example, it can be used to overlay virtual output on real output,
but with a different resolution (this can be done with `wlr-randr`
or `wdisplays`).\& After that, virtual output can be selected for screen
sharing (casting), effectively sharing only the region of the screen.\&
.PP
It must be noted that overlaying virtual output and real output is not
endorsed or explicitly supported by wlroots.\& For example, after
configuring virtual output, real output must be reconfigured as well
(for the overlay configuration to work correctly).\& This is the example
configuration:
.PP
.RE
.nf
.RS 4
<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>
.fi
.RE
.PP
.RS 4
Note that the vertical resolution of "ScreenCasting" output is just 50px
smaller than "eDP-1" output to cut off bottom panel from screen sharing.\&
.PP
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.\&
.PP
\fBoutput_name\fR The name of virtual output.\& Providing virtual output name
is beneficial for further automation.\& Default is "HEADLESS-X".\&
.PP
.RE
\fB<action name="VirtualOutputRemove" output_name="value" />\fR
.RS 4
Remove virtual output (headless backend).\&
.PP
\fBoutput_name\fR The name of virtual output.\& If not supplied, will remove
the last virtual output added.\&
.PP
.RE
\fB<action name="AutoPlace" policy="value"/>\fR
.RS 4
Reposition the window according to the desired placement policy.\&
.PP
\fBpolicy\fR [automatic|cursor|center|cascade] Use the specified policy,
which has the same meaning as the corresponding value for
\fB<placement><policy>\fR.\& Default is automatic.\&
.PP
.RE
\fB<action name="Shade" />\fR
.br
\fB<action name="Unshade" />\fR
.br
\fB<action name="ToggleShade" />\fR
.RS 4
Set, unset, or toggle, respectively, the "shaded" state of the active
window.\& When shaded, window contents are hidden, leaving only the
titlebar visible.\& 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.\&
.PP
.RE
\fB<action name="EnableTabletMouseEmulation" />\fR
.br
\fB<action name="DisableTabletMouseEmulation" />\fR
.br
\fB<action name="ToggleTabletMouseEmulation">\fR
.RS 4
Enable, disable or toggle mouse emulation for drawing tablets respectively.\&
.PP
.RE
\fB<action name="ToggleMagnify">\fR
.RS 4
Toggle the screen magnifier on or off at the last magnification level
used.\&
.PP
.RE
\fB<action name="ZoomIn">\fR
.br
\fB<action name="ZoomOut">\fR
.RS 4
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.\&
.PP
.RE
\fB<action name="None" />\fR
.RS 4
If used as the only action for a binding: clear an earlier defined
binding.\&
.PP
.RE
.SH CONDITIONAL ACTIONS
.PP
Actions that execute other actions.\& Used in keyboard/mouse bindings.\&
.PP
\fB<action name="If">\fR
.RS 4
This action will execute one set of actions if the focused window
matches the criteria, or another if it does not.\&
.PP
The arguments are as follows:
.PP
.nf
.RS 4
<action name="If">
  <query/>
  <then><action/></then>
  <else><action/></else>
</action>
.fi
.RE
.PP
\fBquery\fR
.RS 4
Define a query with zero or more conditions.\& All conditions must
be evaluated as true in order for the window to match this
query.\& Multiple queries can be defined.\&
.PP
Pattern matching is done according to glob(7) and is
case-insensitive.\&
.PP
Conditions are as follows:
.PP
\fBidentifier\fR
.RS 4
XDG shell app_id for Wayland clients, WM_CLASS for
XWayland clients.\&
.PP
.RE
\fBtitle\fR
.RS 4
XDG shell title for Wayland clients, WM_NAME for
XWayland clients.\&
.PP
.RE
\fBtype\fR
.RS 4
Internal heuristics for Wayland clients,
NET_WM_WINDOW_TYPE for XWayland clients.\&
.PP
.RE
\fBshaded\fR [yes|no]
.RS 4
Whether or not the client is rolled up.\&
.PP
.RE
\fBmaximized\fR [both|horizontal|vertical|none]
.RS 4
Whether the client is maximized along both axes, the
horizontal axis only, the vertical axis only, or neither
axis (none).\&
.PP
.RE
\fBiconified\fR [yes|no]
.RS 4
Whether or not the client is iconified.\&
.PP
.RE
\fBfocused\fR [yes|no]
.RS 4
Whether or not the client is focused.\&
.PP
.RE
\fBomnipresent\fR [yes|no]
.RS 4
Whether or not the client is visible on all desktops.\&
.PP
.RE
\fBdesktop\fR
.RS 4
The desktop the client is currently on.\& This can be the
number or name of a desktop, or special relative values
"current", "other", "left", "right" or "last".\& The
"left" and "right" directions will not wrap.\&
.PP
.RE
\fBtiled\fR [up|right|down|left|center]
.RS 4
Whether the client is tiled (snapped) along the the
indicated screen edge.\&
.PP
.RE
\fBtiled_region\fR
.RS 4
Whether the client is tiled (snapped) to the indicated
region.\& The indicated region may be a glob.\&
.PP
.RE
\fBdecoration\fR [full|border|none]
.RS 4
Whether the client has full server-side decorations,
borders only, or no server-side decorations.\&
.PP
.RE
This argument is optional.\&
.PP
.RE
\fBthen\fR
.RS 4
A list of actions to be executed if the window matches any
query.\& This argument is optional.\&
.PP
.RE
\fBelse\fR
.RS 4
A list of actions to be executed if the window does not match
any query.\& This argument is optional.\&
.PP
.RE
.RE
\fB<action name="ForEach">\fR
.RS 4
Identical to "If" action, but applies to all windows, not just the
focused one.\&
.PP
The \fBForEach\fR action has another optional \fBnone\fR branch which gets
executed when no window has been matched by the query.\& This allows
for example to implement a run-or-raise functionality.\&
.PP
.RE
.SH SEE ALSO
.PP
labwc(1), labwc-config(5), labwc-theme(5), glob(7)