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