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

NAME

4     spectrwm — window manager for X11
5

SYNOPSIS

7     spectrwm
8

DESCRIPTION

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

CONFIGURATION FILES

30     spectrwm first tries to open the user specific file, ~/.spectrwm.conf.
31     If that file is unavailable, it then tries to open the global configura‐
32     tion file /etc/spectrwm.conf.
33
34     The format of the file is
35
36           keyword = setting
37
38     For example:
39
40           color_focus = red
41
42     Enabling or disabling an option is done by using 1 or 0 respectively.
43
44     Colors need to be specified per the XQueryColor(3) specification.
45
46     Comments begin with a #.  When a literal ‘#’ is desired in an option,
47     then it must be escaped with a backslash, i.e. \#
48
49     The file supports the following keywords:
50
51     autorun
52         Launch an application in a specified workspace at start-of-day.
53         Defined in the format ws[idx]:application, e.g. ws[2]:xterm launches
54         an xterm(1) in workspace 2.
55
56         Note that workspace mapping is handled via libswmhack.so.  When
57         autorun spawns windows via a daemon, ensure the daemon is started
58         with the correct LD_PRELOAD in its environment.
59
60         For example, starting urxvtd(1) via xinit(1):
61
62               LD_PRELOAD=/usr/lib/libswmhack.so.0.0 urxvtd -q -o -f
63
64         Spawned programs automatically have LD_PRELOAD set when executed.
65
66     bar_action
67         External script that populates additional information in the status
68         bar, such as battery life.
69
70     bar_at_bottom
71         Place the statusbar at the bottom of each region instead of the top.
72
73     bar_border[x]
74         Border color of the status bar(s) in screen x.
75
76     bar_border_unfocus[x]
77         Border color of the status bar(s) on unfocused region(s) in screen x.
78
79     bar_border_width
80         Set status bar border thickness in pixels.  Disable border by setting
81         to 0.
82
83     bar_color[x]
84         Background color of the status bar(s) in screen x.
85
86     bar_color_selected[x]
87         Background color for selections on the status bar(s) in screen x.
88         Defaults to the value of bar_border.
89
90     bar_enabled
91         Set default bar_toggle state; default is 1.
92
93     bar_enabled_ws[x]
94         Set default bar_toggle_ws state on workspace x; default is 1.
95
96     bar_font
97         Font used in the status bar.  Either Xft or X Logical Font Descrip‐
98         tion (XLFD) may be used to specify fonts.  Fallback fonts may be
99         specified by separating each font with a comma.  If all entries are
100         in XLFD syntax, font set will be used.  If at least one entry is Xft,
101         Xft will be used.  Note that if Xft is in use, only the first font
102         that successfully loads will be used regardless of missing glyphs.
103         The default is to use font set.  Also note that dmenu(1) does not
104         support Xft fonts.
105
106         Xft examples:
107
108               bar_font = Terminus:style=Regular:pixelsize=14:antialias=true
109
110               bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,Terminus:pixelsize=14,-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*
111
112         Font set examples:
113
114               bar_font = -*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*
115
116               bar_font = -*-profont-medium-*-*-*-11-*-*-*-*-*-*-*,-*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*,-*-clean-medium-*-*-*-12-*-*-*-*-*-*-*
117
118         To list the available fonts in your system see fc-list(1) or
119         xlsfonts(1) manpages.  The xfontsel(1) application can help with the
120         XLFD setting.
121
122     bar_font_color[x]
123         Foreground color of the status bar(s) in screen x.
124
125     bar_font_color_selected[x]
126         Foreground color for selections on the status bar(s) in screen x.
127         Defaults to the value of bar_color.
128
129     bar_format
130         Set the bar format string, overriding clock_format and all of the
131         enabled options.  The format is passed through strftime(3) before
132         being used.  It may contain the following character sequences:
133
134               Character sequence    Replaced with
135               +<                    Pad with a space
136               +A                    Output of the external script
137               +C                    Window class (from WM_CLASS)
138               +D                    Workspace name
139               +F                    Floating indicator
140               +I                    Workspace index
141               +L                    Workspace list indicator
142               +M                    Number of iconic (minimized) windows in
143                                                      workspace
144               +N                    Screen number
145               +P                    Window class and instance separated by a
146                                                      colon
147               +R                    Region index
148               +S                    Stacking algorithm
149               +T                    Window instance (from WM_CLASS)
150               +U                    Urgency hint
151               +V                    Program version
152               +W                    Window name (from _NET_WM_NAME/WM_NAME)
153               ++                    A literal ‘+’
154
155         All character sequences may limit its output to a specific length,
156         for example +64A.  By default, no padding/alignment is done in case
157         the length of the replaced string is less than the specified length
158         (64 in the example).  The padding/alignment can be enabled using a
159         '_' character in the sequence.  For example: +_64W, +64_W and +_64_W
160         enable padding before (right alignment), after (left alignment), and
161         both before and after (center alignment) window name, respectively.
162         Any characters that don't match the specification are copied as-is.
163
164     bar_justify
165         Justify the status bar text.  Possible values are left, center, and
166         right.
167
168         Note that if the output is not left justified, it may not be properly
169         aligned in some circumstances, due to the white-spaces in the default
170         static format.  See the bar_format option for more details.
171
172     bind[x]
173         Bind key or button combo to action x.  See the BINDINGS section
174         below.
175
176     border_width
177         Set window border thickness in pixels.  Disable all borders by set‐
178         ting to 0.
179
180     boundary_width
181         Set region containment boundary width in pixels.  This is how far a
182         window must be dragged/resized (with the pointer) beyond the region
183         edge before it is allowed outside the region.  Disable the window
184         containment effect by setting to 0.
185
186     clock_enabled
187         Enable or disable displaying the clock in the status bar.  Disable by
188         setting to 0 so a custom clock could be used in the bar_action
189         script.
190
191     iconic_enabled
192         Display the number of iconic (minimized) windows in the status bar.
193         Enable by setting to 1.
194
195     color_focus
196         Border color of the currently focused window.  Default is red.
197
198     color_focus_maximized
199         Border color of the currently focused, maximized window.  Defaults to
200         the value of color_focus.
201
202     color_unfocus
203         Border color of unfocused windows, default is rgb:88/88/88.
204
205     color_unfocus_maximized
206         Border color of unfocused, maximized windows.  Defaults to the value
207         of color_unfocus.
208
209     dialog_ratio
210         Some applications have dialogue windows that are too small to be use‐
211         ful.  This ratio is the screen size to what they will be resized.
212         For example, 0.6 is 60% of the physical screen size.
213
214     disable_border
215         Remove border when bar is disabled and there is only one window on
216         the region.
217
218     focus_close
219         Window to put focus when the focused window is closed.  Possible val‐
220         ues are first, next, previous (default) and last.  next and previous
221         are relative to the window that is closed.
222
223     focus_close_wrap
224         Whether to allow the focus to jump to the last window when the first
225         window is closed or vice versa.  Disable by setting to 0.
226
227     focus_default
228         Window to put focus when no window has been focused.  Possible values
229         are first and last (default).
230
231     focus_mode
232         Window focus behavior with respect to the pointer.  Possible values:
233
234               default  Set window focus on border crossings caused by cursor
235                        motion and window interaction.
236               follow   Set window focus on all cursor border crossings,
237                        including workspace switches and changes to layout.
238               manual   Set window focus on window interaction only.
239
240     maximize_hide_bar
241         When set to 1, maximize_toggle will also hide/restore the bar visi‐
242         bility of the affected workspace.  Defaults to 0.
243
244     keyboard_mapping
245         Clear all key bindings (not button bindings) and load new bindings
246         from the specified file.  This allows you to load pre-defined key
247         bindings for your keyboard layout.  See the KEYBOARD MAPPING FILES
248         section below for a list of keyboard mapping files that have been
249         provided for several keyboard layouts.
250
251     layout
252         Select layout to use at start-of-day.  Defined in the format
253         ws[idx]:master_grow:master_add:stack_inc:always_raise:stack_mode,
254         e.g. ws[2]:-4:0:1:0:horizontal sets worskspace 2 to the horizontal
255         stack mode, shrinks the master area by 4 ticks and adds one window to
256         the stack, while maintaining default floating window behavior.  Pos‐
257         sible stack_mode values are vertical, vertical_flip, horizontal,
258         horizontal_flip and max.
259
260         See master_grow, master_shrink, master_add, master_del, stack_inc,
261         stack_dec, stack_balance, and always_raise for more information.
262         Note that the stacking options are complicated and have side-effects.
263         One should familiarize oneself with these commands before experiment‐
264         ing with the layout option.
265
266         This setting is not retained at restart.
267
268     modkey
269         Change mod key.  Mod1 is generally the ALT key and Mod4 is the win‐
270         dows key on a PC.
271
272     name
273         Set the name of a workspace at start-of-day.  Defined in the format
274         ws[idx]:name, e.g. ws[1]:Console sets the name of workspace 1 to
275         “Console”.
276
277     program[p]
278         Define new action to spawn a program p.  See the PROGRAMS section
279         below.
280
281     quirk[c[:i[:n]]]
282         Add "quirk" for windows with class c, instance i (optional) and name
283         n (optional).  See the QUIRKS section below.
284
285     region
286         Allocates a custom region, removing any autodetected regions which
287         occupy the same space on the screen.  Defined in the format
288         screen[idx]:widthxheight+x+y, e.g. screen[1]:800x1200+0+0.
289
290         To make a region span multiple monitors, create a region big enough
291         to cover them all, e.g. screen[1]:2048x768+0+0 makes the region span
292         two monitors with 1024x768 resolution sitting one next to the other.
293
294     region_padding
295         Pixel width of empty space within region borders.  Disable by setting
296         to 0.
297
298     spawn_position
299         Position in stack to place newly spawned windows.  Possible values
300         are first, next, previous and last (default).  next and previous are
301         relative to the focused window.
302
303     stack_enabled
304         Enable or disable displaying the current stacking algorithm in the
305         status bar.
306
307     term_width
308         Set a preferred minimum width for the terminal.  If this value is
309         greater than 0, spectrwm will attempt to adjust the font sizes in the
310         terminal to keep the terminal width above this number as the window
311         is resized.  Only xterm(1) is currently supported.  The xterm(1)
312         binary must not be setuid or setgid, which it is by default on most
313         systems.  Users may need to set program[term] (see the PROGRAMS sec‐
314         tion) to use an alternate copy of the xterm(1) binary without the
315         setgid bit set.
316
317     tile_gap
318         Pixel width of empty space between tiled windows.  Negative values
319         cause overlap.  Set this to the opposite of border_width to collapse
320         the border between tiles.  Disable by setting to 0.
321
322     urgent_collapse
323         Minimizes the space consumed by the urgency hint indicator by remov‐
324         ing the placeholders for non-urgent workspaces, the trailing space
325         when there are urgent windows and the default leading space.  Enable
326         by setting to 1.
327
328     urgent_enabled
329         Enable or disable the urgency hint indicator in the status bar.  Note
330         that many terminal emulators require an explicit setting for the bell
331         character to trigger urgency on the window.  In xterm(1), for exam‐
332         ple, one needs to add the following line to .Xdefaults:
333
334               xterm.bellIsUrgent: true
335
336     verbose_layout
337         Enable or disable displaying the current master window count and
338         stack column/row count in the status bar.  Enable by setting to 1.
339         See master_add, master_del, stack_inc and stack_dec for more informa‐
340         tion.
341
342     workspace_clamp
343         Prevents workspaces from being swapped when attempting to switch to a
344         workspace that is mapped to another region.  Use warp_focus if you
345         want to focus on the region containing the workspace and warp_pointer
346         if you want to also send the pointer.  Enable by setting to 1.
347
348     window_class_enabled
349         Enable or disable displaying the window class name (from WM_CLASS) in
350         the status bar.  Enable by setting to 1.
351
352     window_instance_enabled
353         Enable or disable displaying the window instance name (from WM_CLASS)
354         in the status bar.  Enable by setting to 1.
355
356     window_name_enabled
357         Enable or disable displaying the window display name (from
358         _NET_WM_NAME/WM_NAME) in the status bar.  Enable by setting to 1.
359
360         To prevent excessively large window names from pushing the remaining
361         text off the bar, it's limited to 64 characters, by default.  See the
362         bar_format option for more details.
363
364     warp_focus
365         Focus on the target window/workspace/region when clamped.  For exam‐
366         ple, when attempting to switch to a workspace that is mapped on
367         another region and workspace_clamp is enabled, focus on the region
368         with the target workspace.  Enable by setting to 1.
369
370     warp_pointer
371         Centers the pointer on the focused window when using bindings to
372         change focus, switch workspaces, change regions, etc.  Enable by set‐
373         ting to 1.
374
375     workspace_indicator
376         Configure the status bar workspace indicator.  One or more of the
377         following options may be specified in a comma-separated list:
378
379               listcurrent     Include the current workspace.
380               listactive      Include workspaces with windows.
381               listempty       Include empty workspaces.
382               listnamed       Include named workspaces.
383               listurgent      Include workspaces with urgent window(s).
384               listall         Include all workspaces.
385               hidecurrent     Always exclude the current workspace from the
386                               list.
387               markcurrent     Indicate the current workspace if it is in the
388                               list.
389               markurgent      Indicate workspaces in the list that contain
390                               urgent window(s).
391               printnames      Display the names of named workspaces in the
392                               list.
393
394         The default is listcurrent,listactive,markcurrent,printnames
395
396     workspace_limit
397         Set the total number of workspaces available.  Minimum is 1, maximum
398         is 22, default is 10.
399

