.\" 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-theme" "5" "2024-05-11"
.PP
.SH NAME
.PP
labwc - theme files
.PP
.SH THEME
.PP
The theme engine aims to be compatible with openbox and themes will be
searched for in the following order:
.PP
.PD 0
.IP \(bu 4
${XDG_DATA_HOME:-$HOME/.\&local/share}/themes/<theme-name>/openbox-3/
.IP \(bu 4
$HOME/.\&themes/<theme-name>/openbox-3/
.IP \(bu 4
/usr/share/themes/<theme-name>/openbox-3/
.IP \(bu 4
/usr/local/share/themes/<theme-name>/openbox-3/
.IP \(bu 4
/opt/share/themes/<theme-name>/openbox-3/
.PD
.PP
When $XDG_DATA_HOME is defined, it replaces (rather than augments)
$HOME/.\&local/share.\& The same is the case for $XDG_DATA_DIRS and /usr/share/.\&
.PP
Choosing a theme is done by editing the <name> key in the <theme> section of
the rc.\&xml configuration file (labwc-config(5)).\&
.PP
A theme consists of a themerc file and optionally some titlebar icons (referred
to as buttons).\&
.PP
Theme settings specified in themerc can be overridden by creating a
\&'\&themerc-override'\& file in the configuration directory, which is normally
$HOME/.\&config/labwc/ but can be a few other locations as described in
labwc-config(5).\&
.PP
.SH DATA TYPES
.PP
\fBcolor\fR
.RS 4
Colors can be specified by either of the following:
.PD 0
.IP \(bu 4
#rrggbb (hexadecimal RGB values)
.IP \(bu 4
#rrggbb aaa (same but with decimal alpha value percentage)
.IP \(bu 4
#rrggbbaa (same but with inline alpha value in hex encoding)
.PD
.PP
Note: the #rrggbb aaa notation is deprecated starting from
labwc 0.\&7.\&2 and may be removed in future releases.\&
.PP
.RE
\fBjustification\fR
.RS 4
Justification determines the horizontal alignment of text.\&
Valid options are Left, Center and Right.\&
.PP
.RE
.SH THEME ELEMENTS
.PP
\fBborder.\&width\fR
.RS 4
Line width (integer) of border border drawn around window frames.\&
Default is 1.\&
.PP
.RE
\fBpadding.\&height\fR
.RS 4
Vertical padding size, used for spacing out elements in the window
decorations.\& Default is 3.\&
.PP
.RE
\fBtitlebar.\&height\fR
.RS 4
Window title bar height.\&
Default equals the vertical font extents of the title plus 2x
padding.\&height.\&
.PP
.RE
\fBmenu.\&items.\&padding.\&x\fR
.RS 4
Horizontal padding of menu text entries in pixels.\&
Default is 7.\&
.PP
.RE
\fBmenu.\&items.\&padding.\&y\fR
.RS 4
Vertical padding of menu text entries in pixels.\&
Default is 4.\&
.PP
.RE
\fBmenu.\&overlap.\&x\fR
.RS 4
Horizontal overlap in pixels between submenus and their parents.\& A
positive value move submenus over the top of their parents, whereas a
negative value creates a gap between submenus and their parents.\&
Default is 0.\&
.PP
.RE
\fBmenu.\&overlap.\&y\fR
.RS 4
Vertical offset in pixels between submenus and their parents.\& Positive
values for downwards and negative for upwards.\& Default is 0.\&
.PP
.RE
\fBmenu.\&width.\&min\fR
.RS 4
Minimal width for menus.\& Default is 20.\&
A fixed width can be achieved by setting .\&min and .\&max to the same
value.\&
.PP
.RE
\fBmenu.\&width.\&max\fR
.RS 4
Maximal width for menus.\& Default is 200.\&
A fixed width can be achieved by setting .\&min and .\&max to the same
value.\&
.PP
.RE
\fBwindow.\&active.\&border.\&color\fR
.RS 4
Border color of active window.\&
.PP
.RE
\fBwindow.\&inactive.\&border.\&color\fR
.RS 4
Border color of inactive window.\&
.PP
.RE
\fBwindow.\&active.\&indicator.\&toggled-keybind.\&color\fR
.RS 4
Status indicator for the ToggleKeybinds action.\& Can be set to the same
value as set for window.\&active.\&border.\&color to disable the status
indicator.\&
.PP
.RE
\fBwindow.\&active.\&title.\&bg.\&color\fR
.RS 4
Background color for the focused window'\&s titlebar.\&
.PP
.RE
\fBwindow.\&inactive.\&title.\&bg.\&color\fR
.RS 4
Background color for non-focused windows'\& titlebars.\&
.PP
.RE
\fBwindow.\&active.\&label.\&text.\&color\fR
.RS 4
Text color for the focused window'\&s titlebar.\&
.PP
.RE
\fBwindow.\&inactive.\&label.\&text.\&color\fR
.RS 4
Text color non-focused windows'\& titlebars.\&
.PP
.RE
\fBwindow.\&label.\&text.\&justify\fR
.RS 4
Specifies how window titles are aligned in the titlebar for both
focused and unfocused windows.\& Type justification.\& Default Left.\&
.PP
.RE
\fBwindow.\&active.\&button.\&unpressed.\&image.\&color\fR
.RS 4
Color of the images in titlebar buttons in their default, unpressed,
state.\& This element is for the focused window.\&
.PP
.RE
\fBwindow.\&inactive.\&button.\&unpressed.\&image.\&color\fR
.RS 4
Color of the images in titlebar buttons in their default, unpressed,
state.\& This element is for non-focused windows.\&
.PP
.RE
Note: The button elements (i.\&e.\& window.\&[in]active.\&button.\&*) support defining
different types of buttons individually by inserting the type ("menu",
"iconify", "max" and "close") after the button node.\& For example:
window.\&active.\&button.\&iconify.\&unpressed.\&image.\&color
This syntax is not documented on the openbox.\&org wiki, but is supported by
openbox and is used by many popular themes.\& For the sake of brevity, these
elements are not listed here, but are supported.\&
.PP
\fBwindow.\&active.\&shadow.\&size\fR
.RS 4
Size of the drop-shadow for the focused window, in pixels.\&
Default is 60.\&
.PP
.RE
\fBwindow.\&inactive.\&shadow.\&size\fR
.RS 4
Size of drop-shadows for non-focused windows, in pixels.\&
Default is 40.\&
.PP
.RE
\fBwindow.\&active.\&shadow.\&color\fR
.RS 4
Color of the drop-shadow for the focused window, including opacity.\&
Default is #00000060 (black with 38% opacity).\&
.PP
.RE
\fBwindow.\&inactive.\&shadow.\&color\fR
.RS 4
Color of drop-shadows for non-focused windows, including opacity.\&
Default is #00000040 (black with 25% opacity).\&
.PP
.RE
\fBmenu.\&items.\&bg.\&color\fR
.RS 4
Background color of inactive menu items.\&
.PP
.RE
\fBmenu.\&items.\&text.\&color\fR
.RS 4
Text color of inactive menu item.\&
.PP
.RE
\fBmenu.\&items.\&active.\&bg.\&color\fR
.RS 4
Background color of active menu items.\&
.PP
.RE
\fBmenu.\&items.\&active.\&text.\&color\fR
.RS 4
Text color of active menu item.\&
.PP
.RE
\fBmenu.\&separator.\&width\fR
.RS 4
Line thickness of menu separators.\& Default 1.\&
.PP
.RE
\fBmenu.\&separator.\&padding.\&width\fR
.RS 4
Space on the left and right side of each separator line.\& Default 6.\&
.PP
.RE
\fBmenu.\&separator.\&padding.\&height\fR
.RS 4
Space above and below each separator line.\& Default 3.\&
.PP
.RE
\fBmenu.\&separator.\&color\fR
.RS 4
Menu separator color.\& Default #888888.\&
.PP
.RE
\fBosd.\&bg.\&color\fR
.RS 4
Background color of on-screen-display.\& Inherits
\fBwindow.\&active.\&title.\&bg.\&color\fR if not set.\&
.PP
.RE
\fBosd.\&border.\&color\fR
.RS 4
Border color of on-screen-display.\& Inherits \fBosd.\&label.\&text.\&color\fR if
not set.\&
.PP
.RE
\fBosd.\&border.\&width\fR
.RS 4
Border width of on-screen-display.\& Inherits \fBborder.\&width\fR if not set.\&
.PP
.RE
\fBosd.\&label.\&text.\&color\fR
.RS 4
Text color of on-screen-display.\& Inherits
\fBwindow.\&active.\&label.\&text.\&color\fR if not set.\&
.PP
.RE
\fBosd.\&window-switcher.\&width\fR
.RS 4
Width of window switcher in pixels.\& Default is 600.\&
Width can also be percent of the width of the monitor.\&
% is mandatory as last character in this case, max 100%
.PP
.RE
\fBosd.\&window-switcher.\&padding\fR
.RS 4
Padding of window switcher in pixels.\& This is the space between the
window-switcher border and its items.\& Default is 4.\&
.PP
.RE
\fBosd.\&window-switcher.\&item.\&padding.\&x\fR
.RS 4
Horizontal padding of window switcher entries in pixels.\&
Default is 10.\&
.PP
.RE
\fBosd.\&window-switcher.\&item.\&padding.\&y\fR
.RS 4
Vertical padding of window switcher entries in pixels.\&
Default is 1.\&
.PP
.RE
\fBosd.\&window-switcher.\&item.\&active.\&border.\&width\fR
.RS 4
Border width of the selection box in the window switcher in pixels.\&
Default is 2.\&
.PP
.RE
\fBosd.\&window-switcher.\&preview.\&border.\&width\fR
.RS 4
Border width of the outlines shown as the preview of the window selected
by window switcher.\& Inherits \fBosd.\&border.\&width\fR if not set.\&
.PP
.RE
\fBosd.\&window-switcher.\&preview.\&border.\&color\fR
.RS 4
Color(s) of the outlines shown as the preview of the window selected by
window switcher.\& Possible value is a color or up to 3 colors separated
by commas (e.\&g.\& "#ffffff,#000000,#ffffff").\& When multiple colors are
specified, a multi-line rectangle with each line having the specified
color is drawn.\& If not set, this inherits the on-screen-display theme
("[\fBosd.\&bg.\&color\fR],[\fBosd.\&label.\&text.\&color\fR],[\fBosd.\&bg.\&color\fR]").\&
.PP
.RE
\fBosd.\&workspace-switcher.\&boxes.\&width\fR
.RS 4
Width of boxes in workspace switcher in pixels.\& Setting to 0 disables
boxes.\& Default is 20.\&
.PP
.RE
\fBosd.\&workspace-switcher.\&boxes.\&height\fR
.RS 4
Height of boxes in workspace switcher in pixels.\& Setting to 0 disables
boxes.\& Default is 20.\&
.PP
.RE
\fBsnapping.\&overlay.\&region.\&bg.\&enabled\fR [yes|no]
.RS 4
Show a filled rectangle as an overlay when a window is snapped to a
region.\& Default is yes for hardware-based renderers and no for
software-based renderers.\&
.PP
.RE
\fBsnapping.\&overlay.\&edge.\&bg.\&enabled\fR [yes|no]
.RS 4
Show a filled rectangle as an overlay when a window is snapped to an
edge.\& Default is yes for hardware-based renderer and no for
software-based renderers.\&
.PP
.RE
\fBsnapping.\&overlay.\&region.\&border.\&enabled\fR [yes|no]
.RS 4
Show an outlined rectangle as an overlay when a window is snapped to a
region.\& Default is no for hardware-based renderers and yes for
software-based renderers.\&
.PP
.RE
\fBsnapping.\&overlay.\&edge.\&border.\&enabled\fR [yes|no]
.RS 4
Show an outlined rectangle as an overlay when a window is snapped to an
edge.\& Default is no for hardware-based renderer and yes for
software-based renderers.\&
.PP
.RE
\fBsnapping.\&overlay.\&region.\&bg.\&color\fR
.RS 4
Color of a filled rectangle shown as an overlay when a window is snapped
to a region.\& Default is #8080b380.\&
.PP
.RE
\fBsnapping.\&overlay.\&edge.\&bg.\&color\fR
.RS 4
Color of a filled rectangle shown as an overlay when a window is snapped
to an edge.\& Default is #8080b380.\&
.PP
.RE
\fBsnapping.\&overlay.\&region.\&border.\&width\fR
.RS 4
Border width of an outlined rectangle shown as an overlay when a window
is snapped to a region.\& Inherits `osd.\&border.\&width` if not set.\&
.PP
.RE
\fBsnapping.\&overlay.\&edge.\&border.\&width\fR
.RS 4
Border width of an outlined rectangle shown as the preview when a window
is snapped to an edge.\& Inherits `osd.\&border.\&width` if not set.\&
.PP
.RE
\fBsnapping.\&overlay.\&region.\&border.\&color\fR
.RS 4
Color(s) of an outlined rectangle shown as an overlay when a window is
snapped to a region.\& Possible values and the default value are the same
as those of \fBosd.\&window-switcher.\&preview.\&border.\&color\fR.\&
.PP
.RE
\fBsnapping.\&overlay.\&edge.\&border.\&color\fR
.RS 4
Color(s) of an outlined rectangle shown as an overlay when a window is
snapped to an edge.\& Possible values and the default value are the same
as those of \fBosd.\&window-switcher.\&preview.\&border.\&color\fR.\&
.PP
.RE
\fBborder.\&color\fR
.RS 4
Set both \fBwindow.\&active.\&border.\&color\fR and
\fBwindow.\&inactive.\&border.\&color\fR.\& This is obsolete, but supported for
backward compatibility as some themes still contain it.\&
.PP
.RE
.SH BUTTONS
.PP
The images used for the titlebar icons are referred to as buttons.\&
.PP
The image formats listed below are supported.\& They are listed in order of
precedence, where the first format in the list is searched for first.\&
.PP
.PD 0
.IP \(bu 4
png
.IP \(bu 4
svg
.IP \(bu 4
xbm
.PD
.PP
By default, buttons are 1-bit xbm (X Bitmaps).\& These are masks where 0=clear and
1=colored.\& The xbm image files are placed in the same directory as the themerc
file within a particular theme.\& The following xbm buttons are supported:
.PP
.PD 0
.IP \(bu 4
max.\&xbm
.IP \(bu 4
iconify.\&xbm
.IP \(bu 4
close.\&xbm
.IP \(bu 4
menu.\&xbm
.IP \(bu 4
max_toggled.\&xbm
.PD
.PP
Additional icons can be defined to be shown when the mouse pointer is hovering
over the button in question:
.PP
.PD 0
.IP \(bu 4
max_hover.\&xbm
.IP \(bu 4
iconify_hover.\&xbm
.IP \(bu 4
close_hover.\&xbm
.IP \(bu 4
menu_hover.\&xbm
.IP \(bu 4
max_toggled_hover.\&xbm
.PD
.PP
One advantage of xbm buttons over other formats is that they change color based
on the theme.\& Other formats use the suffices "-active" and "-inactive" to align
with the respective titlebar colors.\& For example: "close-active.\&png"
.PP
For compatibility reasons, the following alternative names are supported
for xbm files:
.PP
.PD 0
.IP \(bu 4
max_hover_toggled.\&xbm for max_toggled_hover.\&xbm
.PD
.PP
When using png or svg icons, for a full theme experience all of the
following icons should be added:
.PP
.PD 0
.IP \(bu 4
close-active.\&[png|svg]
.IP \(bu 4
close_hover-active.\&[png|svg]
.IP \(bu 4
close_hover-inactive.\&[png|svg]
.IP \(bu 4
close-inactive.\&[png|svg]
.IP \(bu 4
iconify-active.\&[png|svg]
.IP \(bu 4
iconify_hover-active.\&[png|svg]
.IP \(bu 4
iconify_hover-inactive.\&[png|svg]
.IP \(bu 4
iconify-inactive.\&[png|svg]
.IP \(bu 4
max-active.\&[png|svg]
.IP \(bu 4
max_hover-active.\&[png|svg]
.IP \(bu 4
max_hover-inactive.\&[png|svg]
.IP \(bu 4
max-inactive.\&[png|svg]
.IP \(bu 4
max_toggled-active.\&[png|svg]
.IP \(bu 4
max_toggled_hover-active.\&[png|svg]
.IP \(bu 4
max_toggled_hover-inactive.\&[png|svg]
.IP \(bu 4
max_toggled-inactive.\&[png|svg]
.IP \(bu 4
menu-active.\&[png|svg]
.IP \(bu 4
menu_hover-active.\&[png|svg]
.IP \(bu 4
menu_hover-inactive.\&[png|svg]
.IP \(bu 4
menu-inactive.\&[png|svg]
.PD
.PP
.SH DEFINITIONS
.PP
The handle is the window edge decoration at the bottom of the window.\&
.PP
.SH SEE ALSO
.PP
labwc(1), labwc-config(5), labwc-actions(5)