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