1SPECTRWM(1)               BSD General Commands Manual              SPECTRWM(1)
2

NAME

4     spectrwm — window manager for X11
5

SYNOPSIS

7     spectrwm [-c file] [-v]
8

OPTIONS

10     -c file
11             Specify a configuration file to load instead of scanning for one.
12
13     -v      Print version and exit.
14

DESCRIPTION

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
22     When spectrwm starts up, it reads settings from its configuration file,
23     spectrwm.conf.  See the CONFIGURATION FILES section below.
24
25     The following notation is used throughout this page:
26
27           M       Meta
28           S       Shift
29Name⟩  Named key or button
30
31     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

CONFIGURATION FILES

36     spectrwm looks for the user-configuration file in the following order:
37
38           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
43     If the user-configuration file is not found, spectrwm then looks for the
44     global configuration file in the following order:
45
46           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
52     The format of the file is
53
54           keyword = setting
55
56     For example:
57
58           color_focus = red
59
60     Enabling or disabling an option is done by using 1 or 0 respectively.
61
62     Colors need to be specified per the XQueryColor(3) specification.
63
64     Comments begin with a #.  When a literal ‘#’ is desired in an option,
65     then it must be escaped with a backslash, i.e. \#
66
67     The file supports the following keywords:
68
69     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
74         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
78         For example, starting urxvtd(1) via xinit(1):
79
80               LD_PRELOAD=/usr/lib/libswmhack.so.0.0 urxvtd -q -o -f
81
82         Spawned programs automatically have LD_PRELOAD set when executed.
83
84         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
88               autorun = ws[2]:xterm -name ws2
89               quirk[XTerm:ws2] = WS[2]
90
91     bar_action
92         External script that populates additional information in the status
93         bar, such as battery life.
94
95     bar_action_expand
96         Process bar_format character sequences in bar_action output; default
97         is 0.
98
99     bar_at_bottom
100         Place the statusbar at the bottom of each region instead of the top.
101
102     bar_border[x]
103         Border color of the status bar(s) in screen x.
104
105     bar_border_unfocus[x]
106         Border color of the status bar(s) on unfocused region(s) in screen x.
107
108     bar_border_width
109         Set status bar border thickness in pixels.  Disable border by setting
110         to 0.
111
112     bar_color[x]
113         Background color of the status bar(s) in screen x.
114
115         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
121     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
125     bar_enabled
126         Set default bar_toggle state; default is 1.
127
128     bar_enabled_ws[x]
129         Set default bar_toggle_ws state on workspace x; default is 1.
130
131     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
138         The default is to use font set.
139
140         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
145         Also note that dmenu(1) does not support Xft fonts.
146
147         Xft examples:
148
149               bar_font = Terminus:style=Regular:pixelsize=14:antialias=true
150
151               bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,Terminus:pixelsize=14,-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*
152
153         Font set examples:
154
155               bar_font = -*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*
156
157               bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,-*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*,-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*
158
159         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
163     bar_font_color[x]
164         Foreground color of the status bar(s) in screen x.
165
166         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
172     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
176     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
181     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
186               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
208                                                      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
215                                                      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
230         The currently recognized text markup sequences are:
231
232               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
245         Note that markup sequences in bar_action script output will only be
246         processed if bar_action_expand is enabled.
247
248         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
257     bar_justify
258         Justify the status bar text.  Possible values are left, center, and
259         right.
260
261         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
265     bind[x]
266         Bind key or button combo to action x.  See the BINDINGS section
267         below.
268
269     border_width
270         Set window border thickness in pixels.  Disable all borders by set‐
271         ting to 0.
272
273     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
279     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
284     color_focus
285         Border color of the currently focused window.  Default is red.
286
287     color_focus_maximized
288         Border color of the currently focused, maximized window.  Defaults to
289         the value of color_focus.
290
291     color_unfocus
292         Border color of unfocused windows, default is rgb:88/88/88.
293
294     color_unfocus_maximized
295         Border color of unfocused, maximized windows.  Defaults to the value
296         of color_unfocus.
297
298     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
303     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
309     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
314     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
318     focus_default
319         Window to put focus when no window has been focused.  Possible values
320         are first and last (default).
321
322     focus_mode
323         Window focus behavior with respect to the pointer.  Possible values:
324
325               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
331     iconic_enabled
332         Display the number of iconic (minimized) windows in the status bar.
333         Enable by setting to 1.
334
335     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
342         Note that /dev/null can be specified if you only want to clear bind‐
343         ings.
344
345     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
354         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
360         This setting is not retained at restart.
361
362     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
366     modkey
367         Change mod key.  Mod1 is generally the ALT key and Mod4 is the win‐
368         dows key on a PC.
369
370     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
375     program[p]
376         Define new action to spawn a program p.  See the PROGRAMS section
377         below.
378
379     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
383     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
388         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
392     region_padding
393         Pixel width of empty space within region borders.  Disable by setting
394         to 0.
395
396     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
401     stack_enabled
402         Enable or disable displaying the current stacking algorithm in the
403         status bar.
404
405     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
415     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
420     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
426     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
432               xterm.bellIsUrgent: true
433
434     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
440     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
446     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
451     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
455     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
459     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
463         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
467     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
473     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
477               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
492         The default is listcurrent,listactive,markcurrent,printnames
493
494     workspace_limit
495         Set the total number of workspaces available.  Minimum is 1, maximum
496         is 22, default is 10.
497

