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