| SPECTRWM(1) | General Commands Manual | SPECTRWM(1) |
spectrwm — window
manager for X11
spectrwm |
[-c file]
[-v] |
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:
spectrwm is very simple in its use. Most
of the actions are initiated via key or pointer bindings. See the
BINDINGS section below for defaults and
customizations.
spectrwm looks for the user-configuration
file in the following order:
If the user-configuration file is not found,
spectrwm then looks for the global configuration
file in the following order:
The format of the file is
keyword
= settingFor example:
color_focus = redEnabling 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:
autorunws[idx]:application,
e.g. ws[2]:xterm launches an xterm(1) in workspace 2.
Note that workspace mapping is handled via
libswmhack.so. When
autorun spawns windows via a daemon, ensure the
daemon is started with the correct LD_PRELOAD in
its environment.
For example, starting urxvtd(1) via xinit(1):
LD_PRELOAD=/usr/lib/libswmhack.so.0.0 urxvtd -q -o -f
Spawned programs automatically have LD_PRELOAD set when executed.
It is advised to check the man page of ld.so as LD_PRELOAD is sometimes ignored by some operating systems. A workaround is available, e.g. launch an xterm(1) in workspace 2:
autorun = ws[2]:xterm -name ws2 quirk[XTerm:ws2] = WS[2]
bar_actionbar_action_expandbar_format character sequences in
bar_action output; default is 0.bar_at_bottombar_border[x]bar_border_unfocus[x]bar_border_widthbar_color[x]A comma separated list of up to 10 colors can be specified.
The first value is used as the default background color. Any of these
colors can then be selected as a background color in the status bar
through the use of the markup sequence +@bg=n;
where n is between 0 and 9.
bar_color_selected[x]bar_border.bar_enabledbar_toggle state; default is 1.bar_enabled_ws[x]bar_toggle_ws state on workspace
x; default is 1.bar_fontThe default is to use font set.
If Xft is used, a comma-separated list of up to 10 fonts can
be specified. The first entry is the default font. Any font defined here
can then be selected in the status bar through the use of the markup
sequence +@fn=n; where n is between 0 and 9.
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]A comma separated list of up to 10 colors can be specified.
The first value is used as the default foreground color. Any of these
colors can then be selected as a foreground color in the status bar
through the use of the markup sequence +@fg=n;
where n is between 0 and 9.
bar_font_color_selected[x]bar_color.bar_font_puabar_formatclock_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 |
+L |
Workspace list indicator |
+M |
Number of iconic (minimized) windows in workspace |
+N |
Screen number |
+P |
Window class and instance separated by a colon |
+R |
Region index |
+S |
Stacking algorithm |
+T |
Window instance (from WM_CLASS) |
+U |
Urgency hint |
+V |
Program version |
+W |
Window name (from _NET_WM_NAME/WM_NAME) |
+|[weight][justify] |
Begin new section and reset markup sequence effects.
|
++ |
A literal ‘+’ |
+@ |
Prefix for text markup sequences |
The currently recognized text markup sequences are:
| Character sequence | Action |
+@fn=n; |
Selects font n (from 0 to 9) from
bar_font. |
+@fg=n; |
Selects foreground color n (from 0 to 9) from
bar_font_color. |
+@bg=n; |
Selects background color n (from 0 to 9) from
bar_color. |
+@stp; |
Stops the interpretation of markup sequences. Any markup sequence found after +@stp will appear as normal characters in the status bar. |
Note that markup sequences in
bar_action script output will only be processed
if bar_action_expand is enabled.
All character sequences may limit its output to a specific length, for example +64A. By default, no padding/alignment is done in case the length of the replaced string is less than the specified length (64 in the example). The padding/alignment can be enabled using a '_' character in the sequence. For example: +_64W, +64_W and +_64_W enable padding before (right alignment), after (left alignment), and both before and after (center alignment) window name, respectively. Any characters that don't match the specification are copied as-is.
bar_justifyNote 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]border_widthboundary_widthclock_enabledbar_action script.color_focuscolor_focus_maximizedcolor_focus.color_unfocuscolor_unfocus_maximizedcolor_unfocus.dialog_ratiodisable_borderfocus_closefocus_close_wrapfocus_defaultfocus_modeiconic_enabledkeyboard_mappingNote that /dev/null can be specified if you only want to clear bindings.
layoutws[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 max.
See master_grow,
master_shrink,
master_add, master_del,
stack_inc, stack_dec,
stack_balance, 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.
maximize_hide_barmaximize_toggle will also
hide/restore the bar visibility of the affected workspace. Defaults to
0.modkeynamews[idx]:name,
e.g. ws[1]:Console sets the name of workspace 1 to
“Console”.program[p]quirk[c[:i[:n]]]regionscreen[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_paddingspawn_positionstack_enabledterm_widthspectrwm 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_gapborder_width
to collapse the border between tiles. Disable by setting to 0.urgent_collapseurgent_enabledxterm.bellIsUrgent: true
verbose_layoutwarp_focuswarp_pointerwindow_class_enabledwindow_instance_enabledwindow_name_enabledTo 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.
workspace_clampworkspace_indicatorThe default is listcurrent,listactive,markcurrent,printnames
workspace_limitspectrwm 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 [arg
[arg ...]]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.
With the exception of '~' expansion, program calls are executed as-is without any interpretation. A shell can be called to execute shell commands. (e.g. sh -c 'command string').
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:
$bar_border$bar_color$bar_color_selected$bar_font$bar_font_color$bar_font_color_selected$color_focus$color_unfocusbar_at_bottom is enabled.$region_index$workspace_indexExample:
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:
bind[] = MOD+Shift+b
Default programs:
termlocksearchname_workspaceinitscrscreenshot_allscreenshot_windNote 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 binding.
For example, to override lock:
program[lock] = xscreensaver-command -lock
To unbind lock and prevent it from being
validated:
bind[] = MOD+Shift+Delete
spectrwm provides many functions (or
actions) accessed via key or pointer bindings.
The default bindings are listed below:
Button1⟩M-⟨Button1⟩M-⟨Button3⟩M-S-⟨Button3⟩M-S-⟨Return⟩M-pM-S-qM-qM-⟨Space⟩M-S-\M-S-⟨Space⟩M-hM-lM-,M-.M-S-,M-S-.M-⟨Return⟩M-j,
M-⟨TAB⟩M-k,
M-S-⟨TAB⟩M-mM-uM-S-jM-S-kM-bM-S-bM-xM-S-xM-⟨1-9,0,F1-F12⟩M-S-⟨1-9,0,F1-F12⟩M-⟨Keypad
1-9⟩M-S-⟨Keypad
1-9⟩M-⟨Right⟩M-⟨Left⟩M-⟨Up⟩M-⟨Down⟩M-aM-S-⟨Down⟩M-S-⟨Up⟩M-S-⟨Right⟩M-S-⟨Left⟩M-sM-S-sM-S-vM-tM-S-⟨Delete⟩M-S-iM-wM-S-wM-eM-S-eM-rM-S-rM-vM--M-=M-S--M-S-=M-[M-]M-S-[M-S-]M-S-/M-/M-fThe action names and descriptions are listed below:
focusmoveresizeresize_centeredresize but keep window centered.termquitspectrwm.restartspectrwm.restart_of_dayrestart but configuration file is loaded
in full.cycle_layoutflip_layoutlayout_verticallayout_horizontallayout_maxstack_resetstack_balancemaster_shrinkmaster_growmaster_addmaster_delstack_incstack_decswap_mainfocus_nextfocus_prevfocus_mainfocus_urgentswap_nextswap_prevbar_togglebar_toggle_wswind_delwind_killws_nworkspace_limit.mvws_nworkspace_limit.rg_nmvrg_nmvrg_nextmvrg_prevws_emptyws_empty_movews_nextws_prevws_next_allws_prev_allws_next_movews_prev_movews_priorrg_nextrg_prevrg_move_nextrg_move_prevscreenshot_allscreenshot_windversionfloat_togglelockinitscriconifyuniconifymaximize_togglefullscreen_toggleraisealways_raisewidth_shrinkwidth_growheight_shrinkheight_growmove_leftmove_rightmove_upmove_downname_workspacesearch_workspacesearch_winCustom bindings in the configuration file are specified as follows:
bind[action] =
comboaction is one of the actions listed above
(or empty to unbind) and combo is in the form of zero
or more modifier keys and/or special arguments (Mod1, Shift, MOD, etc.) and
a normal key (b, Space, etc) or a button (Button1 .. Button255), separated
by ‘+’. Multiple key/button
combinations may be bound to the same action.
Special arguments:
MOD example:
bind[reset] = Mod4+q # bind Windows-key + q to reset bind[] = Mod1+q # unbind Alt + q bind[move] = MOD+Button3 # Bind move to M-Button3 bind[] = MOD+Button1 # Unbind default move binding.
ANYMOD example:
bind[focus] = ANYMOD+Button3 bind[move] = MOD+Button3
In the above example,
M-⟨Button3⟩
initiates move and
⟨Button3⟩ pressed with any other
combination of modifiers sets focus to the window/region under the
pointer.
REPLAY example:
bind[focus] = REPLAY+Button3
In the above example, when
⟨Button3⟩ is pressed without any
modifier(s), focus is set to the window under the pointer and the button
press is passed to the window.
To bind non-latin characters such as å or π you must enter the xkb character name instead of the character itself. Run xev(1), 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
To clear all default keyboard bindings and specify your own, see
the keyboard_mapping option.
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.
spectrwm_cz.confspectrwm_es.confspectrwm_fr.confspectrwm_fr_ch.confspectrwm_se.confspectrwm_us.confspectrwm 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:
The quirks themselves are described below:
focus_mode is set to
follow.focus_mode is set to
follow.dialog_ratio (see
CONFIGURATION FILES).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:
In all other cases, no automatic quirks are assigned to the window. Quirks specified in the configuration file override the automatic quirks.
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):
$ wmctrl -i -a 0x4a0000b
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):
$ wmctrl -i -c 0x4a0000b
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.
Sending spectrwm a HUP signal will restart
it.
spectrwm user specific settings.spectrwm global settings.spectrwm was inspired by xmonad &
dwm.
spectrwm was written by:
| August 29, 2018 | Debian |