1SPECTRWM(1) BSD General Commands Manual SPECTRWM(1)
2
4 spectrwm — window manager for X11
5
7 spectrwm
8
10 spectrwm is a minimalistic window manager that tries to stay out of the
11 way so that valuable screen real estate can be used for much more impor‐
12 tant stuff. It has sane defaults and does not require one to learn a
13 language to do any configuration. It was written by hackers for hackers
14 and it strives to be small, compact and fast.
15 When spectrwm starts up, it reads settings from its configuration file,
17 spectrwm.conf. See the CONFIGURATION FILES section below.
18 The following notation is used throughout this page:
20 M Meta
22 S Shift
23 ⟨Name⟩ Named key or button
24 spectrwm is very simple in its use. Most of the actions are initiated
26 via key or pointer bindings. See the BINDINGS section below for defaults
27 and customizations.
28
30 spectrwm looks for the user-configuration file in the following order:
31 1. $XDG_CONFIG_HOME/spectrwm/spectrwm.conf
33 2. ~/.config/spectrwm/spectrwm.conf (if $XDG_CONFIG_HOME is
34 either not set or empty)
35 3. ~/.spectrwm.conf.
36 If the user-configuration file is not found, spectrwm then looks for the
38 global configuration file in the following order:
39 1. $XDG_CONFIG_DIRS/spectrwm/spectrwm.conf (each colon-separated
41 directory in $XDG_CONFIG_DIRS)
42 2. /etc/xdg/spectrwm/spectrwm.conf (if $XDG_CONFIG_DIRS is either
43 not set or empty)
44 3. /etc/spectrwm.conf
45 The format of the file is
47 keyword = setting
49 For example:
51 color_focus = red
53 Enabling or disabling an option is done by using 1 or 0 respectively.
55 Colors need to be specified per the XQueryColor(3) specification.
57 Comments begin with a #. When a literal ‘#’ is desired in an option,
59 then it must be escaped with a backslash, i.e. \#
60 The file supports the following keywords:
62 autorun
64 Launch an application in a specified workspace at start-of-day.
65 Defined in the format ws[idx]:application, e.g. ws[2]:xterm launches
66 an xterm(1) in workspace 2.
67 Note that workspace mapping is handled via libswmhack.so. When
69 autorun spawns windows via a daemon, ensure the daemon is started
70 with the correct LD_PRELOAD in its environment.
71 For example, starting urxvtd(1) via xinit(1):
73 LD_PRELOAD=/usr/lib/libswmhack.so.0.0 urxvtd -q -o -f
75 Spawned programs automatically have LD_PRELOAD set when executed.
77 bar_action
79 External script that populates additional information in the status
80 bar, such as battery life.
81 bar_action_expand
83 Process bar_format character sequences in bar_action output; default
84 is 0.
85 bar_at_bottom
87 Place the statusbar at the bottom of each region instead of the top.
88 bar_border[x]
90 Border color of the status bar(s) in screen x.
91 bar_border_unfocus[x]
93 Border color of the status bar(s) on unfocused region(s) in screen x.
94 bar_border_width
96 Set status bar border thickness in pixels. Disable border by setting
97 to 0.
98 bar_color[x]
100 Background color of the status bar(s) in screen x.
101 A comma separated list of up to 10 colors can be specified. The
103 first value is used as the default background color. Any of these
104 colors can then be selected as a background color in the status bar
105 through the use of the markup sequence +@bg=n; where n is between 0
106 and 9.
107 bar_color_selected[x]
109 Background color for selections on the status bar(s) in screen x.
110 Defaults to the value of bar_border.
111 bar_enabled
113 Set default bar_toggle state; default is 1.
114 bar_enabled_ws[x]
116 Set default bar_toggle_ws state on workspace x; default is 1.
117 bar_font
119 Fonts used in the status bar. Either Xft or X Logical Font Descrip‐
120 tion (XLFD) may be used to specify fonts. Fallback fonts may be
121 specified by separating each font with a comma. If all entries are
122 in XLFD syntax, font set will be used. If at least one entry is Xft,
123 Xft will be used.
124 The default is to use font set.
126 If Xft is used, a comma-separated list of up to 10 fonts can be spec‐
128 ified. The first entry is the default font. Any font defined here
129 can then be selected in the status bar through the use of the markup
130 sequence +@fn=n; where n is between 0 and 9.
131 Also note that dmenu(1) does not support Xft fonts.
133 Xft examples:
135 bar_font = Terminus:style=Regular:pixelsize=14:antialias=true
137 bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,Terminus:pixelsize=14,-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*
139 Font set examples:
141 bar_font = -*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*
143 bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,-*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*,-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*
145 To list the available fonts in your system see fc-list(1) or
147 xlsfonts(1) manpages. The xfontsel(1) application can help with the
148 XLFD setting.
149 bar_font_color[x]
151 Foreground color of the status bar(s) in screen x.
152 A comma separated list of up to 10 colors can be specified. The
154 first value is used as the default foreground color. Any of these
155 colors can then be selected as a foreground color in the status bar
156 through the use of the markup sequence +@fg=n; where n is between 0
157 and 9.
158 bar_font_color_selected[x]
160 Foreground color for selections on the status bar(s) in screen x.
161 Defaults to the value of bar_color.
162 bar_font_pua
164 Specify a font which uses the Unicode Private Use Area (U+E000 ->
165 U+F8FF). Some fonts use these code points to provide special icon
166 glyphs. Available only with Xft fonts.
167 bar_format
169 Set the bar format string, overriding clock_format and all of the
170 enabled options. The format is passed through strftime(3) before
171 being used. It may contain the following character sequences:
172 Character sequence Replaced with
174 +< Pad with a space
175 +A Output of the external script
176 +C Window class (from WM_CLASS)
177 +D Workspace name
178 +F Floating indicator
179 +I Workspace index
180 +L Workspace list indicator
181 +M Number of iconic (minimized) windows in
182 workspace
183 +N Screen number
184 +P Window class and instance separated by a
185 colon
186 +R Region index
187 +S Stacking algorithm
188 +T Window instance (from WM_CLASS)
189 +U Urgency hint
190 +V Program version
191 +W Window name (from _NET_WM_NAME/WM_NAME)
192 +|[weight][justify] Marks the start of a new bar section
193 weight is a positive
195 integer used to allocate
196 horizontal space between
197 'L', 'C' and 'R' sec‐
198 tions (see justify).
199 The default weight is 1.
200 justify can have the
202 value L, C, R or T. L,
203 C, R are for left, cen‐
204 ter and right justified
205 sections respectively.
206 A 'T' section will limit
207 its space usage to fit
208 to the text. If no
209 value is specified for a
210 given section, the set‐
211 ting from bar_justify is
212 used.
213 ++ A literal ‘+’
214 +@ Prefix for text markup sequences
215 The currently recognized text markup sequences are:
217 Character sequence Action
219 +@fn=n; Selects font n (from 0 to 9) from
220 bar_font.
221 +@fg=n; Selects foreground color n (from 0 to 9)
222 from bar_font_color.
223 +@bg=n; Selects background color n (from 0 to 9)
224 from bar_color.
225 +@stp; Stops the interpretation of markup
226 sequences. Any markup sequence
227 found after +@stp will appear
228 as normal characters in the
229 status bar.
230 Note: the effect of a markup sequence will not cross a section bound‐
232 ary.
233 All character sequences may limit its output to a specific length,
235 for example +64A. By default, no padding/alignment is done in case
236 the length of the replaced string is less than the specified length
237 (64 in the example). The padding/alignment can be enabled using a
238 '_' character in the sequence. For example: +_64W, +64_W and +_64_W
239 enable padding before (right alignment), after (left alignment), and
240 both before and after (center alignment) window name, respectively.
241 Any characters that don't match the specification are copied as-is.
242 bar_justify
244 Justify the status bar text. Possible values are left, center, and
245 right.
246 Note that if the output is not left justified, it may not be properly
248 aligned in some circumstances, due to the white-spaces in the default
249 static format. See the bar_format option for more details.
250 bind[x]
252 Bind key or button combo to action x. See the BINDINGS section
253 below.
254 border_width
256 Set window border thickness in pixels. Disable all borders by set‐
257 ting to 0.
258 boundary_width
260 Set region containment boundary width in pixels. This is how far a
261 window must be dragged/resized (with the pointer) beyond the region
262 edge before it is allowed outside the region. Disable the window
263 containment effect by setting to 0.
264 clock_enabled
266 Enable or disable displaying the clock in the status bar. Disable by
267 setting to 0 so a custom clock could be used in the bar_action
268 script.
269 iconic_enabled
271 Display the number of iconic (minimized) windows in the status bar.
272 Enable by setting to 1.
273 color_focus
275 Border color of the currently focused window. Default is red.
276 color_focus_maximized
278 Border color of the currently focused, maximized window. Defaults to
279 the value of color_focus.
280 color_unfocus
282 Border color of unfocused windows, default is rgb:88/88/88.
283 color_unfocus_maximized
285 Border color of unfocused, maximized windows. Defaults to the value
286 of color_unfocus.
287 dialog_ratio
289 Some applications have dialogue windows that are too small to be use‐
290 ful. This ratio is the screen size to what they will be resized.
291 For example, 0.6 is 60% of the physical screen size.
292 disable_border
294 Remove border when bar is disabled and there is only one window on
295 the region. Enable by setting to 1. Setting this to always removes
296 border from lone tiled windows, regardless of the bar being
297 enabled/disabled. Defaults to 0.
298 focus_close
300 Window to put focus when the focused window is closed. Possible val‐
301 ues are first, next, previous (default) and last. next and previous
302 are relative to the window that is closed.
303 focus_close_wrap
305 Whether to allow the focus to jump to the last window when the first
306 window is closed or vice versa. Disable by setting to 0.
307 focus_default
309 Window to put focus when no window has been focused. Possible values
310 are first and last (default).
311 focus_mode
313 Window focus behavior with respect to the pointer. Possible values:
314 default Set window focus on border crossings caused by cursor
316 motion and window interaction.
317 follow Set window focus on all cursor border crossings,
318 including workspace switches and changes to layout.
319 manual Set window focus on window interaction only.
320 maximize_hide_bar
322 When set to 1, maximize_toggle will also hide/restore the bar visi‐
323 bility of the affected workspace. Defaults to 0.
324 keyboard_mapping
326 Clear all key bindings (not button bindings) and load new bindings
327 from the specified file. This allows you to load pre-defined key
328 bindings for your keyboard layout. See the KEYBOARD MAPPING FILES
329 section below for a list of keyboard mapping files that have been
330 provided for several keyboard layouts.
331 layout
333 Select layout to use at start-of-day. Defined in the format
334 ws[idx]:master_grow:master_add:stack_inc:always_raise:stack_mode,
335 e.g. ws[2]:-4:0:1:0:horizontal sets worskspace 2 to the horizontal
336 stack mode, shrinks the master area by 4 ticks and adds one window to
337 the stack, while maintaining default floating window behavior. Pos‐
338 sible stack_mode values are vertical, vertical_flip, horizontal,
339 horizontal_flip and max.
340 See master_grow, master_shrink, master_add, master_del, stack_inc,
342 stack_dec, stack_balance, and always_raise for more information.
343 Note that the stacking options are complicated and have side-effects.
344 One should familiarize oneself with these commands before experiment‐
345 ing with the layout option.
346 This setting is not retained at restart.
348 modkey
350 Change mod key. Mod1 is generally the ALT key and Mod4 is the win‐
351 dows key on a PC.
352 name
354 Set the name of a workspace at start-of-day. Defined in the format
355 ws[idx]:name, e.g. ws[1]:Console sets the name of workspace 1 to
356 “Console”.
357 program[p]
359 Define new action to spawn a program p. See the PROGRAMS section
360 below.
361 quirk[c[:i[:n]]]
363 Add "quirk" for windows with class c, instance i (optional) and name
364 n (optional). See the QUIRKS section below.
365 region
367 Allocates a custom region, removing any autodetected regions which
368 occupy the same space on the screen. Defined in the format
369 screen[idx]:widthxheight+x+y, e.g. screen[1]:800x1200+0+0.
370 To make a region span multiple monitors, create a region big enough
372 to cover them all, e.g. screen[1]:2048x768+0+0 makes the region span
373 two monitors with 1024x768 resolution sitting one next to the other.
374 region_padding
376 Pixel width of empty space within region borders. Disable by setting
377 to 0.
378 spawn_position
380 Position in stack to place newly spawned windows. Possible values
381 are first, next, previous and last (default). next and previous are
382 relative to the focused window.
383 stack_enabled
385 Enable or disable displaying the current stacking algorithm in the
386 status bar.
387 term_width
389 Set a preferred minimum width for the terminal. If this value is
390 greater than 0, spectrwm will attempt to adjust the font sizes in the
391 terminal to keep the terminal width above this number as the window
392 is resized. Only xterm(1) is currently supported. The xterm(1)
393 binary must not be setuid or setgid, which it is by default on most
394 systems. Users may need to set program[term] (see the PROGRAMS sec‐
395 tion) to use an alternate copy of the xterm(1) binary without the
396 setgid bit set.
397 tile_gap
399 Pixel width of empty space between tiled windows. Negative values
400 cause overlap. Set this to the opposite of border_width to collapse
401 the border between tiles. Disable by setting to 0.
402 urgent_collapse
404 Minimizes the space consumed by the urgency hint indicator by remov‐
405 ing the placeholders for non-urgent workspaces, the trailing space
406 when there are urgent windows and the default leading space. Enable
407 by setting to 1.
408 urgent_enabled
410 Enable or disable the urgency hint indicator in the status bar. Note
411 that many terminal emulators require an explicit setting for the bell
412 character to trigger urgency on the window. In xterm(1), for exam‐
413 ple, one needs to add the following line to .Xdefaults:
414 xterm.bellIsUrgent: true
416 verbose_layout
418 Enable or disable displaying the current master window count and
419 stack column/row count in the status bar. Enable by setting to 1.
420 See master_add, master_del, stack_inc and stack_dec for more informa‐
421 tion.
422 workspace_clamp
424 Prevents workspaces from being swapped when attempting to switch to a
425 workspace that is mapped to another region. Use warp_focus if you
426 want to focus on the region containing the workspace and warp_pointer
427 if you want to also send the pointer. Enable by setting to 1.
428 window_class_enabled
430 Enable or disable displaying the window class name (from WM_CLASS) in
431 the status bar. Enable by setting to 1.
432 window_instance_enabled
434 Enable or disable displaying the window instance name (from WM_CLASS)
435 in the status bar. Enable by setting to 1.
436 window_name_enabled
438 Enable or disable displaying the window display name (from
439 _NET_WM_NAME/WM_NAME) in the status bar. Enable by setting to 1.
440 To prevent excessively large window names from pushing the remaining
442 text off the bar, it's limited to 64 characters, by default. See the
443 bar_format option for more details.
444 warp_focus
446 Focus on the target window/workspace/region when clamped. For exam‐
447 ple, when attempting to switch to a workspace that is mapped on
448 another region and workspace_clamp is enabled, focus on the region
449 with the target workspace. Enable by setting to 1.
450 warp_pointer
452 Centers the pointer on the focused window when using bindings to
453 change focus, switch workspaces, change regions, etc. Enable by set‐
454 ting to 1.
455 workspace_indicator
457 Configure the status bar workspace indicator. One or more of the
458 following options may be specified in a comma-separated list:
459 listcurrent Include the current workspace.
461 listactive Include workspaces with windows.
462 listempty Include empty workspaces.
463 listnamed Include named workspaces.
464 listurgent Include workspaces with urgent window(s).
465 listall Include all workspaces.
466 hidecurrent Always exclude the current workspace from the
467 list.
468 markcurrent Indicate the current workspace if it is in the
469 list.
470 markurgent Indicate workspaces in the list that contain
471 urgent window(s).
472 printnames Display the names of named workspaces in the
473 list.
474 The default is listcurrent,listactive,markcurrent,printnames
476 workspace_limit
478 Set the total number of workspaces available. Minimum is 1, maximum
479 is 22, default is 10.
480
482 spectrwm allows you to define custom actions to launch programs of your
483 choice and then bind them the same as with built-in actions. See the
484 BINDINGS section below.
485 Custom programs in the configuration file are specified as follows:
487 program[action] = progpath [arg [arg ...]]
489 action is any identifier that does not conflict with a built-in action or
491 keyword, progpath is the desired program, and arg is zero or more argu‐
492 ments to the program.
493 Remember that when using ‘#’ in your program call, it must be escaped
495 with a backslash, i.e. \#
496 The following argument variables will be substituted for values at the
498 time the program is spawned:
499 $bar_border
501 $bar_color
502 $bar_color_selected
503 $bar_font
504 $bar_font_color
505 $bar_font_color_selected
506 $color_focus
507 $color_unfocus
508 $dmenu_bottom -b if bar_at_bottom is enabled.
509 $region_index
510 $workspace_index
511 Example:
513 program[ff] = /usr/local/bin/firefox http://spectrwm.org/
515 bind[ff] = MOD+Shift+b # Now M-S-b launches firefox
516 To cancel the previous, unbind it:
518 bind[] = MOD+Shift+b
520 Default programs:
522 term xterm
523 lock xlock
524 menu dmenu_run $dmenu_bottom -fn $bar_font -nb
525 $bar_color -nf $bar_font_color -sb
526 $bar_color_selected -sf $bar_font_color_selected
527 search dmenu $dmenu_bottom -i -fn $bar_font -nb
528 $bar_color -nf $bar_font_color -sb
529 $bar_color_selected -sf $bar_font_color_selected
530 name_workspace dmenu $dmenu_bottom -p Workspace -fn $bar_font -nb
531 $bar_color -nf $bar_font_color -sb
532 $bar_color_selected -sf $bar_font_color_selected
533 initscr initscreen.sh # optional
534 screenshot_all screenshot.sh full # optional
535 screenshot_wind screenshot.sh window # optional
536 Note that optional default programs will not be validated unless overrid‐
538 den. If a default program fails validation, you can resolve the excep‐
539 tion by installing the program, modifying the program call or disabling
540 the program by freeing the respective binding.
541 For example, to override lock:
543 program[lock] = xscreensaver-command -lock
545 To unbind lock and prevent it from being validated:
547 bind[] = MOD+Shift+Delete
549
551 spectrwm provides many functions (or actions) accessed via key or pointer
552 bindings.
553 The default bindings are listed below:
555 ⟨Button1⟩ focus
557 M-⟨Button1⟩ move
558 M-⟨Button3⟩ resize
559 M-S-⟨Button3⟩ resize_centered
560 M-S-⟨Return⟩ term
561 M-p menu
562 M-S-q quit
563 M-q restart
564 M-⟨Space⟩ cycle_layout
565 M-S-\ flip_layout
566 ⟨unbound⟩ layout_vertical
567 ⟨unbound⟩ layout_horizontal
568 ⟨unbound⟩ layout_max
569 M-S-⟨Space⟩ stack_reset
570 ⟨unbound⟩ stack_balance
571 M-h master_shrink
572 M-l master_grow
573 M-, master_add
574 M-. master_del
575 M-S-, stack_inc
576 M-S-. stack_dec
577 M-⟨Return⟩ swap_main
578 M-j, M-⟨TAB⟩ focus_next
579 M-k, M-S-⟨TAB⟩ focus_prev
580 M-m focus_main
581 M-u focus_urgent
582 M-S-j swap_next
583 M-S-k swap_prev
584 M-b bar_toggle
585 M-S-b bar_toggle_ws
586 M-x wind_del
587 M-S-x wind_kill
588 M-⟨1-9,0,F1-F12⟩ ws_⟨1-22⟩
589 M-S-⟨1-9,0,F1-F12⟩ mvws_⟨1-22⟩
590 M-⟨Keypad 1-9⟩ rg_⟨1-9⟩
591 M-S-⟨Keypad 1-9⟩ mvrg_⟨1-9⟩
592 ⟨unbound⟩ mvrg_next
593 ⟨unbound⟩ mvrg_prev
594 ⟨unbound⟩ ws_empty
595 ⟨unbound⟩ ws_empty_move
596 M-⟨Right⟩ ws_next
597 M-⟨Left⟩ ws_prev
598 M-⟨Up⟩ ws_next_all
599 M-⟨Down⟩ ws_prev_all
600 M-a ws_prior
601 M-S-⟨Down⟩ ws_prev_move
602 M-S-⟨Up⟩ ws_next_move
603 M-S-⟨Right⟩ rg_next
604 M-S-⟨Left⟩ rg_prev
605 ⟨unbound⟩ rg_move_next
606 ⟨unbound⟩ rg_move_prev
607 M-s screenshot_all
608 M-S-s screenshot_wind
609 M-S-v version
610 M-t float_toggle
611 M-S-⟨Delete⟩ lock
612 M-S-i initscr
613 M-w iconify
614 M-S-w uniconify
615 M-e maximize_toggle
616 M-S-e fullscreen_toggle
617 M-r raise
618 M-S-r always_raise
619 M-v button2
620 M-- width_shrink
621 M-= width_grow
622 M-S-- height_shrink
623 M-S-= height_grow
624 M-[ move_left
625 M-] move_right
626 M-S-[ move_up
627 M-S-] move_down
628 M-S-/ name_workspace
629 M-/ search_workspace
630 M-f search_win
631 The action names and descriptions are listed below:
633 focus Focus window/region under pointer.
635 move Move window with pointer while binding is
636 pressed.
637 resize Resize window with pointer while binding is
638 pressed.
639 resize_centered Same as resize but keep window centered.
640 term Spawn a new terminal (see PROGRAMS above).
641 menu Menu (see PROGRAMS above).
642 quit Quit spectrwm.
643 restart Restart spectrwm.
644 cycle_layout Cycle layout.
645 flip_layout Swap the master and stacking areas.
646 layout_vertical Switch to vertical layout.
647 layout_horizontal Switch to horizontal layout.
648 layout_max Switch to max layout.
649 stack_reset Reset layout.
650 stack_balance Balance master/stacking area.
651 master_shrink Shrink master area.
652 master_grow Grow master area.
653 master_add Add windows to master area.
654 master_del Remove windows from master area.
655 stack_inc Add columns/rows to stacking area.
656 stack_dec Remove columns/rows from stacking area.
657 swap_main Move current window to master area.
658 focus_next Focus next window in workspace.
659 focus_prev Focus previous window in workspace.
660 focus_main Focus on main window in workspace.
661 focus_urgent Focus on next window with the urgency hint flag
662 set. The workspace is switched if needed.
663 swap_next Swap with next window in workspace.
664 swap_prev Swap with previous window in workspace.
665 bar_toggle Toggle overall visibility of status bars.
666 bar_toggle_ws Toggle status bar on current workspace.
667 wind_del Delete current window in workspace.
668 wind_kill Destroy current window in workspace.
669 ws_n Switch to workspace n, where n is 1 through
670 workspace_limit.
671 mvws_n Move current window to workspace n, where n is
672 1 through workspace_limit.
673 rg_n Focus on region n, where n is 1 through 9.
674 mvrg_n Move current window to region n, where n is 1
675 through 9.
676 mvrg_next Move current window to workspace in next
677 region.
678 mvrg_prev Move current window to workspace in previous
679 region.
680 ws_empty Switch to the first empty workspace.
681 ws_empty_move Switch to the first empty workspace and move
682 current window.
683 ws_next Switch to next workspace with a window in it.
684 ws_prev Switch to previous workspace with a window in
685 it.
686 ws_next_all Switch to next workspace.
687 ws_prev_all Switch to previous workspace.
688 ws_next_move Switch to next workspace with the current win‐
689 dow.
690 ws_prev_move Switch to previous workspace with the current
691 window.
692 ws_prior Switch to last visited workspace.
693 rg_next Switch to next region.
694 rg_prev Switch to previous region.
695 rg_move_next Switch region to next screen.
696 rg_move_prev Switch region to previous screen.
697 screenshot_all Take screenshot of entire screen (if enabled)
698 (see PROGRAMS above).
699 screenshot_wind Take screenshot of selected window (if enabled)
700 (see PROGRAMS above).
701 version Toggle version in status bar.
702 float_toggle Toggle focused window between tiled and float‐
703 ing.
704 lock Lock screen (see PROGRAMS above).
705 initscr Reinitialize physical screens (see PROGRAMS
706 above).
707 iconify Minimize (unmap) currently focused window.
708 uniconify Restore (map) window returned by dmenu(1)
709 selection.
710 maximize_toggle Toggle maximization of focused window.
711 fullscreen_toggle Toggle fullscreen state of focused window.
712 raise Raise the current window.
713 always_raise When set tiled windows are allowed to obscure
714 floating windows.
715 button2 Fake a middle mouse button click (Button2).
716 width_shrink Shrink the width of a floating window.
717 width_grow Grow the width of a floating window.
718 height_shrink Shrink the height of a floating window.
719 height_grow Grow the height of a floating window.
720 move_left Move a floating window a step to the left.
721 move_right Move a floating window a step to the right.
722 move_up Move a floating window a step upwards.
723 move_down Move a floating window a step downwards.
724 name_workspace Name the current workspace.
725 search_workspace Search for a workspace.
726 search_win Search the windows in the current workspace.
727 Custom bindings in the configuration file are specified as follows:
729 bind[action] = combo
731 action is one of the actions listed above (or empty to unbind) and combo
733 is in the form of zero or more modifier keys and/or special arguments
734 (Mod1, Shift, MOD, etc.) and a normal key (b, Space, etc) or a button
735 (Button1 .. Button255), separated by ‘+’. Multiple key/button combina‐
736 tions may be bound to the same action.
737 Special arguments:
739 MOD Substituted for the currently defined modkey.
740 ANYMOD Select all modifier combinations not handled by another
741 binding.
742 REPLAY Reprocess binding press/release events for other pro‐
743 grams to handle. Unavailable for move, resize and
744 resize_centered.
745 MOD example:
747 bind[reset] = Mod4+q # bind Windows-key + q to reset
749 bind[] = Mod1+q # unbind Alt + q
750 bind[move] = MOD+Button3 # Bind move to M-Button3
751 bind[] = MOD+Button1 # Unbind default move binding.
752 ANYMOD example:
754 bind[focus] = ANYMOD+Button3
756 bind[move] = MOD+Button3
757 In the above example, M-⟨Button3⟩ initiates move and ⟨Button3⟩ pressed
759 with any other combination of modifiers sets focus to the window/region
760 under the pointer.
761 REPLAY example:
763 bind[focus] = REPLAY+Button3
765 In the above example, when ⟨Button3⟩ is pressed without any modifier(s),
767 focus is set to the window under the pointer and the button press is
768 passed to the window.
769 To bind non-latin characters such as å or π you must enter the xkb char‐
771 acter name instead of the character itself. Run xev(1), focus the window
772 and press the specific key and in the terminal output read the symbol
773 name. In the following example for å:
774 KeyPress event, serial 41, synthetic NO, window 0x2600001,
776 root 0x15a, subw 0x0, time 106213808, (11,5), root:(359,823),
777 state 0x0, keycode 24 (keysym 0xe5, aring), same_screen YES,
778 XLookupString gives 2 bytes: (c3 a5) "å"
779 XmbLookupString gives 2 bytes: (c3 a5) "å"
780 XFilterEvent returns: False
781 The xkb name is aring. In other words, in spectrwm.conf add:
783 bind[program] = MOD+aring
785
787 Keyboard mapping files for several keyboard layouts are listed below.
788 These files can be used with the keyboard_mapping setting to load pre-
789 defined key bindings for the specified keyboard layout.
790 spectrwm_cz.conf Czech Republic keyboard layout
792 spectrwm_es.conf Spanish keyboard layout
793 spectrwm_fr.conf French keyboard layout
794 spectrwm_fr_ch.conf Swiss French keyboard layout
795 spectrwm_se.conf Swedish keyboard layout
796 spectrwm_us.conf United States keyboard layout
797
799 spectrwm provides "quirks" which handle windows that must be treated spe‐
800 cially in a tiling window manager, such as some dialogs and fullscreen
801 apps.
802 The default quirks are described below:
804 Firefox-bin:firefox-bin TRANSSZ
806 Firefox:Dialog FLOAT
807 Gimp:gimp FLOAT + ANYWHERE
808 MPlayer:xv FLOAT + FULLSCREEN + FOCUS‐
809 PREV
810 OpenOffice.org 2.4:VCLSalFrame FLOAT
811 OpenOffice.org 3.1:VCLSalFrame FLOAT
812 pcb:pcb FLOAT
813 xine:Xine Window FLOAT + ANYWHERE
814 xine:xine Panel FLOAT + ANYWHERE
815 xine:xine Video Fullscreen Window FULLSCREEN + FLOAT
816 Xitk:Xitk Combo FLOAT + ANYWHERE
817 Xitk:Xine Window FLOAT + ANYWHERE
818 XTerm:xterm XTERM_FONTADJ
819 The quirks themselves are described below:
821 ANYWHERE Allow window to position itself, uncentered.
823 FLOAT This window should not be tiled, but allowed
824 to float freely.
825 FOCUSONMAP_SINGLE When the window first appears on the screen,
826 change focus to the window if there are no
827 other windows on the workspace with the same
828 WM_CLASS class/instance value. Has no
829 effect when focus_mode is set to follow.
830 FOCUSPREV On exit force focus on previously focused
831 application not previous application in the
832 stack.
833 FULLSCREEN Remove border to allow window to use full
834 region size.
835 IGNOREPID Ignore the PID when determining the initial
836 workspace for a new window. Especially use‐
837 ful for terminal windows that share a
838 process.
839 IGNORESPAWNWS Ignore the spawn workspace when determining
840 the initial workspace for a new window.
841 MINIMALBORDER Remove border when window is unfocused and
842 floating.
843 NOFOCUSCYCLE Remove from normal focus cycle (focus_prev
844 or focus_next). The window can still be
845 focused using search_win.
846 NOFOCUSONMAP Don't change focus to the window when it
847 first appears on the screen. Has no effect
848 when focus_mode is set to follow.
849 OBEYAPPFOCUSREQ When an application requests focus on the
850 window via a _NET_ACTIVE_WINDOW client mes‐
851 sage (source indication of 1), comply with
852 the request. Note that a source indication
853 of 0 (unspecified) or 2 (pager) are always
854 obeyed.
855 TRANSSZ Adjusts size on transient windows that are
856 too small using dialog_ratio (see
857 CONFIGURATION FILES).
858 WS[n] Force a new window to appear on workspace n.
859 XTERM_FONTADJ Adjust xterm(1) fonts when resizing.
860 Custom quirks in the configuration file are specified as follows:
862 quirk[class[:instance[:name]]] = quirk [+ quirk ...]
864 class, instance (optional) and name (optional) are patterns used to
866 determine which window(s) the quirk(s) apply to and quirk is one of the
867 quirks from the list above.
868 Note that patterns are interpreted as POSIX Extended Regular Expressions.
870 Any ':', '[' or ']' must be escaped with '\'. See regex(7) for more
871 information on POSIX Extended Regular Expressions.
872 For example:
874 quirk[MPlayer] = FLOAT + FULLSCREEN + FOCUSPREV # Float all windows having a class of 'MPlayer'
876 quirk[.*] = FLOAT # Float all windows by default.
877 quirk[.*:.*:.*] = FLOAT # Same as above.
878 quirk[Firefox:Navigator] = FLOAT # Float all Firefox browser windows.
879 quirk[::Console] = FLOAT # Float windows with WM_CLASS not set and a window name of 'Console'.
880 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.
881 quirk[pcb:pcb] = NONE # remove existing quirk
882 You can obtain class, instance and name by running xprop(1) and then
884 clicking on the desired window. In the following example the main window
885 of Firefox was clicked:
886 $ xprop | grep -E "^(WM_CLASS|_NET_WM_NAME|WM_NAME)"
888 WM_CLASS(STRING) = "Navigator", "Firefox"
889 WM_NAME(STRING) = "spectrwm - ConformalOpenSource"
890 _NET_WM_NAME(UTF8_STRING) = "spectrwm - ConformalOpenSource"
891 Note that xprop(1) displays WM_CLASS as:
893 WM_CLASS(STRING) = "<instance>", "<class>"
895 In the example above the quirk entry would be:
897 quirk[Firefox:Navigator] = FLOAT
899 spectrwm also automatically assigns quirks to windows based on the value
901 of the window's _NET_WM_WINDOW_TYPE property as follows:
902 _NET_WM_WINDOW_TYPE_DOCK FLOAT + ANYWHERE
904 _NET_WM_WINDOW_TYPE_TOOLBAR FLOAT + ANYWHERE
905 _NET_WM_WINDOW_TYPE_UTILITY FLOAT + ANYWHERE
906 _NET_WM_WINDOW_TYPE_SPLASH FLOAT
907 _NET_WM_WINDOW_TYPE_DIALOG FLOAT
908 In all other cases, no automatic quirks are assigned to the window.
910 Quirks specified in the configuration file override the automatic quirks.
911
913 spectrwm partially implements the Extended Window Manager Hints (EWMH)
914 specification. This enables controlling windows as well as spectrwm
915 itself from external scripts and programs. This is achieved by spectrwm
916 responding to certain ClientMessage events. From the terminal these
917 events can be conveniently sent using tools such as wmctrl(1) and
918 xdotool(1). For the actual format of these ClientMessage events, see the
919 EWMH specification.
920 The id of the currently focused window is stored in the _NET_ACTIVE_WIN‐
922 DOW property of the root window. This can be used for example to
923 retrieve the title of the currently active window with xprop(1) and
924 grep(1):
925 $ WINDOWID=`xprop -root _NET_ACTIVE_WINDOW | grep -o "0x.*"`
927 $ xprop -id $WINDOWID _NET_WM_NAME | grep -o "\".*\""
928 A window can be focused by sending a _NET_ACTIVE_WINDOW client message to
930 the root window. For example, using wmctrl(1) to send the message
931 (assuming 0x4a0000b is the id of the window to be focused):
932 $ wmctrl -i -a 0x4a0000b
934 Windows can be closed by sending a _NET_CLOSE_WINDOW client message to
936 the root window. For example, using wmctrl(1) to send the message
937 (assuming 0x4a0000b is the id of the window to be closed):
938 $ wmctrl -i -c 0x4a0000b
940 Windows can be floated and un-floated by adding or removing the
942 _NET_WM_STATE_ABOVE atom from the _NET_WM_STATE property of the window.
943 This can be achieved by sending a _NET_WM_STATE client message to the
944 root window. For example, the following toggles the floating state of a
945 window using wmctrl(1) to send the message (assuming 0x4a0000b is the id
946 of the window to be floated or un-floated):
947 $ wmctrl -i -r 0x4a0000b -b toggle,_NET_WM_STATE_ABOVE
949 Windows can also be iconified and un-iconified by substituting
951 _NET_WM_STATE_HIDDEN for _NET_WM_STATE_ABOVE in the previous example:
952 $ wmctrl -i -r 0x4a0000b -b toggle,_NET_WM_STATE_HIDDEN
954 Floating windows can also be resized and moved by sending a _NET_MOVERE‐
956 SIZE_WINDOW client message to the root window. For example, using
957 wmctrl(1) to send the message (assuming 0x4a0000b is the id of the window
958 to be resize/moved):
959 $ wmctrl -i -r 0x4a0000b -e 0,100,50,640,480
961 This moves the window to (100,50) and resizes it to 640x480.
963 Any _NET_MOVERESIZE_WINDOW events received for stacked windows are
965 ignored.
966
968 Sending spectrwm a HUP signal will restart it.
969
971 ~/.spectrwm.conf spectrwm user specific settings.
972 /etc/spectrwm.conf spectrwm global settings.
973
975 spectrwm was inspired by xmonad & dwm.
976
978 spectrwm was written by:
979 Marco Peereboom ⟨marco@peereboom.us⟩
981 Ryan Thomas McBride ⟨mcbride@countersiege.com⟩
982 Darrin Chandler ⟨dwchandler@stilyagin.com⟩
983 Pierre-Yves Ritschard ⟨pyr@spootnik.org⟩
984 Tuukka Kataja ⟨stuge@xor.fi⟩
985 Jason L. Wright ⟨jason@thought.net⟩
986 Reginald Kennedy ⟨rk@rejii.com⟩
987 Lawrence Teo ⟨lteo@lteo.net⟩
988 Tiago Cunha ⟨tcunha@gmx.com⟩
989 David Hill ⟨dhill@mindcry.org⟩
990BSD May 10, 2020 BSD