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 .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 Aq Cm Delete
 356 lock
 357 .It Cm M-S-i
 358 initscr
 359 .El
 360 .Pp
 361 The action names and descriptions are listed below:
 362 .Pp
 363 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 364 .It Cm term
 365 Spawn a new terminal
 366 (see
 367 .Sx PROGRAMS
 368 above)
 369 .It Cm menu
 370 Menu
 371 (see
 372 .Sx PROGRAMS
 373 above)
 374 .It Cm quit
 375 Quit
 376 .Nm
 377 .It Cm restart
 378 Restart
 379 .Nm
 380 .It Cm cycle_layout
 381 Cycle layout
 382 .It Cm reset_layout
 383 Reset layout
 384 .It Cm master_shrink
 385 Shrink master area
 386 .It Cm master_grow
 387 Grow master area
 388 .It Cm master_add
 389 Add windows to master area
 390 .It Cm master_del
 391 Remove windows from master area
 392 .It Cm stack_inc
 393 Add columns/rows to stacking area
 394 .It Cm stack_del
 395 Remove columns/rows from stacking area
 396 .It Cm swap_main
 397 Move current window to master area
 398 .It Cm focus_next
 399 Focus next window in workspace
 400 .It Cm focus_prev
 401 Focus previous window in workspace
 402 .It Cm focus_main
 403 Focus on main window in workspace
 404 .It Cm swap_next
 405 Swap with next window in workspace
 406 .It Cm swap_prev
 407 Swap with previous window in workspace
 408 .It Cm bar_toggle
 409 Toggle status bar in all workspaces
 410 .It Cm wind_del
 411 Delete current window in workspace
 412 .It Cm wind_kill
 413 Destroy current window in workspace
 414 .It Cm ws_ Ns Ar n
 415 Switch to workspace
 416 .Ar n ,
 417 where
 418 .Ar n
 419 is 1 through 10
 420 .It Cm mvws_ Ns Ar n
 421 Move current window to workspace
 422 .Ar n ,
 423 where
 424 .Ar n
 425 is 1 through 10
 426 .It Cm ws_next
 427 Switch to next workspace with a window in it
 428 .It Cm ws_prev
 429 Switch to previous workspace with a window in it
 430 .It Cm ws_prior
 431 Switch to last visited workspace
 432 .It Cm screen_next
 433 Move pointer to next region
 434 .It Cm screen_prev
 435 Move pointer to previous region
 436 .It Cm screenshot_all
 437 Take screenshot of entire screen (if enabled)
 438 (see
 439 .Sx PROGRAMS
 440 above)
 441 .It Cm screenshot_wind
 442 Take screenshot of selected window (if enabled)
 443 (see
 444 .Sx PROGRAMS
 445 above)
 446 .It Cm version
 447 Toggle version in status bar
 448 .It Cm float_toggle
 449 Toggle focused window between tiled and floating
 450 .It Cm lock
 451 Lock screen
 452 (see
 453 .Sx PROGRAMS
 454 above)
 455 .It Cm initscr
 456 Reinitialize physical screens
 457 (see
 458 .Sx PROGRAMS
 459 above)
 460 .El
 461 .Pp
 462 Custom bindings in the configuration file are specified as follows:
 463 .Pp
 464 .Dl bind[<action>] = <keys>
 465 .Pp
 466 .Aq action
 467 is one of the actions listed above (or empty) and
 468 .Aq keys
 469 is in the form of zero or more modifier keys
 470 (MOD, Mod1, Shift, etc.) and one or more normal keys
 471 (b, space, etc.), separated by "+".
 472 For example:
 473 .Bd -literal -offset indent
 474 bind[reset] = Mod4+q # bind Windows-key + q to reset
 475 bind[] = Mod1+q # unbind Alt + q
 476 .Ed
 477 .Pp
 478 Multiple key combinations may be bound to the same action.
 479 .Sh QUIRKS
 480 .Nm
 481 provides "quirks" which handle windows that must be treated specially
 482 in a tiling window manager, such as some dialogs and fullscreen apps.
 483 .Pp
 484 The default quirks are described below:
 485 .Pp
 486 .Bl -tag -width "OpenOffice.org N.M:VCLSalFrame<TAB>XXX" -offset indent -compact
 487 .It Firefox\-bin:firefox\-bin
 488 TRANSSZ
 489 .It Firefox:Dialog
 490 FLOAT
 491 .It Gimp:gimp
 492 FLOAT + ANYWHERE
 493 .It MPlayer:xv
 494 FLOAT + FULLSCREEN
 495 .It OpenOffice.org 2.4:VCLSalFrame
 496 FLOAT
 497 .It OpenOffice.org 3.1:VCLSalFrame
 498 FLOAT
 499 .It pcb:pcb
 500 FLOAT
 501 .It xine:Xine Window
 502 FLOAT + ANYWHERE
 503 .It xine:xine Panel
 504 FLOAT + ANYWHERE
 505 .It xine:xine Video Fullscreen Window
 506 FULLSCREEN + FLOAT
 507 .It Xitk:Xitk Combo
 508 FLOAT + ANYWHERE
 509 .It Xitk:Xine Window
 510 FLOAT + ANYWHERE
 511 .It XTerm:xterm
 512 XTERM_FONTADJ
 513 .El
 514 .Pp
 515 The quirks themselves are described below:
 516 .Pp
 517 .Bl -tag -width "XTERM_FONTADJ<TAB>XXX" -offset indent -compact
 518 .It FLOAT
 519 This window should not be tiled, but allowed to float freely.
 520 .It TRANSSZ
 521 Adjusts size on transient windows that are too small using dialog_ratio
 522 (see
 523 .Sx CONFIGURATION FILES ) .
 524 .It ANYWHERE
 525 Allow window to position itself, uncentered.
 526 .It XTERM_FONTADJ
 527 Adjust xterm fonts when resizing.
 528 .It FULLSCREEN
 529 Remove border to allow window to use full screen size.
 530 .El
 531 .Pp
 532 Custom quirks in the configuration file are specified as follows:
 533 .Pp
 534 .Dl quirk[<class>:<name>] = <quirk> [ + <quirk> ... ]
 535 .Pp
 536 .Aq class
 537 and
 538 .Aq name
 539 specify the window to which the quirk(s) apply, and
 540 .Aq quirk
 541 is one of the quirks from the list above.
 542 For example:
 543 .Bd -literal -offset indent
 544 quirk[MPlayer:xv] = FLOAT + FULLSCREEN # let mplayer play
 545 quirk[pcb:pcb] = NONE  # remove existing quirk
 546 .Ed
 547 .Pp
 548 You can obtain
 549 .Aq class
 550 and
 551 .Aq name
 552 by running xprop(1) and then clicking on the desired window.
 553 In the following example the main window of Firefox was clicked:
 554 .Bd -literal -offset indent
 555 $ xprop | grep WM_CLASS
 556 WM_CLASS(STRING) = "Navigator", "Firefox"
 557 .Ed
 558 .Pp
 559 Note that grepping for WM_CLASS flips class and name.
 560 In the example above the quirk entry would be:
 561 .Bd -literal -offset indent
 562 quirk[Firefox:Navigator] = FLOAT
 563 .Ed
 564 .Sh SIGNALS
 565 Sending
 566 .Nm
 567 a HUP signal will retstart it.
 568 .Sh FILES
 569 .Bl -tag -width "/etc/scrotwm.confXXX" -compact
 570 .It Pa ~/.scrotwm.conf
 571 .Nm
 572 user specific settings.
 573 .It Pa /etc/scrotwm.conf
 574 .Nm
 575 global settings.
 576 .El
 577 .Sh HISTORY
 578 .Nm
 579 was inspired by xmonad & dwm.
 580 .Sh AUTHORS
 581 .An -nosplit
 582 .Pp
 583 .Nm
 584 was written by
 585 .An Marco Peereboom Aq marco@peereboom.us ,
 586 .An Ryan Thomas McBride Aq mcbride@countersiege.com
 587 and
 588 .An Darrin Chandler Aq dwchandler@stilyagin.com .
 589 .Sh BUGS
 590 Currently the menu, invoked with
 591 .Cm M-p ,
 592 depends on dmenu.