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