PROGRAMS

401     spectrwm allows you to define custom actions to launch programs of your
402     choice and then bind them the same as with built-in actions.  See the
403     BINDINGS section below.
404
405     Custom programs in the configuration file are specified as follows:
406
407           program[action] = progpath [arg [arg ...]]
408
409     action is any identifier that does not conflict with a built-in action or
410     keyword, progpath is the desired program, and arg is zero or more argu‐
411     ments to the program.
412
413     Remember that when using ‘#’ in your program call, it must be escaped
414     with a backslash, i.e. \#
415
416     The following argument variables will be substituted for values at the
417     time the program is spawned:
418
419           $bar_border
420           $bar_color
421           $bar_color_selected
422           $bar_font
423           $bar_font_color
424           $bar_font_color_selected
425           $color_focus
426           $color_unfocus
427           $dmenu_bottom    -b if bar_at_bottom is enabled.
428           $region_index
429           $workspace_index
430
431     Example:
432
433           program[ff] = /usr/local/bin/firefox http://spectrwm.org/
434           bind[ff] = MOD+Shift+b # Now M-S-b launches firefox
435
436     To cancel the previous, unbind it:
437
438           bind[] = MOD+Shift+b
439
440     Default programs:
441           term             xterm
442           lock             xlock
443           menu             dmenu_run $dmenu_bottom -fn $bar_font -nb
444                            $bar_color -nf $bar_font_color -sb
445                            $bar_color_selected -sf $bar_font_color_selected
446           search           dmenu $dmenu_bottom -i -fn $bar_font -nb
447                            $bar_color -nf $bar_font_color -sb
448                            $bar_color_selected -sf $bar_font_color_selected
449           name_workspace   dmenu $dmenu_bottom -p Workspace -fn $bar_font -nb
450                            $bar_color -nf $bar_font_color -sb
451                            $bar_color_selected -sf $bar_font_color_selected
452           initscr          initscreen.sh        # optional
453           screenshot_all   screenshot.sh full   # optional
454           screenshot_wind  screenshot.sh window # optional
455
456     Note that optional default programs will not be validated unless overrid‐
457     den.  If a default program fails validation, you can resolve the excep‐
458     tion by installing the program, modifying the program call or disabling
459     the program by freeing the respective binding.
460
461     For example, to override lock:
462
463           program[lock] = xscreensaver-command -lock
464
465     To unbind lock and prevent it from being validated:
466
467           bind[] = MOD+Shift+Delete
468

