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