code.delx.au - spectrwm/blob - spectrwm.1

   1 .\" Copyright (c) 2009-2012 Marco Peereboom <marco@peereboom.us>
   2 .\" Copyright (c) 2009 Darrin Chandler <dwchandler@stilyagin.com>
   3 .\" Copyright (c) 2011-2012 Reginald Kennedy <rk@rejii.com>
   4 .\" Copyright (c) 2011-2012 Lawrence Teo <lteo@lteo.net>
   5 .\" Copyright (c) 2011-2012 Tiago Cunha <tcunha@gmx.com>
   6 .\" Copyright (c) 2012 David Hill <dhill@mindcry.org>
   7 .\"
   8 .\" Permission to use, copy, modify, and distribute this software for any
   9 .\" purpose with or without fee is hereby granted, provided that the above
  10 .\" copyright notice and this permission notice appear in all copies.
  11 .\"
  12 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  13 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  14 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  15 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  16 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  17 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  18 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  19 .\"
  20 .Dd $Mdocdate: February 15 2012 $
  21 .Dt SPECTRWM 1
  22 .Os
  23 .Sh NAME
  24 .Nm spectrwm
  25 .Nd window manager for X11
  26 .Sh SYNOPSIS
  27 .Nm spectrwm
  28 .Sh DESCRIPTION
  29 .Nm
  30 is a minimalistic window manager that tries to stay out of the way so that
  31 valuable screen real estate can be used for much more important stuff.
  32 It has sane defaults and does not require one to learn a language to do any
  33 configuration.
  34 It was written by hackers for hackers and it strives to be small, compact and
  35 fast.
  36 .Pp
  37 When
  38 .Nm
  39 starts up, it reads settings from its configuration file,
  40 .Pa spectrwm.conf .
  41 See the
  42 .Sx CONFIGURATION FILES
  43 section below.
  44 .Pp
  45 The following notation is used throughout this page:
  46 .Pp
  47 .Bl -tag -width Ds -offset indent -compact
  48 .It Cm M
  49 Meta
  50 .It Cm S
  51 Shift
  52 .It Aq Cm Name
  53 Named key
  54 .It Cm M1
  55 Mouse button 1
  56 .It Cm M3
  57 Mouse button 3
  58 .El
  59 .Pp
  60 .Nm
  61 is very simple in its use.
  62 Most of the actions are initiated via key or mouse bindings.
  63 See the
  64 .Sx BINDINGS
  65 section below for defaults and customizations.
  66 .Sh CONFIGURATION FILES
  67 .Nm
  68 first tries to open the user specific file,
  69 .Pa ~/.spectrwm.conf .
  70 If that file is unavailable,
  71 it then tries to open the global configuration file
  72 .Pa /etc/spectrwm.conf .
  73 .Pp
  74 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
  75 For example:
  76 .Pp
  77 .Dl color_focus = red
  78 .Pp
  79 Enabling or disabling an option is done by using 1 or 0 respectively.
  80 .Pp
  81 Colors need to be specified per the
  82 .Xr XQueryColor 3
  83 specification.
  84 .Pp
  85 The file supports the following keywords:
  86 .Bl -tag -width 2m
  87 .It Ic autorun
  88 Launch an application in a specified workspace at start-of-day.
  89 Defined in the format ws[<idx>]:application, e.g. ws[2]:xterm launches an
  90 xterm in workspace 2.
  91 .It Ic bar_action
  92 External script that populates additional information in the status bar,
  93 such as battery life.
  94 .It Ic bar_at_bottom
  95 Place the statusbar at the bottom of each region instead of the top.
  96 .It Ic bar_border Ns Bq Ar x
  97 Color of the status bar border in screen
  98 .Ar x .
  99 .It Ic bar_border_width
 100 Set status bar border thickness in pixels.
 101 Disable border by setting to 0.
 102 .It Ic bar_color Ns Bq Ar x
 103 Color of the status bar window in screen
 104 .Ar x .
 105 .It Ic bar_delay
 106 Update frequency, in seconds, of external script that populates the status bar.
 107 .It Ic bar_enabled
 108 Enable or disable status bar.
 109 .It Ic bar_font
 110 Font used in the status bar.  Either Xft or X Logical Font Description (XLFD) may be used
 111 to specify the font.
 112 .Pp
 113 Example for Xft:
 114 .Bd -literal -offset indent
 115 bar_font = Terminus:style=Regular:pixelsize=14:antialias=true
 116 .Ed
 117 .Pp
 118 Example for XLFD:
 119 .Bd -literal -offset indent
 120 bar_font = -*-terminus-medium-*-*-*-14-*-*-*-*-*-*-*
 121 .Ed
 122 .Pp
 123 To list the available fonts in your system see
 124 .Xr fc-list 1
 125 or
 126 .Xr xlsfonts 1
 127 manpages.
 128 The
 129 .Xr xfontsel 1
 130 application can help with the XLFD setting.
 131 .Pp
 132 .It Ic bar_font_color Ns Bq Ar x
 133 Color of the font in status bar in screen
 134 .Ar x .
 135 .It Ic bar_format
 136 Set the bar_format string and overrides
 137 .Ic clock_format
 138 and all of the
 139 .Ic enabled
 140 options.
 141 The format is passed through
 142 .Xr strftime 3
 143 before being used.
 144 It may contain the following character sequences:
 145 .Bl -column "Character sequence" "Replaced with" -offset indent
 146 .It Sy "Character sequence" Ta Sy "Replaced with"
 147 .It Li "+<" Ta "Pad with a space"
 148 .It Li "+A" Ta "Output of the external script"
 149 .It Li "+C" Ta "Window class"
 150 .It Li "+D" Ta "Workspace name"
 151 .It Li "+F" Ta "Floating indicator"
 152 .It Li "+I" Ta "Workspace index"
 153 .It Li "+N" Ta "Screen number"
 154 .It Li "+P" Ta "Window class and title separated by a colon"
 155 .It Li "+S" Ta "Stacking algorithm"
 156 .It Li "+T" Ta "Window title"
 157 .It Li "+U" Ta "Urgency hint"
 158 .It Li "+V" Ta "Program version"
 159 .It Li "+W" Ta "Window name"
 160 .It Li "++" Ta "A literal" Ql +
 161 .El
 162 .Pp
 163 All character sequences may limit its output to a specific length, for example
 164 +64A.
 165 Any characters that don't match the specification are copied as-is.
 166 .It Ic bar_justify
 167 Justify the status bar text. Possible values are
 168 .Pa left ,
 169 .Pa center ,
 170 and
 171 .Pa right .
 172 .Pp
 173 Note that if the output is not
 174 .Pa left
 175 justified, it may not be properly aligned in some circumstances, due to the
 176 white-spaces in the default static format.
 177 See the
 178 .Ic bar_format
 179 option for more details.
 180 .It Ic bind Ns Bq Ar x
 181 Bind key combo to action
 182 .Ar x .
 183 See the
 184 .Sx BINDINGS
 185 section below.
 186 .It Ic border_width
 187 Set window border thickness in pixels.
 188 Disable all borders by setting to 0.
 189 .It Ic clock_enabled
 190 Enable or disable displaying the clock in the status bar.
 191 Disable by setting to 0
 192 so a custom clock could be used in the
 193 .Pa bar_action
 194 script.
 195 .It Ic color_focus
 196 Border color of the currently focussed window.
 197 .It Ic color_unfocus
 198 Border color of unfocussed windows.
 199 .It Ic dialog_ratio
 200 Some applications have dialogue windows that are too small to be useful.
 201 This ratio is the screen size to what they will be resized.
 202 For example, 0.6 is 60% of the physical screen size.
 203 .It Ic disable_border
 204 Remove border when bar is disabled and there is only one window on the screen.
 205 .It Ic focus_close
 206 Window to put focus when the focused window is closed.
 207 Possible values are
 208 .Pa first ,
 209 .Pa next ,
 210 .Pa previous
 211 (default) and
 212 .Pa last .
 213 .Pa next
 214 and
 215 .Pa previous
 216 are relative to the window that is closed.
 217 .It Ic focus_close_wrap
 218 Whether to allow the focus to jump to the last window when the first window is
 219 closed or vice versa.
 220 Disable by setting to 0.
 221 .It Ic focus_default
 222 Window to put focus when no window has been focused.
 223 Possible values are
 224 .Pa first
 225 and
 226 .Pa last
 227 (default).
 228 .It Ic focus_mode
 229 Using a value of
 230 .Pa follow_cursor
 231 will make the window manager focus the window
 232 under the mouse when switching workspaces and creating windows.
 233 .It Ic keyboard_mapping
 234 Clear all key bindings and load new key bindings from the specified file.
 235 This allows you to load pre-defined key bindings for your keyboard layout.
 236 See the
 237 .Sx KEYBOARD MAPPING FILES
 238 section below for a list of keyboard mapping files that have been provided
 239 for several keyboard layouts.
 240 .It Ic layout
 241 Select layout to use at start-of-day.
 242 Defined in the format
 243 ws[idx]:master_grow:master_add:stack_inc:layout:always_raise:stack_mode, e.g.
 244 ws[2]:-4:0:1:0:horizontal sets worskspace 2 to the horizontal stack mode and
 245 shrinks the master area by 4 ticks and adds one window to the stack, while
 246 maintaining default floating window behavior.
 247 Possible stack_mode values are
 248 .Pa vertical ,
 249 .Pa vertical_flip ,
 250 .Pa horizontal ,
 251 .Pa horizontal_flip
 252 and
 253 .Pa fullscreen .
 254 .Pp
 255 See
 256 .Pa master_grow ,
 257 .Pa master_shrink ,
 258 .Pa master_add ,
 259 .Pa master_del ,
 260 .Pa stack_inc ,
 261 .Pa stack_dec ,
 262 and
 263 .Pa always_raise
 264 for more information.
 265 Note that the stacking options are complicated and have side-effects.
 266 One should familiarize oneself with these commands before experimenting with the
 267 .Pa layout
 268 option.
 269 .Pp
 270 This setting is not retained at restart.
 271 .It Ic modkey
 272 Change mod key.
 273 Mod1 is generally the ALT key and Mod4 is the windows key on a PC.
 274 .It Ic program Ns Bq Ar p
 275 Define new action to spawn a program
 276 .Ar p .
 277 See the
 278 .Sx PROGRAMS
 279 section below.
 280 .It Ic quirk Ns Bq Ar c:n
 281 Add "quirk" for windows with class
 282 .Ar c
 283 and name
 284 .Ar n .
 285 See the
 286 .Sx QUIRKS
 287 section below.
 288 .It Ic region
 289 Allocates a custom region, removing any autodetected regions which occupy the same
 290 space on the screen.
 291 Defined in the format screen[<idx>]:WIDTHxHEIGHT+X+Y,
 292 e.g.\& screen[1]:800x1200+0+0.
 293 .Pp
 294 To make a screen span multiple monitors, create a region big enough to cover
 295 them all, e.g. screen[1]:2048x768+0+0 makes the screen span two monitors with
 296 1024x768 resolution sitting one next to the other.
 297 .It Ic spawn_position
 298 Position in stack to place newly spawned windows.
 299 Possible values are
 300 .Pa first ,
 301 .Pa next ,
 302 .Pa previous
 303 and
 304 .Pa last
 305 (default).
 306 .Pa next
 307 and
 308 .Pa previous
 309 are relative to the focused window.
 310 .It Ic stack_enabled
 311 Enable or disable displaying the current stacking algorithm in the status bar.
 312 .It Ic term_width
 313 Set a preferred minimum width for the terminal.
 314 If this value is greater than 0,
 315 .Nm
 316 will attempt to adjust the font sizes in the terminal to keep the terminal
 317 width above this number as the window is resized.
 318 Only
 319 .Xr xterm 1
 320 is currently supported.
 321 The
 322 .Xr xterm 1
 323 binary must not be setuid or setgid, which it is by default on most systems.
 324 Users may need to set program[term] (see the
 325 .Sx PROGRAMS
 326 section) to use an alternate copy of the
 327 .Xr xterm 1
 328 binary without the setgid bit set.
 329 .It Ic title_class_enabled
 330 Enable or disable displaying the window class in the status bar.
 331 Enable by setting to 1.
 332 .It Ic title_name_enabled
 333 Enable or disable displaying the window title in the status bar.
 334 Enable by setting to 1.
 335 .It Ic urgent_enabled
 336 Enable or disable the urgency hint.
 337 Note that many terminal emulators require this to be enabled for it to
 338 propagate.
 339 In xterm, for example, one needs to add the following line
 340 .Pa xterm.bellIsUrgent: true
 341 to
 342 .Pa .Xdefaults .
 343 .It Ic verbose_layout
 344 Enable or disable displaying the current master and stack values in the status
 345 bar.
 346 Enable by setting to 1.
 347 .It Ic window_name_enabled
 348 Enable or disable displaying the window name in the status bar.
 349 Enable by setting to 1.
 350 .Pp
 351 To prevent excessively large window names from pushing the remaining text off
 352 the screen, it's limited to 64 characters, by default.
 353 See the
 354 .Ic bar_format
 355 option for more details.
 356 .It Ic workspace_limit
 357 Set the total number of workspaces available.  Minimum is 1, maximum is 22, default is 10.
 358 .El
 359 .Sh PROGRAMS
 360 .Nm
 361 allows you to define custom actions to launch programs of your choice and then
 362 bind them the same as with built-in actions.
 363 See the
 364 .Sx BINDINGS
 365 section below.
 366 .Pp
 367 The default programs are described below:
 368 .Pp
 369 .Bl -tag -width "screenshot_wind" -offset indent -compact
 370 .It Cm term
 371 xterm
 372 .It Cm screenshot_all
 373 screenshot.sh full
 374 .It Cm screenshot_wind
 375 screenshot.sh window
 376 .It Cm lock
 377 xlock
 378 .It Cm initscr
 379 initscreen.sh
 380 .It Cm menu
 381 dmenu_run \-fn $bar_font \-nb $bar_color \-nf $bar_font_color \-sb $bar_border \-sf $bar_color
 382 .El
 383 .Pp
 384 Custom programs in the configuration file are specified as follows:
 385 .Pp
 386 .Dl program[<name>] = <progpath> [<arg> [... <arg>]]
 387 .Pp
 388 .Aq name
 389 is any identifier that does not conflict with a built-in action or keyword,
 390 .Aq progpath
 391 is the desired program, and
 392 .Aq arg
 393 is zero or more arguments to the program.
 394 .Pp
 395 The following variables represent settable values in
 396 .Nm
 397 (see the
 398 .Sx CONFIGURATION FILES
 399 section above),
 400 and may be used in the
 401 .Aq arg
 402 fields and will be substituted for values at the time the program is spawned:
 403 .Pp
 404 .Bl -tag -width "$bar_font_color" -offset indent -compact
 405 .It Cm $bar_border
 406 .It Cm $bar_color
 407 .It Cm $bar_font
 408 .It Cm $bar_font_color
 409 .It Cm $color_focus
 410 .It Cm $color_unfocus
 411 .El
 412 .Pp
 413 Example:
 414 .Bd -literal -offset indent
 415 program[ff] = /usr/local/bin/firefox http://spectrwm.org/
 416 bind[ff] = Mod+Shift+b # Now Mod+Shift+B launches firefox
 417 .Ed
 418 .Pp
 419 To undo the previous:
 420 .Bd -literal -offset indent
 421 bind[] = Mod+Shift+b
 422 program[ff] =
 423 .Ed
 424 .Sh BINDINGS
 425 .Nm
 426 provides many functions (or actions) accessed via key or mouse bindings.
 427 .Pp
 428 The current mouse bindings are described below:
 429 .Pp
 430 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 431 .It Cm M1
 432 Focus window
 433 .It Cm M-M1
 434 Move window
 435 .It Cm M-M3
 436 Resize window
 437 .It Cm M-S-M3
 438 Resize window while maintaining it centered
 439 .El
 440 .Pp
 441 The default key bindings are described below:
 442 .Pp
 443 .Bl -tag -width "M-j, M-<TAB>XXXXXX" -offset indent -compact
 444 .It Cm M-S- Ns Aq Cm Return
 445 term
 446 .It Cm M-p
 447 menu
 448 .It Cm M-S-q
 449 quit
 450 .It Cm M-q
 451 restart
 452 .It Cm M- Ns Aq Cm Space
 453 cycle_layout
 454 .It Cm M-S- Ns Aq Cm \e
 455 flip_layout
 456 .It Cm M-S- Ns Aq Cm Space
 457 stack_reset
 458 .It Cm M-h
 459 master_shrink
 460 .It Cm M-l
 461 master_grow
 462 .It Cm M-,
 463 master_add
 464 .It Cm M-.
 465 master_del
 466 .It Cm M-S-,
 467 stack_inc
 468 .It Cm M-S-.
 469 stack_dec
 470 .It Cm M- Ns Aq Cm Return
 471 swap_main
 472 .It Xo
 473 .Cm M-j ,
 474 .Cm M- Ns Aq Cm TAB
 475 .Xc
 476 focus_next
 477 .It Xo
 478 .Cm M-k ,
 479 .Cm M-S- Ns Aq Cm TAB
 480 .Xc
 481 focus_prev
 482 .It Cm M-m
 483 focus_main
 484 .It Cm M-S-j
 485 swap_next
 486 .It Cm M-S-k
 487 swap_prev
 488 .It Cm M-b
 489 bar_toggle
 490 .It Cm M-x
 491 wind_del
 492 .It Cm M-S-x
 493 wind_kill
 494 .It Cm M- Ns Aq Ar 1-9,0,F1-F12
 495 .Pf ws_ Aq Ar 1-22
 496 .It Cm M-S- Ns Aq Ar 1-9,0,F1-F12
 497 .Pf mvws_ Ns Aq Ar 1-22
 498 .It Cm M- Ns Aq Cm Right
 499 ws_next
 500 .It Cm M- Ns Aq Cm Left
 501 ws_prev
 502 .It Cm M- Ns Aq Cm Up
 503 ws_next_all
 504 .It Cm M- Ns Aq Cm Down
 505 ws_prev_all
 506 .It Cm M-a
 507 ws_prior
 508 .It Cm M-S- Ns Aq Cm Right
 509 screen_next
 510 .It Cm M-S- Ns Aq Cm Left
 511 screen_prev
 512 .It Cm M-s
 513 screenshot_all
 514 .It Cm M-S-s
 515 screenshot_wind
 516 .It Cm M-S-v
 517 version
 518 .It Cm M-t
 519 float_toggle
 520 .It Cm M-S- Ns Aq Cm Delete
 521 lock
 522 .It Cm M-S-i
 523 initscr
 524 .It Cm M-w
 525 iconify
 526 .It Cm M-S-w
 527 uniconify
 528 .It Cm M-S-r
 529 always_raise
 530 .It Cm M-v
 531 button2
 532 .It Cm M--
 533 width_shrink
 534 .It Cm M-=
 535 width_grow
 536 .It Cm M-S--
 537 height_shrink
 538 .It Cm M-S-=
 539 height_grow
 540 .It Cm M-[
 541 move_left
 542 .It Cm M-]
 543 move_right
 544 .It Cm M-S-[
 545 move_up
 546 .It Cm M-S-]
 547 move_down
 548 .It Cm M-S-/
 549 name_workspace
 550 .It Cm M-/
 551 search_workspace
 552 .It Cm M-f
 553 search_win
 554 .El
 555 .Pp
 556 The action names and descriptions are listed below:
 557 .Pp
 558 .Bl -tag -width "M-j, M-<TAB>XXXX" -offset indent -compact
 559 .It Cm term
 560 Spawn a new terminal
 561 (see
 562 .Sx PROGRAMS
 563 above).
 564 .It Cm menu
 565 Menu
 566 (see
 567 .Sx PROGRAMS
 568 above).
 569 .It Cm quit
 570 Quit
 571 .Nm .
 572 .It Cm restart
 573 Restart
 574 .Nm .
 575 .It Cm cycle_layout
 576 Cycle layout.
 577 .It Cm flip_layout
 578 Swap the master and stacking areas.
 579 .It Cm stack_reset
 580 Reset layout.
 581 .It Cm master_shrink
 582 Shrink master area.
 583 .It Cm master_grow
 584 Grow master area.
 585 .It Cm master_add
 586 Add windows to master area.
 587 .It Cm master_del
 588 Remove windows from master area.
 589 .It Cm stack_inc
 590 Add columns/rows to stacking area.
 591 .It Cm stack_dec
 592 Remove columns/rows from stacking area.
 593 .It Cm swap_main
 594 Move current window to master area.
 595 .It Cm focus_next
 596 Focus next window in workspace.
 597 .It Cm focus_prev
 598 Focus previous window in workspace.
 599 .It Cm focus_main
 600 Focus on main window in workspace.
 601 .It Cm swap_next
 602 Swap with next window in workspace.
 603 .It Cm swap_prev
 604 Swap with previous window in workspace.
 605 .It Cm bar_toggle
 606 Toggle status bar in all workspaces.
 607 .It Cm wind_del
 608 Delete current window in workspace.
 609 .It Cm wind_kill
 610 Destroy current window in workspace.
 611 .It Cm ws_ Ns Ar n
 612 Switch to workspace
 613 .Ar n ,
 614 where
 615 .Ar n
 616 is 1 through workspace_limit.
 617 .It Cm mvws_ Ns Ar n
 618 Move current window to workspace
 619 .Ar n ,
 620 where
 621 .Ar n
 622 is 1 through workspace_limit.
 623 .It Cm ws_next
 624 Switch to next workspace with a window in it.
 625 .It Cm ws_prev
 626 Switch to previous workspace with a window in it.
 627 .It Cm ws_next_all
 628 Switch to next workspace.
 629 .It Cm ws_prev_all
 630 Switch to previous workspace.
 631 .It Cm ws_prior
 632 Switch to last visited workspace.
 633 .It Cm screen_next
 634 Move pointer to next region.
 635 .It Cm screen_prev
 636 Move pointer to previous region.
 637 .It Cm screenshot_all
 638 Take screenshot of entire screen (if enabled)
 639 (see
 640 .Sx PROGRAMS
 641 above).
 642 .It Cm screenshot_wind
 643 Take screenshot of selected window (if enabled)
 644 (see
 645 .Sx PROGRAMS
 646 above).
 647 .It Cm version
 648 Toggle version in status bar.
 649 .It Cm float_toggle
 650 Toggle focused window between tiled and floating.
 651 .It Cm lock
 652 Lock screen
 653 (see
 654 .Sx PROGRAMS
 655 above).
 656 .It Cm initscr
 657 Reinitialize physical screens
 658 (see
 659 .Sx PROGRAMS
 660 above).
 661 .It Cm iconify
 662 Minimize (unmap) currently focused window.
 663 .It Cm uniconify
 664 Maximize (map) window returned by dmenu selection.
 665 .It Cm always_raise
 666 When set tiled windows are allowed to obscure floating windows.
 667 .It Cm button2
 668 Fake a middle mouse button click (mouse button 2).
 669 .It Cm width_shrink
 670 Shrink the width of a floating window.
 671 .It Cm width_grow
 672 Grow the width of a floating window.
 673 .It Cm height_shrink
 674 Shrink the height of a floating window.
 675 .It Cm height_grow
 676 Grow the height of a floating window.
 677 .It Cm move_left
 678 Move a floating window a step to the left.
 679 .It Cm move_right
 680 Move a floating window a step to the right.
 681 .It Cm move_up
 682 Move a floating window a step upwards.
 683 .It Cm move_down
 684 Move a floating window a step downwards.
 685 .It Cm name_workspace
 686 Name the current workspace.
 687 .It Cm search_workspace
 688 Search for a workspace.
 689 .It Cm search_win
 690 Search the windows in the current workspace.
 691 .El
 692 .Pp
 693 Custom bindings in the configuration file are specified as follows:
 694 .Pp
 695 .Dl bind[<action>] = <keys>
 696 .Pp
 697 .Aq action
 698 is one of the actions listed above (or empty) and
 699 .Aq keys
 700 is in the form of zero or more modifier keys
 701 (MOD, Mod1, Shift, etc.) and one or more normal keys
 702 (b, space, etc.), separated by "+".
 703 For example:
 704 .Bd -literal -offset indent
 705 bind[reset] = Mod4+q # bind Windows-key + q to reset
 706 bind[] = Mod1+q # unbind Alt + q
 707 .Ed
 708 .Pp
 709 To use the currently defined
 710 .Ic modkey ,
 711 specify MOD as the modifier key.
 712 .Pp
 713 Multiple key combinations may be bound to the same action.
 714 .Pp
 715 To bind non-latin characters such as å or π you must enter the xkb
 716 character name instead of the character itself. Run xev, focus the window
 717 and press the specific key and in the terminal output read the symbol name.
 718 In the fallowing example for å:
 719 .Bd -literal -offset indent
 720 KeyPress event, serial 41, synthetic NO, window 0x2600001,
 721     root 0x15a, subw 0x0, time 106213808, (11,5), root:(359,823),
 722     state 0x0, keycode 24 (keysym 0xe5, aring), same_screen YES,
 723     XLookupString gives 2 bytes: (c3 a5) "å"
 724     XmbLookupString gives 2 bytes: (c3 a5) "å"
 725     XFilterEvent returns: False
 726 .Ed
 727 .Pp
 728 The xkb name is aring. In other words, in .spectrwm.conf add:
 729 .Bd -literal -offset indent
 730 bind[program] = MOD+aring
 731 .Ed
 732 .Sh KEYBOARD MAPPING FILES
 733 Keyboard mapping files for several keyboard layouts are listed
 734 below.
 735 These files can be used with the
 736 .Pa keyboard_mapping
 737 setting to load pre-defined key bindings for the specified
 738 keyboard layout.
 739 .Pp
 740 .Bl -tag -width "spectrwm_XX.confXXX" -offset indent -compact
 741 .It Cm spectrwm_cz.conf
 742 Czech Republic keyboard layout
 743 .It Cm spectrwm_es.conf
 744 Spanish keyboard layout
 745 .It Cm spectrwm_fr.conf
 746 French keyboard layout
 747 .It Cm spectrwm_fr_ch.conf
 748 Swiss French keyboard layout
 749 .It Cm spectrwm_se.conf
 750 Swedish keyboard layout
 751 .It Cm spectrwm_us.conf
 752 United States keyboard layout
 753 .El
 754 .Sh QUIRKS
 755 .Nm
 756 provides "quirks" which handle windows that must be treated specially
 757 in a tiling window manager, such as some dialogs and fullscreen apps.
 758 .Pp
 759 The default quirks are described below:
 760 .Pp
 761 .Bl -tag -width "OpenOffice.org N.M:VCLSalFrame<TAB>XXX" -offset indent -compact
 762 .It Firefox\-bin:firefox\-bin
 763 TRANSSZ
 764 .It Firefox:Dialog
 765 FLOAT
 766 .It Gimp:gimp
 767 FLOAT + ANYWHERE
 768 .It MPlayer:xv
 769 FLOAT + FULLSCREEN + FOCUSPREV
 770 .It OpenOffice.org 2.4:VCLSalFrame
 771 FLOAT
 772 .It OpenOffice.org 3.1:VCLSalFrame
 773 FLOAT
 774 .It pcb:pcb
 775 FLOAT
 776 .It xine:Xine Window
 777 FLOAT + ANYWHERE
 778 .It xine:xine Panel
 779 FLOAT + ANYWHERE
 780 .It xine:xine Video Fullscreen Window
 781 FULLSCREEN + FLOAT
 782 .It Xitk:Xitk Combo
 783 FLOAT + ANYWHERE
 784 .It Xitk:Xine Window
 785 FLOAT + ANYWHERE
 786 .It XTerm:xterm
 787 XTERM_FONTADJ
 788 .El
 789 .Pp
 790 The quirks themselves are described below:
 791 .Pp
 792 .Bl -tag -width "XTERM_FONTADJ<TAB>XXX" -offset indent -compact
 793 .It FLOAT
 794 This window should not be tiled, but allowed to float freely.
 795 .It TRANSSZ
 796 Adjusts size on transient windows that are too small using dialog_ratio
 797 (see
 798 .Sx CONFIGURATION FILES ) .
 799 .It ANYWHERE
 800 Allow window to position itself, uncentered.
 801 .It XTERM_FONTADJ
 802 Adjust xterm fonts when resizing.
 803 .It FULLSCREEN
 804 Remove border to allow window to use full screen size.
 805 .It FOCUSPREV
 806 On exit force focus on previously focused application not previous application
 807 in the stack.
 808 .El
 809 .Pp
 810 Custom quirks in the configuration file are specified as follows:
 811 .Pp
 812 .Dl quirk[<class>:<name>] = <quirk> [ + <quirk> ... ]
 813 .Pp
 814 .Aq class
 815 and
 816 .Aq name
 817 specify the window to which the quirk(s) apply, and
 818 .Aq quirk
 819 is one of the quirks from the list above.
 820 For example:
 821 .Bd -literal -offset indent
 822 quirk[MPlayer:xv] = FLOAT + FULLSCREEN + FOCUSPREV
 823 quirk[pcb:pcb] = NONE  # remove existing quirk
 824 .Ed
 825 .Pp
 826 You can obtain
 827 .Aq class
 828 and
 829 .Aq name
 830 by running
 831 .Xr xprop 1
 832 and then clicking on the desired window.
 833 In the following example the main window of Firefox was clicked:
 834 .Bd -literal -offset indent
 835 $ xprop | grep WM_CLASS
 836 WM_CLASS(STRING) = "Navigator", "Firefox"
 837 .Ed
 838 .Pp
 839 Note that grepping for WM_CLASS flips class and name.
 840 In the example above the quirk entry would be:
 841 .Bd -literal -offset indent
 842 quirk[Firefox:Navigator] = FLOAT
 843 .Ed
 844 .Pp
 845 .Nm
 846 also automatically assigns quirks to windows based on the value
 847 of the window's _NET_WM_WINDOW_TYPE property as follows:
 848 .Pp
 849 .Bl -tag -width "_NET_WM_WINDOW_TYPE_TOOLBAR<TAB>XXX" -offset indent -compact
 850 .It _NET_WM_WINDOW_TYPE_DOCK
 851 FLOAT + ANYWHERE
 852 .It _NET_WM_WINDOW_TYPE_TOOLBAR
 853 FLOAT + ANYWHERE
 854 .It _NET_WM_WINDOW_TYPE_UTILITY
 855 FLOAT + ANYWHERE
 856 .It _NET_WM_WINDOW_TYPE_SPLASH
 857 FLOAT
 858 .It _NET_WM_WINDOW_TYPE_DIALOG
 859 FLOAT
 860 .El
 861 .Pp
 862 In all other cases, no automatic quirks are assigned to the window.
 863 Quirks specified in the configuration file override the automatic quirks.
 864 .Sh EWMH
 865 .Nm
 866 partially implements the Extended Window Manager Hints (EWMH) specification.
 867 This enables controlling windows as well as
 868 .Nm
 869 itself from external scripts and programs.
 870 This is achieved by
 871 .Nm
 872 responding to certain ClientMessage events.
 873 From the terminal these events
 874 can be conveniently sent using tools such as
 875 .Xr wmctrl 1
 876 and
 877 .Xr xdotool 1 .
 878 For the
 879 actual format of these ClientMessage events, see the EWMH specification.
 880 .Pp
 881 The id of the currently focused window is stored in the _NET_ACTIVE_WINDOW
 882 property of the root window.
 883 This can be used for example to retrieve the
 884 title of the currently active window with
 885 .Xr xprop 1
 886 and
 887 .Xr grep 1 :
 888 .Bd -literal -offset indent
 889 $ WINDOWID=`xprop \-root _NET_ACTIVE_WINDOW | grep \-o "0x.*"`
 890 $ xprop \-id $WINDOWID WM_NAME | grep \-o "\\".*\\""
 891 .Ed
 892 .Pp
 893 A window can be focused by sending a _NET_ACTIVE_WINDOW client message
 894 to the root window.
 895 For example, using
 896 .Xr wmctrl 1
 897 to send the message
 898 (assuming 0x4a0000b is the id of the window to be focused):
 899 .Bd -literal -offset indent
 900 $ wmctrl \-i \-a 0x4a0000b
 901 .Ed
 902 .Pp
 903 Windows can be closed by sending a _NET_CLOSE_WINDOW client message
 904 to the root window.
 905 For example, using
 906 .Xr wmctrl 1
 907 to send the message
 908 (assuming 0x4a0000b is the id of the window to be closed):
 909 .Bd -literal -offset indent
 910 $ wmctrl \-i \-c 0x4a0000b
 911 .Ed
 912 .Pp
 913 Windows can be floated and un-floated by adding or removing the
 914 _NET_WM_STATE_ABOVE atom from the _NET_WM_STATE property of the window.
 915 This can be achieved by sending a _NET_WM_STATE client message to the
 916 root window.
 917 For example, the following toggles the floating state of
 918 a window using
 919 .Xr wmctrl 1
 920 to send the message (assuming 0x4a0000b is the  id of the window floated
 921 or un-floated):
 922 .Bd -literal -offset indent
 923 $ wmctrl \-i \-r 0x4a0000b \-b toggle,_NET_WM_STATE_ABOVE
 924 .Ed
 925 .Pp
 926 Floating windows can also be resized and moved by sending a
 927 _NET_MOVERESIZE_WINDOW client message to the root window.
 928 For example,
 929 using
 930 .Xr wmctrl 1
 931 to send the message (assuming 0x4a0000b is the id of
 932 the window to be resize/moved):
 933 .Bd -literal -offset indent
 934 $ wmctrl \-i \-r 0x4a0000b \-e 0,100,50,640,480
 935 .Ed
 936 .Pp
 937 This moves the window to (100,50) and resizes it to 640x480.
 938 .Pp
 939 Any _NET_MOVERESIZE_WINDOW events received for stacked windows are ignored.
 940 .Sh SIGNALS
 941 Sending
 942 .Nm
 943 a HUP signal will restart it.
 944 .Sh FILES
 945 .Bl -tag -width "/etc/spectrwm.confXXX" -compact
 946 .It Pa ~/.spectrwm.conf
 947 .Nm
 948 user specific settings.
 949 .It Pa /etc/spectrwm.conf
 950 .Nm
 951 global settings.
 952 .El
 953 .Sh HISTORY
 954 .Nm
 955 was inspired by xmonad & dwm.
 956 .Sh AUTHORS
 957 .An -nosplit
 958 .Nm
 959 was written by:
 960 .Pp
 961 .Bl -tag -width "Ryan Thomas McBride Aq mcbride@countersiege.com " -offset indent -compact
 962 .It Cm Marco Peereboom Aq marco@peereboom.us
 963 .It Cm Ryan Thomas McBride Aq mcbride@countersiege.com
 964 .It Cm Darrin Chandler Aq dwchandler@stilyagin.com
 965 .It Cm Pierre-Yves Ritschard Aq pyr@spootnik.org
 966 .It Cm Tuukka Kataja Aq stuge@xor.fi
 967 .It Cm Jason L. Wright Aq jason@thought.net
 968 .It Cm Reginald Kennedy Aq rk@rejii.com
 969 .It Cm Lawrence Teo Aq lteo@lteo.net
 970 .It Cm Tiago Cunha Aq tcunha@gmx.com
 971 .It Cm David Hill Aq dhill@mindcry.org
 972 .El