BINDINGS

470     spectrwm provides many functions (or actions) accessed via key or pointer
471     bindings.
472
473     The default bindings are listed below:
474
475Button1⟩           focus
476           M-Button1⟩         move
477           M-Button3⟩         resize
478           M-S-Button3⟩       resize_centered
479           M-S-Return⟩        term
480           M-p                 menu
481           M-S-q               quit
482           M-q                 restart
483           M-Space⟩           cycle_layout
484           M-S-\               flip_layout
485unbound⟩           layout_vertical
486unbound⟩           layout_horizontal
487unbound⟩           layout_max
488           M-S-Space⟩         stack_reset
489unbound⟩           stack_balance
490           M-h                 master_shrink
491           M-l                 master_grow
492           M-,                 master_add
493           M-.                 master_del
494           M-S-,               stack_inc
495           M-S-.               stack_dec
496           M-Return⟩          swap_main
497           M-j, M-TAB⟩        focus_next
498           M-k, M-S-TAB⟩      focus_prev
499           M-m                 focus_main
500           M-u                 focus_urgent
501           M-S-j               swap_next
502           M-S-k               swap_prev
503           M-b                 bar_toggle
504           M-S-b               bar_toggle_ws
505           M-x                 wind_del
506           M-S-x               wind_kill
507           M-1-9,0,F1-F12⟩    ws_⟨1-22
508           M-S-1-9,0,F1-F12⟩  mvws_⟨1-22
509           M-Keypad 1-9⟩      rg_⟨1-9
510           M-S-Keypad 1-9⟩    mvrg_⟨1-9
511unbound⟩           mvrg_next
512unbound⟩           mvrg_prev
513unbound⟩           ws_empty
514unbound⟩           ws_empty_move
515           M-Right⟩           ws_next
516           M-Left⟩            ws_prev
517           M-Up⟩              ws_next_all
518           M-Down⟩            ws_prev_all
519           M-a                 ws_prior
520           M-S-Down⟩          ws_prev_move
521           M-S-Up⟩            ws_next_move
522           M-S-Right⟩         rg_next
523           M-S-Left⟩          rg_prev
524unbound⟩           rg_move_next
525unbound⟩           rg_move_prev
526           M-s                 screenshot_all
527           M-S-s               screenshot_wind
528           M-S-v               version
529           M-t                 float_toggle
530           M-S-Delete⟩        lock
531           M-S-i               initscr
532           M-w                 iconify
533           M-S-w               uniconify
534           M-e                 maximize_toggle
535           M-S-e               fullscreen_toggle
536           M-r                 raise
537           M-S-r               always_raise
538           M-v                 button2
539           M--                 width_shrink
540           M-=                 width_grow
541           M-S--               height_shrink
542           M-S-=               height_grow
543           M-[                 move_left
544           M-]                 move_right
545           M-S-[               move_up
546           M-S-]               move_down
547           M-S-/               name_workspace
548           M-/                 search_workspace
549           M-f                 search_win
550
551     The action names and descriptions are listed below:
552
553           focus               Focus window/region under pointer.
554           move                Move window with pointer while binding is
555                               pressed.
556           resize              Resize window with pointer while binding is
557                               pressed.
558           resize_centered     Same as resize but keep window centered.
559           term                Spawn a new terminal (see PROGRAMS above).
560           menu                Menu (see PROGRAMS above).
561           quit                Quit spectrwm.
562           restart             Restart spectrwm.
563           cycle_layout        Cycle layout.
564           flip_layout         Swap the master and stacking areas.
565           layout_vertical     Switch to vertical layout.
566           layout_horizontal   Switch to horizontal layout.
567           layout_max          Switch to max layout.
568           stack_reset         Reset layout.
569           stack_balance       Balance master/stacking area.
570           master_shrink       Shrink master area.
571           master_grow         Grow master area.
572           master_add          Add windows to master area.
573           master_del          Remove windows from master area.
574           stack_inc           Add columns/rows to stacking area.
575           stack_dec           Remove columns/rows from stacking area.
576           swap_main           Move current window to master area.
577           focus_next          Focus next window in workspace.
578           focus_prev          Focus previous window in workspace.
579           focus_main          Focus on main window in workspace.
580           focus_urgent        Focus on next window with the urgency hint flag
581                               set.  The workspace is switched if needed.
582           swap_next           Swap with next window in workspace.
583           swap_prev           Swap with previous window in workspace.
584           bar_toggle          Toggle overall visibility of status bars.
585           bar_toggle_ws       Toggle status bar on current workspace.
586           wind_del            Delete current window in workspace.
587           wind_kill           Destroy current window in workspace.
588           ws_n                Switch to workspace n, where n is 1 through
589                               workspace_limit.
590           mvws_n              Move current window to workspace n, where n is
591                               1 through workspace_limit.
592           rg_n                Focus on region n, where n is 1 through 9.
593           mvrg_n              Move current window to region n, where n is 1
594                               through 9.
595           mvrg_next           Move current window to workspace in next
596                               region.
597           mvrg_prev           Move current window to workspace in previous
598                               region.
599           ws_empty            Switch to the first empty workspace.
600           ws_empty_move       Switch to the first empty workspace and move
601                               current window.
602           ws_next             Switch to next workspace with a window in it.
603           ws_prev             Switch to previous workspace with a window in
604                               it.
605           ws_next_all         Switch to next workspace.
606           ws_prev_all         Switch to previous workspace.
607           ws_next_move        Switch to next workspace with the current win‐
608                               dow.
609           ws_prev_move        Switch to previous workspace with the current
610                               window.
611           ws_prior            Switch to last visited workspace.
612           rg_next             Switch to next region.
613           rg_prev             Switch to previous region.
614           rg_move_next        Switch region to next screen.
615           rg_move_prev        Switch region to previous screen.
616           screenshot_all      Take screenshot of entire screen (if enabled)
617                               (see PROGRAMS above).
618           screenshot_wind     Take screenshot of selected window (if enabled)
619                               (see PROGRAMS above).
620           version             Toggle version in status bar.
621           float_toggle        Toggle focused window between tiled and float‐
622                               ing.
623           lock                Lock screen (see PROGRAMS above).
624           initscr             Reinitialize physical screens (see PROGRAMS
625                               above).
626           iconify             Minimize (unmap) currently focused window.
627           uniconify           Restore (map) window returned by dmenu(1)
628                               selection.
629           maximize_toggle     Toggle maximization of focused window.
630           fullscreen_toggle   Toggle fullscreen state of focused window.
631           raise               Raise the current window.
632           always_raise        When set tiled windows are allowed to obscure
633                               floating windows.
634           button2             Fake a middle mouse button click (Button2).
635           width_shrink        Shrink the width of a floating window.
636           width_grow          Grow the width of a floating window.
637           height_shrink       Shrink the height of a floating window.
638           height_grow         Grow the height of a floating window.
639           move_left           Move a floating window a step to the left.
640           move_right          Move a floating window a step to the right.
641           move_up             Move a floating window a step upwards.
642           move_down           Move a floating window a step downwards.
643           name_workspace      Name the current workspace.
644           search_workspace    Search for a workspace.
645           search_win          Search the windows in the current workspace.
646
647     Custom bindings in the configuration file are specified as follows:
648
649           bind[action] = combo
650
651     action is one of the actions listed above (or empty to unbind) and combo
652     is in the form of zero or more modifier keys and/or special arguments
653     (Mod1, Shift, MOD, etc.) and a normal key (b, Space, etc) or a button
654     (Button1 .. Button255), separated by ‘+’.  Multiple key/button combina‐
655     tions may be bound to the same action.
656
657     Special arguments:
658           MOD         Substituted for the currently defined modkey.
659           ANYMOD      Select all modifier combinations not handled by another
660                       binding.
661           REPLAY      Reprocess binding press/release events for other pro‐
662                       grams to handle.  Unavailable for move, resize and
663                       resize_centered.
664
665     MOD example:
666
667           bind[reset] = Mod4+q # bind Windows-key + q to reset
668           bind[] = Mod1+q # unbind Alt + q
669           bind[move] = MOD+Button3 # Bind move to M-Button3
670           bind[] = MOD+Button1 # Unbind default move binding.
671
672     ANYMOD example:
673
674           bind[focus] = ANYMOD+Button3
675           bind[move] = MOD+Button3
676
677     In the above example, M-Button3⟩ initiates move and ⟨Button3⟩ pressed
678     with any other combination of modifiers sets focus to the window/region
679     under the pointer.
680
681     REPLAY example:
682
683           bind[focus] = REPLAY+Button3
684
685     In the above example, when ⟨Button3⟩ is pressed without any modifier(s),
686     focus is set to the window under the pointer and the button press is
687     passed to the window.
688
689     To bind non-latin characters such as å or π you must enter the xkb char‐
690     acter name instead of the character itself.  Run xev(1), focus the window
691     and press the specific key and in the terminal output read the symbol
692     name.  In the following example for å:
693
694           KeyPress event, serial 41, synthetic NO, window 0x2600001,
695               root 0x15a, subw 0x0, time 106213808, (11,5), root:(359,823),
696               state 0x0, keycode 24 (keysym 0xe5, aring), same_screen YES,
697               XLookupString gives 2 bytes: (c3 a5) "å"
698               XmbLookupString gives 2 bytes: (c3 a5) "å"
699               XFilterEvent returns: False
700
701     The xkb name is aring.  In other words, in spectrwm.conf add:
702
703           bind[program] = MOD+aring
704

