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