scrotwm.1

   1 .\"     $scrotwm$
   2 .\"
   3 .\" Copyright (c) 2009 Marco Peereboom <marco@peereboom.us>
   4 .\" Copyright (c) 2009 Darrin Chandler <dwchandler@stilyagin.com>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate$
  19 .Dt SCROTWM 1
  20 .Os
  21 .Sh NAME
  22 .Nm scrotwm
  23 .Nd window manager for X11
  24 .Sh SYNOPSIS
  25 .Nm scrotwm
  26 .Sh DESCRIPTION
  27 .Nm
  28 is a minimalistic window manager that tries to stay out of the way so that
  29 valuable screen real estate can be used for much more important stuff.
  30 It has sane defaults and does not require one to learn a language to do any
  31 configuration.
  32 It was written by hackers for hackers and it strives to be small, compact and
  33 fast.
  34 .Pp
  35 When
  36 .Nm
  37 starts up, it reads settings from its configuration file,
  38 .Pa scrotwm.conf .
  39 See the
  40 .Sx CONFIGURATION FILES
  41 section below.
  42 .Pp
  43 The following notation is used throughout this page:
  44 .Pp
  45 .Bl -tag -width Ds -offset indent -compact
  46 .It Cm M
  47 Meta
  48 .It Cm S
  49 Shift
  50 .It Aq Cm Name
  51 Named key
  52 .It Cm M1
  53 Mouse button 1
  54 .It Cm M3
  55 Mouse button 3
  56 .El
  57 .Pp
  58 .Nm
  59 is very simple in its use.
  60 Most of the actions are initiated via key or mouse bindings.
  61 See the
  62 .Sx BINDINGS
  63 section below for defaults and customizations.
  64 .Sh CONFIGURATION FILES
  65 .Nm
  66 first tries to open the user specific file,
  67 .Pa ~/.scrotwm.conf .
  68 If that file is unavailable,
  69 it then tries to open the global configuration file
  70 .Pa /etc/scrotwm.conf .
  71 .Pp
  72 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
  73 For example:
  74 .Pp
  75 .Dl color_focus = red
  76 .Pp
  77 Enabling or disabling an option is done by using 1 or 0 respectively.
  78 .Pp
  79 The file supports the following keywords:
  80 .Pp
  81 .Bl -tag -width "title_class_enabledXXX" -offset indent -compact
  82 .It Cm autorun
  83 Launch an application in a specified workspace at start-of-day.
  84 Currently this option does not support arguments so if those are required one
  85 must use a wrapper script.
  86 Defined in the format ws[<idx>]:application, e.g. ws[2]:xterm launches and
  87 xterm in workspace 2
  88 .It Cm color_focus
  89 Border color of the currently focussed window.
  90 .It Cm color_unfocus
  91 Border color of unfocussed windows.
  92 .It Cm bar_enabled
  93 Enable or disable status bar.
  94 .It Cm bar_border Ns Bq Ar x
  95 Color of the status bar border in screen
  96 .It Cm bar_border_width
  97 Set status bar border thickness in pixels.
  98 Disable border by setting to 0
  99 .Ar x .
 100 .It Cm bar_color Ns Bq Ar x
 101 Color of the status bar window in screen
 102 .Ar x .
 103 .It Cm bar_font_color Ns Bq Ar x
 104 Color of the font in status bar in screen
 105 .Ar x .
 106 .It Cm bar_font
 107 Status bar font.
 108 .It Cm bar_action
 109 External script that populates additional information in the status bar,
 110 such as battery life.
 111 .It Cm bar_delay
 112 Update frequency, in seconds, of external script that populates the status bar.
 113 .It Cm bar_at_bottom
 114 Place the statusbar at the bottom of each region instead of the top.
 115 .It Cm stack_enabled
 116 Enable or disable displaying the current stacking algorithm in the status bar.
 117 .It Cm clock_enabled
 118 Enable or disable displaying the clock in the status bar.
 119 Disable by setting to 0
 120 so a custom clock could be used in the bar_action script.
 121 .It Cm dialog_ratio
 122 Some applications have dialogue windows that are too small to be useful.
 123 This ratio is the screen size to what they will be resized.
 124 For example, 0.6 is 60% of the physical screen size.
 125 .It Cm region
 126 Allocates a custom region, removing any autodetected regions which occupy the same
 127 space on the screen.
 128 Defined in the format screen[<idx>]:WIDTHxHEIGHT+X+Y,
 129 e.g.\& screen[1]:800x1200+0+0.
 130 .It Cm term_width
 131 Set a preferred minimum width for the terminal
 132 If this value is greater than 0,
 133 .Nm
 134 will attempt to adjust the font sizes in the terminal to keep the terminal
 135 width above this number as the window is resized.
 136 Only
 137 .Xr xterm 1
 138 is currently supported.
 139 The
 140 .Xr xterm 1
 141 binary must not be setuid or setgid, which it is by default on most systems.
 142 Users may need to set program[term] (see the
 143 .Sx PROGRAMS
 144 section) to use an alternate copy of the
 145 .Xr xterm 1
 146 binary without the setgid bit set.
 147 .It Cm title_class_enabled
 148 Enable or disable displaying the window class in the status bar.
 149 Enable by setting to 1
 150 .It Cm title_name_enabled
 151 Enable or disable displaying the window title in the status bar.
 152 Enable by setting to 1
 153 .It Cm window_name_enabled
 154 Enable or disable displaying the window name in the status bar.
 155 Enable by setting to 1
 156 .It Cm modkey
 157 Change mod key.
 158 Mod1 is generally the ALT key and Mod4 is the windows key on a PC.
 159 .It Cm focus_mode
 160 Using a value of follow_cursor will make the window manager focus the window
 161 under the mouse when switching workspaces and creating windows.
 162 .It Cm disable_border
 163 Remove border when bar is disabled and there is only one window on the screen.
 164 .It Cm border_width
 165 Set window border thickness in pixels.
 166 Disable all borders by setting to 0
 167 .It Cm program Ns Bq Ar p
 168 Define new action to spawn a program
 169 .Ar p .
 170 See the
 171 .Sx PROGRAMS
 172 section below.
 173 .It Cm bind Ns Bq Ar x
 174 Bind key combo to action
 175 .Ar x .
 176 See the
 177 .Sx BINDINGS
 178 section below.
 179 .It Cm quirk Ns Bq Ar c:n
 180 Add "quirk" for windows with class
 181 .Ar c
 182 and name
 183 .Ar n .
 184 See the
 185 .Sx QUIRKS
 186 section below.
 187 .El
 188 .Pp
 189 Colors need to be specified per the
 190 .Xr XQueryColor 3
 191 specification and fonts need to be specified per the
 192 .Xr XQueryFont 3
 193 specification.
 194 .Pp
 195 To list the available fonts in your system see
 196 .Xr fc-list 1
 197 or
 198 .Xr xlsfonts 1
 199 manpages.
 200 The
 201 .Xr xfontsel 1
 202 application can help you to show the X Logical Font Description ("XLFD") used
 203 as setting in the keyword bar_font.
 204 .Sh PROGRAMS
 205 .Nm
 206 allows you to define custom actions to launch programs of your choice and then
 207 bind them the same as with built-in actions.
 208 See the
 209 .Sx BINDINGS
 210 section below.
 211 .Pp
 212 The default programs are described below:
 213 .Pp
 214 .Bl -tag -width "screenshot_wind" -offset indent -compact
 215 .It Cm term
 216 xterm
 217 .It Cm screenshot_all
 218 screenshot.sh full
 219 .It Cm screenshot_wind
 220 screenshot.sh window
 221 .It Cm lock
 222 xlock
 223 .It Cm initscr
 224 initscreen.sh
 225 .It Cm menu
 226 dmenu_run \-fn $bar_font \-nb $bar_color \-nf $bar_font_color \-sb $bar_border \-sf $bar_color
 227 .El
 228 .Pp
 229 Custom programs in the configuration file are specified as follows:
 230 .Pp
 231 .Dl program[<name>] = <progpath> [<arg> [... <arg>]]
 232 .Pp
 233 .Aq name
 234 is any identifier that does not conflict with a built-in action or keyword,
 235 .Aq progpath
 236 is the desired program, and
 237 .Aq arg
 238 is zero or more arguments to the program.
 239 .Pp
 240 The following variables represent settable values in
 241 .Nm
 242 (see the
 243 .Sx CONFIGURATION FILES
 244 section above),
 245 and may be used in the
 246 .Aq arg
 247 fields and will be substituted for values at the time the program is spawned:
 248 .Pp
 249 .Bl -tag -width "$bar_font_color" -offset indent -compact
 250 .It Cm $bar_border
 251 .It Cm $bar_color
 252 .It Cm $bar_font
 253 .It Cm $bar_font_color
 254 .It Cm $color_focus
 255 .It Cm $color_unfocus
 256 .El
 257 .Pp
 258 Example:
 259 .Bd -literal -offset indent
 260 program[ff] = /usr/local/bin/firefox http://scrotwm.org/
 261 bind[ff] = Mod+f # Now Mod+F launched firefox
 262 .Ed
 263 .Pp
 264 To undo the previous:
 265 .Bd -literal -offset indent
 266 bind[] = Mod+f
 267 program[ff] =
 268 .Ed
 269 .Pp
 270 .Sh BINDINGS
 271 .Nm
 272 provides many functions (or actions) accessed via key or mouse bindings.
 273 .Pp
 274 The current mouse bindings are described below:
 275 .Pp
 276 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 277 .It Cm M1
 278 Focus window
 279 .It Cm M-M1
 280 Move window
 281 .It Cm M-M3
 282 Resize window
 283 .It Cm M-S-M3
 284 Resize window while maintaining it centered
 285 .El
 286 .Pp
 287 The default key bindings are described below:
 288 .Pp
 289 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 290 .It Cm M-S- Ns Aq Cm Return
 291 term
 292 .It Cm M-p
 293 menu
 294 .It Cm M-S-q
 295 quit
 296 .It Cm M-q
 297 restart
 298 .Nm
 299 .It Cm M- Ns Aq Cm Space
 300 cycle_layout
 301 .It Cm M-S- Ns Aq Cm Space
 302 reset_layout
 303 .It Cm M-h
 304 master_shrink
 305 .It Cm M-l
 306 master_grow
 307 .It Cm M-,
 308 master_add
 309 .It Cm M-.
 310 master_del
 311 .It Cm M-S-,
 312 stack_inc
 313 .It Cm M-S-.
 314 stack_del
 315 .It Cm M- Ns Aq Cm Return
 316 swap_main
 317 .It Xo
 318 .Cm M-j ,
 319 .Cm M- Ns Aq Cm TAB
 320 .Xc
 321 focus_next
 322 .It Xo
 323 .Cm M-k ,
 324 .Cm M-S- Ns Aq Cm TAB
 325 .Xc
 326 focus_prev
 327 .It Cm M-m
 328 focus_main
 329 .It Cm M-S-j
 330 swap_next
 331 .It Cm M-S-k
 332 swap_prev
 333 .It Cm M-b
 334 bar_toggle
 335 .It Cm M-x
 336 wind_del
 337 .It Cm M-S-x
 338 wind_kill
 339 .It Cm M- Ns Aq Ar n
 340 .Ns ws_ Ns Ar n
 341 .It Cm M-S- Ns Aq Ar n
 342 .Ns mvws_ Ns Ar n
 343 .It Cm M- Ns Aq Cm Right
 344 ws_next
 345 .It Cm M- Ns Aq Cm Left
 346 ws_prev
 347 .It Cm M-a
 348 ws_prior
 349 .It Cm M-S- Ns Aq Cm Right
 350 screen_next
 351 .It Cm M-S- Ns Aq Cm Left
 352 screen_prev
 353 .It Cm M-s
 354 screenshot_all
 355 .It Cm M-S-s
 356 screenshot_wind
 357 .It Cm M-S-v
 358 version
 359 .It Cm M-t
 360 float_toggle
 361 .It Cm M-S- Ns Aq Cm Delete
 362 lock
 363 .It Cm M-S-i
 364 initscr
 365 .It Cm M-w
 366 iconify
 367 .It Cm M-S-w
 368 uniconify
 369 .El
 370 .Pp
 371 The action names and descriptions are listed below:
 372 .Pp
 373 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 374 .It Cm term
 375 Spawn a new terminal
 376 (see
 377 .Sx PROGRAMS
 378 above)
 379 .It Cm menu
 380 Menu
 381 (see
 382 .Sx PROGRAMS
 383 above)
 384 .It Cm quit
 385 Quit
 386 .Nm
 387 .It Cm restart
 388 Restart
 389 .Nm
 390 .It Cm cycle_layout
 391 Cycle layout
 392 .It Cm reset_layout
 393 Reset layout
 394 .It Cm master_shrink
 395 Shrink master area
 396 .It Cm master_grow
 397 Grow master area
 398 .It Cm master_add
 399 Add windows to master area
 400 .It Cm master_del
 401 Remove windows from master area
 402 .It Cm stack_inc
 403 Add columns/rows to stacking area
 404 .It Cm stack_del
 405 Remove columns/rows from stacking area
 406 .It Cm swap_main
 407 Move current window to master area
 408 .It Cm focus_next
 409 Focus next window in workspace
 410 .It Cm focus_prev
 411 Focus previous window in workspace
 412 .It Cm focus_main
 413 Focus on main window in workspace
 414 .It Cm swap_next
 415 Swap with next window in workspace
 416 .It Cm swap_prev
 417 Swap with previous window in workspace
 418 .It Cm bar_toggle
 419 Toggle status bar in all workspaces
 420 .It Cm wind_del
 421 Delete current window in workspace
 422 .It Cm wind_kill
 423 Destroy current window in workspace
 424 .It Cm ws_ Ns Ar n
 425 Switch to workspace
 426 .Ar n ,
 427 where
 428 .Ar n
 429 is 1 through 10
 430 .It Cm mvws_ Ns Ar n
 431 Move current window to workspace
 432 .Ar n ,
 433 where
 434 .Ar n
 435 is 1 through 10
 436 .It Cm ws_next
 437 Switch to next workspace with a window in it
 438 .It Cm ws_prev
 439 Switch to previous workspace with a window in it
 440 .It Cm ws_prior
 441 Switch to last visited workspace
 442 .It Cm screen_next
 443 Move pointer to next region
 444 .It Cm screen_prev
 445 Move pointer to previous region
 446 .It Cm screenshot_all
 447 Take screenshot of entire screen (if enabled)
 448 (see
 449 .Sx PROGRAMS
 450 above)
 451 .It Cm screenshot_wind
 452 Take screenshot of selected window (if enabled)
 453 (see
 454 .Sx PROGRAMS
 455 above)
 456 .It Cm version
 457 Toggle version in status bar
 458 .It Cm float_toggle
 459 Toggle focused window between tiled and floating
 460 .It Cm lock
 461 Lock screen
 462 (see
 463 .Sx PROGRAMS
 464 above)
 465 .It Cm initscr
 466 Reinitialize physical screens
 467 (see
 468 .Sx PROGRAMS
 469 above)
 470 .It Cm iconify
 471 Minimize (unmap) currently focused window.
 472 .It Cm uniconify
 473 Maximize (map) window returned by dmenu selection.
 474 .El
 475 .Pp
 476 Custom bindings in the configuration file are specified as follows:
 477 .Pp
 478 .Dl bind[<action>] = <keys>
 479 .Pp
 480 .Aq action
 481 is one of the actions listed above (or empty) and
 482 .Aq keys
 483 is in the form of zero or more modifier keys
 484 (MOD, Mod1, Shift, etc.) and one or more normal keys
 485 (b, space, etc.), separated by "+".
 486 For example:
 487 .Bd -literal -offset indent
 488 bind[reset] = Mod4+q # bind Windows-key + q to reset
 489 bind[] = Mod1+q # unbind Alt + q
 490 .Ed
 491 .Pp
 492 Multiple key combinations may be bound to the same action.
 493 .Sh QUIRKS
 494 .Nm
 495 provides "quirks" which handle windows that must be treated specially
 496 in a tiling window manager, such as some dialogs and fullscreen apps.
 497 .Pp
 498 The default quirks are described below:
 499 .Pp
 500 .Bl -tag -width "OpenOffice.org N.M:VCLSalFrame<TAB>XXX" -offset indent -compact
 501 .It Firefox\-bin:firefox\-bin
 502 TRANSSZ
 503 .It Firefox:Dialog
 504 FLOAT
 505 .It Gimp:gimp
 506 FLOAT + ANYWHERE
 507 .It MPlayer:xv
 508 FLOAT + FULLSCREEN + FOCUSPREV
 509 .It OpenOffice.org 2.4:VCLSalFrame
 510 FLOAT
 511 .It OpenOffice.org 3.1:VCLSalFrame
 512 FLOAT
 513 .It pcb:pcb
 514 FLOAT
 515 .It xine:Xine Window
 516 FLOAT + ANYWHERE
 517 .It xine:xine Panel
 518 FLOAT + ANYWHERE
 519 .It xine:xine Video Fullscreen Window
 520 FULLSCREEN + FLOAT
 521 .It Xitk:Xitk Combo
 522 FLOAT + ANYWHERE
 523 .It Xitk:Xine Window
 524 FLOAT + ANYWHERE
 525 .It XTerm:xterm
 526 XTERM_FONTADJ
 527 .El
 528 .Pp
 529 The quirks themselves are described below:
 530 .Pp
 531 .Bl -tag -width "XTERM_FONTADJ<TAB>XXX" -offset indent -compact
 532 .It FLOAT
 533 This window should not be tiled, but allowed to float freely.
 534 .It TRANSSZ
 535 Adjusts size on transient windows that are too small using dialog_ratio
 536 (see
 537 .Sx CONFIGURATION FILES ) .
 538 .It ANYWHERE
 539 Allow window to position itself, uncentered.
 540 .It XTERM_FONTADJ
 541 Adjust xterm fonts when resizing.
 542 .It FULLSCREEN
 543 Remove border to allow window to use full screen size.
 544 .It FOCUSPREV
 545 On exit force focus on previously focused application not previous application
 546 in the stack.
 547 .El
 548 .Pp
 549 Custom quirks in the configuration file are specified as follows:
 550 .Pp
 551 .Dl quirk[<class>:<name>] = <quirk> [ + <quirk> ... ]
 552 .Pp
 553 .Aq class
 554 and
 555 .Aq name
 556 specify the window to which the quirk(s) apply, and
 557 .Aq quirk
 558 is one of the quirks from the list above.
 559 For example:
 560 .Bd -literal -offset indent
 561 quirk[MPlayer:xv] = FLOAT + FULLSCREEN + FOCUSPREV
 562 quirk[pcb:pcb] = NONE  # remove existing quirk
 563 .Ed
 564 .Pp
 565 You can obtain
 566 .Aq class
 567 and
 568 .Aq name
 569 by running xprop(1) and then clicking on the desired window.
 570 In the following example the main window of Firefox was clicked:
 571 .Bd -literal -offset indent
 572 $ xprop | grep WM_CLASS
 573 WM_CLASS(STRING) = "Navigator", "Firefox"
 574 .Ed
 575 .Pp
 576 Note that grepping for WM_CLASS flips class and name.
 577 In the example above the quirk entry would be:
 578 .Bd -literal -offset indent
 579 quirk[Firefox:Navigator] = FLOAT
 580 .Ed
 581 .Sh SIGNALS
 582 Sending
 583 .Nm
 584 a HUP signal will retstart it.
 585 .Sh FILES
 586 .Bl -tag -width "/etc/scrotwm.confXXX" -compact
 587 .It Pa ~/.scrotwm.conf
 588 .Nm
 589 user specific settings.
 590 .It Pa /etc/scrotwm.conf
 591 .Nm
 592 global settings.
 593 .El
 594 .Sh HISTORY
 595 .Nm
 596 was inspired by xmonad & dwm.
 597 .Sh AUTHORS
 598 .An -nosplit
 599 .Pp
 600 .Nm
 601 was written by
 602 .An Marco Peereboom Aq marco@peereboom.us ,
 603 .An Ryan Thomas McBride Aq mcbride@countersiege.com
 604 and
 605 .An Darrin Chandler Aq dwchandler@stilyagin.com .
 606 .Sh BUGS
 607 Currently the menu, invoked with
 608 .Cm M-p ,
 609 depends on dmenu.