KEYBOARD MAPPING FILES

706     Keyboard mapping files for several keyboard layouts are listed below.
707     These files can be used with the keyboard_mapping setting to load pre-
708     defined key bindings for the specified keyboard layout.
709
710           spectrwm_cz.conf     Czech Republic keyboard layout
711           spectrwm_es.conf     Spanish keyboard layout
712           spectrwm_fr.conf     French keyboard layout
713           spectrwm_fr_ch.conf  Swiss French keyboard layout
714           spectrwm_se.conf     Swedish keyboard layout
715           spectrwm_us.conf     United States keyboard layout
716

QUIRKS

718     spectrwm provides "quirks" which handle windows that must be treated spe‐
719     cially in a tiling window manager, such as some dialogs and fullscreen
720     apps.
721
722     The default quirks are described below:
723
724           Firefox-bin:firefox-bin                 TRANSSZ
725           Firefox:Dialog                          FLOAT
726           Gimp:gimp                               FLOAT + ANYWHERE
727           MPlayer:xv                              FLOAT + FULLSCREEN + FOCUS‐
728                                                   PREV
729           OpenOffice.org 2.4:VCLSalFrame          FLOAT
730           OpenOffice.org 3.1:VCLSalFrame          FLOAT
731           pcb:pcb                                 FLOAT
732           xine:Xine Window                        FLOAT + ANYWHERE
733           xine:xine Panel                         FLOAT + ANYWHERE
734           xine:xine Video Fullscreen Window       FULLSCREEN + FLOAT
735           Xitk:Xitk Combo                         FLOAT + ANYWHERE
736           Xitk:Xine Window                        FLOAT + ANYWHERE
737           XTerm:xterm                             XTERM_FONTADJ
738
739     The quirks themselves are described below:
740
741           ANYWHERE               Allow window to position itself, uncentered.
742           FLOAT                  This window should not be tiled, but allowed
743                                  to float freely.
744           FOCUSONMAP_SINGLE      When the window first appears on the screen,
745                                  change focus to the window if there are no
746                                  other windows on the workspace with the same
747                                  WM_CLASS class/instance value.  Has no
748                                  effect when focus_mode is set to follow.
749           FOCUSPREV              On exit force focus on previously focused
750                                  application not previous application in the
751                                  stack.
752           FULLSCREEN             Remove border to allow window to use full
753                                  region size.
754           IGNOREPID              Ignore the PID when determining the initial
755                                  workspace for a new window.  Especially use‐
756                                  ful for terminal windows that share a
757                                  process.
758           IGNORESPAWNWS          Ignore the spawn workspace when determining
759                                  the initial workspace for a new window.
760           MINIMALBORDER          Remove border when window is unfocused and
761                                  floating.
762           NOFOCUSCYCLE           Remove from normal focus cycle (focus_prev
763                                  or focus_next). The window can still be
764                                  focused using search_win.
765           NOFOCUSONMAP           Don't change focus to the window when it
766                                  first appears on the screen.  Has no effect
767                                  when focus_mode is set to follow.
768           OBEYAPPFOCUSREQ        When an application requests focus on the
769                                  window via a _NET_ACTIVE_WINDOW client mes‐
770                                  sage (source indication of 1), comply with
771                                  the request.  Note that a source indication
772                                  of 0 (unspecified) or 2 (pager) are always
773                                  obeyed.
774           TRANSSZ                Adjusts size on transient windows that are
775                                  too small using dialog_ratio (see
776                                  CONFIGURATION FILES).
777           WS[n]                  Force a new window to appear on workspace n.
778           XTERM_FONTADJ          Adjust xterm(1) fonts when resizing.
779
780     Custom quirks in the configuration file are specified as follows:
781
782           quirk[class[:instance[:name]]] = quirk [+ quirk ...]
783
784     class, instance (optional) and name (optional) are patterns used to
785     determine which window(s) the quirk(s) apply to and quirk is one of the
786     quirks from the list above.
787
788     Note that patterns are interpreted as POSIX Extended Regular Expressions.
789     Any ':', '[' or ']' must be escaped with '\'.  See regex(7) for more
790     information on POSIX Extended Regular Expressions.
791
792     For example:
793
794           quirk[MPlayer] = FLOAT + FULLSCREEN + FOCUSPREV # Float all windows having a class of 'MPlayer'
795           quirk[.*] = FLOAT # Float all windows by default.
796           quirk[.*:.*:.*] = FLOAT # Same as above.
797           quirk[Firefox:Navigator] = FLOAT # Float all Firefox browser windows.
798           quirk[::Console] = FLOAT # Float windows with WM_CLASS not set and a window name of 'Console'.
799           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.
800           quirk[pcb:pcb] = NONE # remove existing quirk
801
802     You can obtain class, instance and name by running xprop(1) and then
803     clicking on the desired window.  In the following example the main window
804     of Firefox was clicked:
805
806           $ xprop | grep -E "^(WM_CLASS|_NET_WM_NAME|WM_NAME)"
807           WM_CLASS(STRING) = "Navigator", "Firefox"
808           WM_NAME(STRING) = "spectrwm - ConformalOpenSource"
809           _NET_WM_NAME(UTF8_STRING) = "spectrwm - ConformalOpenSource"
810
811     Note that xprop(1) displays WM_CLASS as:
812
813           WM_CLASS(STRING) = "<instance>", "<class>"
814
815     In the example above the quirk entry would be:
816
817           quirk[Firefox:Navigator] = FLOAT
818
819     spectrwm also automatically assigns quirks to windows based on the value
820     of the window's _NET_WM_WINDOW_TYPE property as follows:
821
822           _NET_WM_WINDOW_TYPE_DOCK             FLOAT + ANYWHERE
823           _NET_WM_WINDOW_TYPE_TOOLBAR          FLOAT + ANYWHERE
824           _NET_WM_WINDOW_TYPE_UTILITY          FLOAT + ANYWHERE
825           _NET_WM_WINDOW_TYPE_SPLASH           FLOAT
826           _NET_WM_WINDOW_TYPE_DIALOG           FLOAT
827
828     In all other cases, no automatic quirks are assigned to the window.
829     Quirks specified in the configuration file override the automatic quirks.
830

