NAME¶
spectrwm
—
window manager for X11
SYNOPSIS¶
DESCRIPTION¶
spectrwm
is a minimalistic window manager
that tries to stay out of the way so that valuable screen real estate can be
used for much more important stuff. It has sane defaults and does not require
one to learn a language to do any configuration. It was written by hackers for
hackers and it strives to be small, compact and fast.
When
spectrwm
starts up, it reads settings
from its configuration file,
spectrwm.conf.
See the
CONFIGURATION
FILES section below.
The following notation is used throughout this page:
M
- Meta
S
- Shift
- ⟨
Name
⟩
- Named key
M1
- Mouse button 1
M3
- Mouse button 3
spectrwm
is very simple in its use. Most of
the actions are initiated via key or mouse bindings. See the
BINDINGS section below for
defaults and customizations.
CONFIGURATION FILES¶
spectrwm
first tries to open the user
specific file,
~/.spectrwm.conf. If that
file is unavailable, it then tries to open the global configuration file
/etc/spectrwm.conf.
The format of the file is
keyword
=
setting
For example:
color_focus = red
Enabling or disabling an option is done by using 1 or 0 respectively.
Colors need to be specified per the
XQueryColor(3)
specification.
Comments begin with a #. When a literal
‘
#
’ is desired in an option, then it
must be escaped with a backslash. i.e. \#
The file supports the following keywords:
autorun
- Launch an application in a specified workspace at start-of-day. Defined in
the format
ws
[idx]:application,
e.g. ws[2]:xterm launches an xterm in workspace 2.
bar_action
- External script that populates additional information in the status bar,
such as battery life.
bar_at_bottom
- Place the statusbar at the bottom of each region instead of the top.
bar_border
[x]
- Border color of the status bar(s) in screen
x.
bar_border_unfocus
[x]
- Border color of the status bar(s) on unfocused region(s) in screen
x.
bar_border_width
- Set status bar border thickness in pixels. Disable border by setting to
0.
bar_color
[x]
- Background color of the status bar(s) in screen
x.
bar_enabled
- Set default
bar_toggle
state; default
is 1.
bar_enabled_ws
[x]
- Set default
bar_toggle_ws
state on
workspace x; default is 1.
bar_font
- Font used in the status bar. Either Xft or X Logical Font Description
(XLFD) may be used to specify fonts. Fallback fonts may be specified by
separating each font with a comma. If all entries are in XLFD syntax, font
set will be used. If at least one entry is Xft, Xft will be used. Note
that if Xft is in use, only the first font that successfully loads will be
used regardless of missing glyphs. The default is to use font set. Also
note that dmenu(1) does not support Xft
fonts.
Xft examples:
bar_font = Terminus:style=Regular:pixelsize=14:antialias=true
bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,Terminus:pixelsize=14,-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*
Font set examples:
bar_font = -*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*
bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,-*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*,-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*
To list the available fonts in your system see
fc-list(1) or
xlsfonts(1) manpages. The
xfontsel(1) application can help with the
XLFD setting.
bar_font_color
[x]
- Color of the font in status bar in screen
x.
bar_format
- Set the bar format string, overriding
clock_format
and all of the
enabled
options. The format is passed
through strftime(3) before being used. It may
contain the following character sequences:
Character sequence |
Replaced with |
+< |
Pad with a space |
+A |
Output of the external script |
+C |
Window class (from WM_CLASS) |
+D |
Workspace name |
+F |
Floating indicator |
+I |
Workspace index |
+M |
Number of iconic (minimized) windows in workspace |
+N |
Screen number |
+P |
Window class and instance separated by a colon |
+S |
Stacking algorithm |
+T |
Window instance (from WM_CLASS) |
+U |
Urgency hint |
+V |
Program version |
+W |
Window name (from _NET_WM_NAME/WM_NAME) |
++ |
A literal ‘+ ’ |
All character sequences may limit its output to a specific length, for
example +64A. Any characters that don't match the specification are copied
as-is.
bar_justify
- Justify the status bar text. Possible values are
left,
center, and
right.
Note that if the output is not left justified, it may not be properly
aligned in some circumstances, due to the white-spaces in the default
static format. See the
bar_format
option for more details.
bind
[x]
- Bind key combo to action x. See the
BINDINGS section below.
border_width
- Set window border thickness in pixels. Disable all borders by setting to
0.
boundary_width
- Set region containment boundary width in pixels. This is how far a window
must be dragged/resized beyond the region edge before it is allowed
outside the region. This has no effect when manipulating the window with
key bindings. Disable the window containment effect by setting to 0.
clock_enabled
- Enable or disable displaying the clock in the status bar. Disable by
setting to 0 so a custom clock could be used in the
bar_action
script.
iconic_enabled
- Display the number of iconic (minimized) windows in the status bar. Enable
by setting to 1.
color_focus
- Border color of the currently focused window. Default is red.
color_focus_maximized
- Border color of the currently focused, maximized window. Defaults to the
value of
color_focus
.
color_unfocus
- Border color of unfocused windows, default is rgb:88/88/88.
color_unfocus_maximized
- Border color of unfocused, maximized windows. Defaults to the value of
color_unfocus
.
dialog_ratio
- Some applications have dialogue windows that are too small to be useful.
This ratio is the screen size to what they will be resized. For example,
0.6 is 60% of the physical screen size.
disable_border
- Remove border when bar is disabled and there is only one window on the
region.
focus_close
- Window to put focus when the focused window is closed. Possible values are
first,
next,
previous (default) and
last.
next and
previous are relative to the window that
is closed.
focus_close_wrap
- Whether to allow the focus to jump to the last window when the first
window is closed or vice versa. Disable by setting to 0.
focus_default
- Window to put focus when no window has been focused. Possible values are
first and
last (default).
focus_mode
- Window focus behavior with respect to the mouse cursor. Possible values:
- default
- Set window focus on border crossings caused by cursor motion and
window interaction.
- follow
- Set window focus on all cursor border crossings, including workspace
switches and changes to layout.
- manual
- Set window focus on window interaction only.
java_workaround
- Workaround a Java GUI rendering issue on non-reparenting window managers
by impersonating the LG3D window manager, written by Sun. Default is
1.
keyboard_mapping
- Clear all key bindings and load new key bindings from the specified file.
This allows you to load pre-defined key bindings for your keyboard layout.
See the KEYBOARD
MAPPING FILES section below for a list of keyboard mapping files that
have been provided for several keyboard layouts.
layout
- Select layout to use at start-of-day. Defined in the format
ws
[idx]:master_grow:master_add:stack_inc:always_raise:stack_mode,
e.g. ws[2]:-4:0:1:0:horizontal sets worskspace 2 to the horizontal stack
mode, shrinks the master area by 4 ticks and adds one window to the stack,
while maintaining default floating window behavior. Possible
stack_mode values are
vertical,
vertical_flip,
horizontal,
horizontal_flip and
fullscreen.
See master_grow
,
master_shrink
,
master_add
,
master_del
,
stack_inc
,
stack_dec
, and
always_raise
for more information. Note
that the stacking options are complicated and have side-effects. One
should familiarize oneself with these commands before experimenting with
the layout
option.
This setting is not retained at restart.
modkey
- Change mod key. Mod1 is generally the ALT key and Mod4 is the windows key
on a PC.
name
- Set the name of a workspace at start-of-day. Defined in the format
ws
[idx]:name,
e.g. ws[1]:Console sets the name of workspace 1 to
“Console”.
program
[p]
- Define new action to spawn a program p.
See the PROGRAMS section
below.
quirk
[c:i:n]
- Add "quirk" for windows with class
c, instance
i and name
n. See the
QUIRKS section below.
region
- Allocates a custom region, removing any autodetected regions which occupy
the same space on the screen. Defined in the format
screen
[idx]:widthxheight+x+y,
e.g. screen[1]:800x1200+0+0.
To make a region span multiple monitors, create a region big enough to cover
them all, e.g. screen[1]:2048x768+0+0 makes the region span two monitors
with 1024x768 resolution sitting one next to the other.
region_padding
- Pixel width of empty space within region borders. Disable by setting to
0.
spawn_position
- Position in stack to place newly spawned windows. Possible values are
first,
next,
previous and
last (default).
next and
previous are relative to the focused
window.
stack_enabled
- Enable or disable displaying the current stacking algorithm in the status
bar.
term_width
- Set a preferred minimum width for the terminal. If this value is greater
than 0,
spectrwm
will attempt to adjust
the font sizes in the terminal to keep the terminal width above this
number as the window is resized. Only
xterm(1) is currently supported. The
xterm(1) binary must not be setuid or setgid,
which it is by default on most systems. Users may need to set
program[term] (see the
PROGRAMS section) to use an
alternate copy of the xterm(1) binary without
the setgid bit set.
tile_gap
- Pixel width of empty space between tiled windows. Negative values cause
overlap. Set this to the opposite of border_width to collapse the border
between tiles. Disable by setting to 0.
urgent_collapse
- Enables hiding of placeholders in the urgency hint indicator for
workspaces that do not have any urgent windows. Enable by setting to
1.
urgent_enabled
- Enable or disable the urgency hint indicator in the status bar. Note that
many terminal emulators require an explicit setting for the bell character
to trigger urgency on the window. In
xterm(1), for example, one needs to add the
following line to .Xdefaults:
verbose_layout
- Enable or disable displaying the current master window count and stack
column/row count in the status bar. Enable by setting to 1. See
master_add,
master_del,
stack_inc and
stack_dec for more information.
window_class_enabled
- Enable or disable displaying the window class name (from WM_CLASS) in the
status bar. Enable by setting to 1.
window_instance_enabled
- Enable or disable displaying the window instance name (from WM_CLASS) in
the status bar. Enable by setting to 1.
window_name_enabled
- Enable or disable displaying the window display name (from
_NET_WM_NAME/WM_NAME) in the status bar. Enable by setting to 1.
To prevent excessively large window names from pushing the remaining text
off the bar, it's limited to 64 characters, by default. See the
bar_format
option for more
details.
warp_pointer
- Centers the mouse pointer on the focused window when using key bindings to
change focus, switch workspaces, change regions, etc. Enable by setting to
1.
workspace_limit
- Set the total number of workspaces available. Minimum is 1, maximum is 22,
default is 10.
PROGRAMS¶
spectrwm
allows you to define custom actions
to launch programs of your choice and then bind them the same as with built-in
actions. See the
BINDINGS
section below.
Custom programs in the configuration file are specified as follows:
program[action] =
progpath
[]
action is any identifier that does not conflict
with a built-in action or keyword,
progpath
is the desired program, and
arg is zero or
more arguments to the program.
Remember that when using # in your program call, it must be escaped with a
backslash. i.e. \#
The following argument variables will be substituted for values at the time the
program is spawned:
Example:
program[ff] = /usr/local/bin/firefox http://spectrwm.org/
bind[ff] = MOD+Shift+b # Now M-S-b launches firefox
To cancel the previous, unbind it:
Default programs:
- dmenu_run $dmenu_bottom -fn $bar_font -nb $bar_color -nf $bar_font_color
-sb $bar_border -sf $bar_color
term
- x-terminal-emulator
lock
- xscreensaver-command -lock # optional
initscr
- initscreen.sh # optional
screenshot_all
- screenshot.sh full # optional
screenshot_wind
- screenshot.sh window # optional
Note that optional default programs will not be validated unless overridden. If
a default program fails validation, you can resolve the exception by
installing the program, modifying the program call or disabling the program by
freeing the respective key binding.
For example, to override
menu
:
To unbind
menu
and prevent it from being
validated:
BINDINGS¶
spectrwm
provides many functions (or actions)
accessed via key or mouse bindings.
The current mouse bindings are described below:
M1
- Focus window
M-M1
- Move window
M-M3
- Resize window
M-S-M3
- Resize window while maintaining it centered
The default key bindings are described below:
The action names and descriptions are listed below:
Custom bindings in the configuration file are specified as follows:
bind[action] =
keys
action is one of the actions listed above (or
empty to unbind) and
keys is in the form of
zero or more modifier keys (MOD, Mod1, Shift, etc.) and one or more normal
keys (b, Space, etc.), separated by ‘
+
’.
Example:
bind[reset] = Mod4+q # bind Windows-key + q to reset
bind[] = Mod1+q # unbind Alt + q
To use the currently defined
modkey
, specify
MOD as the modifier key.
Multiple key combinations may be bound to the same action.
To bind non-latin characters such as å or π you must enter the xkb
character name instead of the character itself. Run xev, focus the window and
press the specific key and in the terminal output read the symbol name. In the
following example for å:
KeyPress event, serial 41, synthetic NO, window 0x2600001,
root 0x15a, subw 0x0, time 106213808, (11,5), root:(359,823),
state 0x0, keycode 24 (keysym 0xe5, aring), same_screen YES,
XLookupString gives 2 bytes: (c3 a5) "å"
XmbLookupString gives 2 bytes: (c3 a5) "å"
XFilterEvent returns: False
The xkb name is aring. In other words, in
spectrwm.conf add:
bind[program] = MOD+aring
KEYBOARD MAPPING FILES¶
Keyboard mapping files for several keyboard layouts are listed below. These
files can be used with the
keyboard_mapping
setting to load pre-defined key bindings for the specified keyboard layout.
QUIRKS¶
spectrwm
provides "quirks" which
handle windows that must be treated specially in a tiling window manager, such
as some dialogs and fullscreen apps.
The default quirks are described below:
- Firefox-bin:firefox-bin
- TRANSSZ
- Firefox:Dialog
- FLOAT
- Gimp:gimp
- FLOAT + ANYWHERE
- MPlayer:xv
- FLOAT + FULLSCREEN + FOCUSPREV
- OpenOffice.org 2.4:VCLSalFrame
- FLOAT
- OpenOffice.org 3.1:VCLSalFrame
- FLOAT
- pcb:pcb
- FLOAT
- xine:Xine Window
- FLOAT + ANYWHERE
- xine:xine Panel
- FLOAT + ANYWHERE
- xine:xine Video Fullscreen Window
- FULLSCREEN + FLOAT
- Xitk:Xitk Combo
- FLOAT + ANYWHERE
- Xitk:Xine Window
- FLOAT + ANYWHERE
- XTerm:xterm
- XTERM_FONTADJ
The quirks themselves are described below:
- FLOAT
- This window should not be tiled, but allowed to float freely.
- TRANSSZ
- Adjusts size on transient windows that are too small using
dialog_ratio
(see
CONFIGURATION
FILES).
- ANYWHERE
- Allow window to position itself, uncentered.
- XTERM_FONTADJ
- Adjust xterm fonts when resizing.
- FULLSCREEN
- Remove border to allow window to use full region size.
- FOCUSPREV
- On exit force focus on previously focused application not previous
application in the stack.
- NOFOCUSONMAP
- Don't change focus to the window when it first appears on the screen. Has
no effect when
focus_mode
is set to
follow.
- FOCUSONMAP_SINGLE
- When the window first appears on the screen, change focus to the window if
there are no other windows on the workspace with the same WM_CLASS
class/instance value. Has no effect when
focus_mode
is set to
follow.
- OBEYAPPFOCUSREQ
- When an application requests focus on the window via a _NET_ACTIVE_WINDOW
client message (source indication of 1), comply with the request. Note
that a source indication of 0 (unspecified) or 2 (pager) are always
obeyed.
- IGNOREPID
- Ignore the PID when determining the initial workspace for a new window.
Especially useful for terminal windows that share a process.
- IGNORESPAWNWS
- Ignore the spawn workspace when determining the initial workspace for a
new window.
- WS[n]
- Force a new window to appear on workspace
n.
Custom quirks in the configuration file are specified as follows:
quirk[class[:instance[:name]]]
= quirk [+
quirk ...
]
class,
instance (optional) and
name (optional) are patterns used to
determine which window(s) the quirk(s) apply to and
quirk is one of the quirks from the list
above.
Note that patterns are interpreted as POSIX Extended Regular Expressions. Any
':', '[' or ']' must be escaped with '\'. See
regex(7) for more information on POSIX Extended
Regular Expressions.
For example:
quirk[MPlayer] = FLOAT + FULLSCREEN + FOCUSPREV # Float all windows having a class of 'MPlayer'
quirk[.*] = FLOAT # Float all windows by default.
quirk[.*:.*:.*] = FLOAT # Same as above.
quirk[Firefox:Navigator] = FLOAT # Float all Firefox browser windows.
quirk[::Console] = FLOAT # Float windows with WM_CLASS not set and a window name of 'Console'.
quirk[\[0-9\].*:.*:\[\[\:alnum\:\]\]*] = FLOAT # Float windows with WM_CLASS class beginning with a number, any WM_CLASS instance and a _NET_WM_NAME/WM_NAME either blank or containing alphanumeric characters without spaces.
quirk[pcb:pcb] = NONE # remove existing quirk
You can obtain
class,
instance and
name by running
xprop(1) and then clicking on the desired window.
In the following example the main window of Firefox was clicked:
$ xprop | grep -E "^(WM_CLASS|_NET_WM_NAME|WM_NAME)"
WM_CLASS(STRING) = "Navigator", "Firefox"
WM_NAME(STRING) = "spectrwm - ConformalOpenSource"
_NET_WM_NAME(UTF8_STRING) = "spectrwm - ConformalOpenSource"
Note that
xprop(1) displays WM_CLASS as:
WM_CLASS(STRING) = "<instance>", "<class>"
In the example above the quirk entry would be:
quirk[Firefox:Navigator] = FLOAT
spectrwm
also automatically assigns quirks to
windows based on the value of the window's _NET_WM_WINDOW_TYPE property as
follows:
- _NET_WM_WINDOW_TYPE_DOCK
- FLOAT + ANYWHERE
- _NET_WM_WINDOW_TYPE_TOOLBAR
- FLOAT + ANYWHERE
- _NET_WM_WINDOW_TYPE_UTILITY
- FLOAT + ANYWHERE
- _NET_WM_WINDOW_TYPE_SPLASH
- FLOAT
- _NET_WM_WINDOW_TYPE_DIALOG
- FLOAT
In all other cases, no automatic quirks are assigned to the window. Quirks
specified in the configuration file override the automatic quirks.
EWMH¶
spectrwm
partially implements the Extended
Window Manager Hints (EWMH) specification. This enables controlling windows as
well as
spectrwm
itself from external
scripts and programs. This is achieved by
spectrwm
responding to certain
ClientMessage events. From the terminal these events can be conveniently sent
using tools such as
wmctrl(1) and
xdotool(1). For the actual format of these
ClientMessage events, see the EWMH specification.
The id of the currently focused window is stored in the _NET_ACTIVE_WINDOW
property of the root window. This can be used for example to retrieve the
title of the currently active window with
xprop(1) and
grep(1):
$ WINDOWID=`xprop -root _NET_ACTIVE_WINDOW | grep -o "0x.*"`
$ xprop -id $WINDOWID _NET_WM_NAME | grep -o "\".*\""
A window can be focused by sending a _NET_ACTIVE_WINDOW client message to the
root window. For example, using
wmctrl(1) to send
the message (assuming 0x4a0000b is the id of the window to be focused):
Windows can be closed by sending a _NET_CLOSE_WINDOW client message to the root
window. For example, using
wmctrl(1) to send the
message (assuming 0x4a0000b is the id of the window to be closed):
Windows can be floated and un-floated by adding or removing the
_NET_WM_STATE_ABOVE atom from the _NET_WM_STATE property of the window. This
can be achieved by sending a _NET_WM_STATE client message to the root window.
For example, the following toggles the floating state of a window using
wmctrl(1) to send the message (assuming 0x4a0000b
is the id of the window to be floated or un-floated):
$ wmctrl -i -r 0x4a0000b -b toggle,_NET_WM_STATE_ABOVE
Windows can also be iconified and un-iconified by substituting
_NET_WM_STATE_HIDDEN for _NET_WM_STATE_ABOVE in the previous example:
$ wmctrl -i -r 0x4a0000b -b toggle,_NET_WM_STATE_HIDDEN
Floating windows can also be resized and moved by sending a
_NET_MOVERESIZE_WINDOW client message to the root window. For example, using
wmctrl(1) to send the message (assuming 0x4a0000b
is the id of the window to be resize/moved):
$ wmctrl -i -r 0x4a0000b -e 0,100,50,640,480
This moves the window to (100,50) and resizes it to 640x480.
Any _NET_MOVERESIZE_WINDOW events received for stacked windows are ignored.
SIGNALS¶
Sending
spectrwm
a HUP signal will restart
it.
FILES¶
- ~/.spectrwm.conf
spectrwm
user specific settings.
- /etc/spectrwm.conf
spectrwm
global settings.
HISTORY¶
spectrwm
was inspired by xmonad & dwm.
AUTHORS¶
spectrwm
was written by: