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

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