EWMH

832     spectrwm partially implements the Extended Window Manager Hints (EWMH)
833     specification.  This enables controlling windows as well as spectrwm
834     itself from external scripts and programs.  This is achieved by spectrwm
835     responding to certain ClientMessage events.  From the terminal these
836     events can be conveniently sent using tools such as wmctrl(1) and
837     xdotool(1).  For the actual format of these ClientMessage events, see the
838     EWMH specification.
839
840     The id of the currently focused window is stored in the _NET_ACTIVE_WIN‐
841     DOW property of the root window.  This can be used for example to
842     retrieve the title of the currently active window with xprop(1) and
843     grep(1):
844
845           $ WINDOWID=`xprop -root _NET_ACTIVE_WINDOW | grep -o "0x.*"`
846           $ xprop -id $WINDOWID _NET_WM_NAME | grep -o "\".*\""
847
848     A window can be focused by sending a _NET_ACTIVE_WINDOW client message to
849     the root window.  For example, using wmctrl(1) to send the message
850     (assuming 0x4a0000b is the id of the window to be focused):
851
852           $ wmctrl -i -a 0x4a0000b
853
854     Windows can be closed by sending a _NET_CLOSE_WINDOW client message to
855     the root window.  For example, using wmctrl(1) to send the message
856     (assuming 0x4a0000b is the id of the window to be closed):
857
858           $ wmctrl -i -c 0x4a0000b
859
860     Windows can be floated and un-floated by adding or removing the
861     _NET_WM_STATE_ABOVE atom from the _NET_WM_STATE property of the window.
862     This can be achieved by sending a _NET_WM_STATE client message to the
863     root window.  For example, the following toggles the floating state of a
864     window using wmctrl(1) to send the message (assuming 0x4a0000b is the id
865     of the window to be floated or un-floated):
866
867           $ wmctrl -i -r 0x4a0000b -b toggle,_NET_WM_STATE_ABOVE
868
869     Windows can also be iconified and un-iconified by substituting
870     _NET_WM_STATE_HIDDEN for _NET_WM_STATE_ABOVE in the previous example:
871
872           $ wmctrl -i -r 0x4a0000b -b toggle,_NET_WM_STATE_HIDDEN
873
874     Floating windows can also be resized and moved by sending a _NET_MOVERE‐
875     SIZE_WINDOW client message to the root window.  For example, using
876     wmctrl(1) to send the message (assuming 0x4a0000b is the id of the window
877     to be resize/moved):
878
879           $ wmctrl -i -r 0x4a0000b -e 0,100,50,640,480
880
881     This moves the window to (100,50) and resizes it to 640x480.
882
883     Any _NET_MOVERESIZE_WINDOW events received for stacked windows are
884     ignored.
885

SIGNALS

887     Sending spectrwm a HUP signal will restart it.
888

FILES

890     ~/.spectrwm.conf       spectrwm user specific settings.
891     /etc/spectrwm.conf     spectrwm global settings.
892

HISTORY

894     spectrwm was inspired by xmonad & dwm.
895

AUTHORS

897     spectrwm was written by:
898
899           Marco Peereboom ⟨marco@peereboom.us
900           Ryan Thomas McBride ⟨mcbride@countersiege.com
901           Darrin Chandler ⟨dwchandler@stilyagin.com
902           Pierre-Yves Ritschard ⟨pyr@spootnik.org
903           Tuukka Kataja ⟨stuge@xor.fi
904           Jason L. Wright ⟨jason@thought.net
905           Reginald Kennedy ⟨rk@rejii.com
906           Lawrence Teo ⟨lteo@lteo.net
907           Tiago Cunha ⟨tcunha@gmx.com
908           David Hill ⟨dhill@mindcry.org
909
910BSD                              June 20, 2019                             BSD
Impressum