1SPECTRWM(1) BSD General Commands Manual SPECTRWM(1)
2
4 spectrwm — window manager for X11
5
7 spectrwm
8
10 spectrwm is a minimalistic window manager that tries to stay out of the
11 way so that valuable screen real estate can be used for much more impor‐
12 tant stuff. It has sane defaults and does not require one to learn a
13 language to do any configuration. It was written by hackers for hackers
14 and it strives to be small, compact and fast.
15
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
23 ⟨Name⟩ 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
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
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
470 spectrwm provides many functions (or actions) accessed via key or pointer
471 bindings.
472
473 The default bindings are listed below:
474
475 ⟨Button1⟩ 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
485 ⟨unbound⟩ layout_vertical
486 ⟨unbound⟩ layout_horizontal
487 ⟨unbound⟩ layout_max
488 M-S-⟨Space⟩ stack_reset
489 ⟨unbound⟩ 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⟩
511 ⟨unbound⟩ mvrg_next
512 ⟨unbound⟩ mvrg_prev
513 ⟨unbound⟩ ws_empty
514 ⟨unbound⟩ 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
524 ⟨unbound⟩ rg_move_next
525 ⟨unbound⟩ 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
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
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
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
887 Sending spectrwm a HUP signal will restart it.
888
890 ~/.spectrwm.conf spectrwm user specific settings.
891 /etc/spectrwm.conf spectrwm global settings.
892
894 spectrwm was inspired by xmonad & dwm.
895
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