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