PROGRAMS

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
503     Custom programs in the configuration file are specified as follows:
504
505           program[action] = progpath [arg [arg ...]]
506
507     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
511     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
515     Remember that when using ‘#’ in your program call, it must be escaped
516     with a backslash, i.e. \#
517
518     The following argument variables will be substituted for values at the
519     time the program is spawned:
520
521           $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
533     Example:
534
535           program[ff] = /usr/local/bin/firefox http://spectrwm.org/
536           bind[ff] = MOD+Shift+b # Now M-S-b launches firefox
537
538     To cancel the previous, unbind it:
539
540           bind[] = MOD+Shift+b
541
542     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
558     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
563     For example, to override lock:
564
565           program[lock] = xscreensaver-command -lock
566
567     To unbind lock and prevent it from being validated:
568
569           bind[] = MOD+Shift+Delete
570

BINDINGS

572     spectrwm provides many functions (or actions) accessed via key or pointer
573     bindings.
574
575     The default bindings are listed below:
576
577Button1⟩           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
585unbound⟩           restart_of_day
586           M-Space⟩           cycle_layout
587           M-S-\               flip_layout
588unbound⟩           layout_vertical
589unbound⟩           layout_horizontal
590unbound⟩           layout_max
591           M-S-Space⟩         stack_reset
592unbound⟩           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
614unbound⟩           mvrg_next
615unbound⟩           mvrg_prev
616unbound⟩           ws_empty
617unbound⟩           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
627unbound⟩           rg_move_next
628unbound⟩           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
654     The action names and descriptions are listed below:
655
656           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
752     Custom bindings in the configuration file are specified as follows:
753
754           bind[action] = combo
755
756     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
762     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
770     MOD example:
771
772           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
777     ANYMOD example:
778
779           bind[focus] = ANYMOD+Button3
780           bind[move] = MOD+Button3
781
782     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
786     REPLAY example:
787
788           bind[focus] = REPLAY+Button3
789
790     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
794     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
799           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
806     The xkb name is aring.  In other words, in spectrwm.conf add:
807
808           bind[program] = MOD+aring
809
810     To clear all default keyboard bindings and specify your own, see the
811     keyboard_mapping option.
812

KEYBOARD MAPPING FILES

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
818           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

QUIRKS

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
830     The default quirks are described below:
831
832           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
847     The quirks themselves are described below:
848
849           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
888     Custom quirks in the configuration file are specified as follows:
889
890           quirk[class[:instance[:name]]] = quirk [+ quirk ...]
891
892     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
896     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
900     For example:
901
902           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
910     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
914           $ 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
919     Note that xprop(1) displays WM_CLASS as:
920
921           WM_CLASS(STRING) = "<instance>", "<class>"
922
923     In the example above the quirk entry would be:
924
925           quirk[Firefox:Navigator] = FLOAT
926
927     spectrwm also automatically assigns quirks to windows based on the value
928     of the window's _NET_WM_WINDOW_TYPE property as follows:
929
930           _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
936     In all other cases, no automatic quirks are assigned to the window.
937     Quirks specified in the configuration file override the automatic quirks.
938

EWMH

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
948     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
953           $ WINDOWID=`xprop -root _NET_ACTIVE_WINDOW | grep -o "0x.*"`
954           $ xprop -id $WINDOWID _NET_WM_NAME | grep -o "\".*\""
955
956     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
960           $ wmctrl -i -a 0x4a0000b
961
962     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
966           $ wmctrl -i -c 0x4a0000b
967
968     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
975           $ wmctrl -i -r 0x4a0000b -b toggle,_NET_WM_STATE_ABOVE
976
977     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
980           $ wmctrl -i -r 0x4a0000b -b toggle,_NET_WM_STATE_HIDDEN
981
982     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
987           $ wmctrl -i -r 0x4a0000b -e 0,100,50,640,480
988
989     This moves the window to (100,50) and resizes it to 640x480.
990
991     Any _NET_MOVERESIZE_WINDOW events received for stacked windows are
992     ignored.
993

SIGNALS

995     Sending spectrwm a HUP signal will restart it.
996

FILES

998     ~/.spectrwm.conf       spectrwm user specific settings.
999     /etc/spectrwm.conf     spectrwm global settings.
1000

HISTORY

1002     spectrwm was inspired by xmonad & dwm.
1003

AUTHORS

1005     spectrwm was written by:
1006
1007           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
1017
1018BSD                             August 29, 2018                            BSD
Impressum