.\" 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-05-11"
.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.\&
.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="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
.RE
\fB<action name="SnapToRegion" region="value" />\fR
.RS 4
Resize and move active window according to the given region.\&
See labwc-config(5) for further information on how to define regions.\&
.PP
.RE
\fB<action name="NextWindow" />\fR
.RS 4
Cycle focus to next window.\&
.PP
.RE
\fB<action name="PreviousWindow" />\fR
.RS 4
Cycle focus to previous window.\&
.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" and
"client-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.\& Default is
yes.\&
.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.\& 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.\&
.PP
.RE
\fB<action name="FocusOutput" output="HDMI-A-1" />\fR
.RS 4
Give focus to topmost window on given output and warp the cursor
to the center of the window.\& If the given output does not contain
any windows, the cursor is centered on the given 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" />\fR
.RS 4
Use the automatic placement policy to move the active window to a
position on its output that will minimize overlap with other windows.\&
.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="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
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)