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 "screenshot_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 spawn_term
 109 External application that gets spawned when
 110 .Cm M-S- Ns Aq Cm Return
 111 is used.
 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 screenshot_enabled
 122 Enable or disable screenshot capability.
 123 .It Cm screenshot_app
 124 Set to the script that will take screenshots.
 125 It will be called with "full" or "window" as parameter 1 to indicate what
 126 screenshot action is expected.
 127 The script shall handle those cases accordingly.
 128 .It Cm term_width
 129 Set a preferred minimum width for the terminal
 130 If this value is greater than 0,
 131 .Nm
 132 will attempt to adjust the font sizes in the terminal to keep the terminal
 133 width above this number as the window is resized.
 134 Only
 135 .Xr xterm 1
 136 is currently supported.
 137 The
 138 .Xr xterm 1
 139 binary must not be setuid or setgid, which it is by default on most systems.
 140 Users may need to set spawn term to use an alternate copy of the
 141 .Xr xterm 1
 142 binary without the setgid bit set.
 143 .It Cm modkey
 144 Change mod key.
 145 Mod1 is generally the ALT key and Mod4 is the windows key on a PC.
 146 .It Cm bind Ns Bq Ar x
 147 Bind key combo to action
 148 .Ar x .
 149 See the
 150 .Sx BINDINGS
 151 section below.
 152 .It Cm quirk Ns Bq Ar c:n
 153 Add "quirk" for windows with class
 154 .Ar c
 155 and name
 156 .Ar n .
 157 See the
 158 .Sx QUIRKS
 159 section below.
 160 .El
 161 .Pp
 162 Colors need to be specified per the
 163 .Xr XQueryColor 3
 164 specification and fonts need to be specified per the
 165 .Xr XQueryFont 3
 166 specification.
 167 .Sh BINDINGS
 168 .Nm
 169 provides many functions (or actions) accessed via key or mouse bindings.
 170 .Pp
 171 The current mouse bindings are described below:
 172 .Pp
 173 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 174 .It Cm M1
 175 Focus window
 176 .It Cm M-M1
 177 Move window
 178 .It Cm M-M3
 179 Resize window
 180 .It Cm M-S-M3
 181 Resize window while maintaining it centered
 182 .El
 183 .Pp
 184 The default key bindings are described below:
 185 .Pp
 186 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 187 .It Cm M-S- Ns Aq Cm Return
 188 spawn_term
 189 .It Cm M-p
 190 spawn_menu
 191 .It Cm M-S-q
 192 quit
 193 .It Cm M-q
 194 restart
 195 .Nm
 196 .It Cm M- Ns Aq Cm Space
 197 cycle_layout
 198 .It Cm M-S- Ns Aq Cm Space
 199 reset_layout
 200 .It Cm M-h
 201 master_shrink
 202 .It Cm M-l
 203 master_grow
 204 .It Cm M-,
 205 master_add
 206 .It Cm M-.
 207 master_del
 208 .It Cm M-S-,
 209 stack_inc
 210 .It Cm M-S-.
 211 stack_del
 212 .It Cm M- Ns Aq Cm Return
 213 swap_main
 214 .It Xo
 215 .Cm M-j ,
 216 .Cm M- Ns Aq Cm TAB
 217 .Xc
 218 focus_next
 219 .It Xo
 220 .Cm M-k ,
 221 .Cm M-S- Ns Aq Cm TAB
 222 .Xc
 223 focus_prev
 224 .It Cm M-m
 225 focus_main
 226 .It Cm M-S-j
 227 swap_next
 228 .It Cm M-S-k
 229 swap_prev
 230 .It Cm M-b
 231 bar_toggle
 232 .It Cm M-x
 233 wind_del
 234 .It Cm M-S-x
 235 wind_kill
 236 .It Cm M- Ns Aq Ar n
 237 .Ns ws_ Ns Ar n
 238 .It Cm M-S- Ns Aq Ar n
 239 .Ns mvws_ Ns Ar n
 240 .It Cm M- Ns Aq Cm Right
 241 ws_next
 242 .It Cm M- Ns Aq Cm Left
 243 ws_prev
 244 .It Cm M-S- Ns Aq Cm Right
 245 screen_next
 246 .It Cm M-S- Ns Aq Cm Left
 247 screen_prev
 248 .It Cm M-s
 249 screenshot_all
 250 .It Cm M-S-s
 251 screenshot_wind
 252 .It Cm M-S-v
 253 version
 254 .It Cm M-t
 255 float_toggle
 256 .It Cm M-S Aq Cm Delete
 257 spawn_lock
 258 .It Cm M-S-i
 259 spawn_initscr
 260 .El
 261 .Pp
 262 The action names and descriptions are listed below:
 263 .Pp
 264 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 265 .It Cm spawn_term
 266 Spawn a new terminal
 267 .It Cm spawn_menu
 268 Menu
 269 .It Cm quit
 270 Quit
 271 .Nm
 272 .It Cm restart
 273 Restart
 274 .Nm
 275 .It Cm cycle_layout
 276 Cycle layout
 277 .It Cm reset_layout
 278 Reset layout
 279 .It Cm master_shrink
 280 Shrink master area
 281 .It Cm master_grow
 282 Grow master area
 283 .It Cm master_add
 284 Add windows to master area
 285 .It Cm master_del
 286 Remove windows from master area
 287 .It Cm stack_inc
 288 Add columns/rows to stacking area
 289 .It Cm stack_del
 290 Remove columns/rows from stacking area
 291 .It Cm swap_main
 292 Move current window to master area
 293 .It Cm focus_next
 294 Focus next window in workspace
 295 .It Cm focus_prev
 296 Focus previous window in workspace
 297 .It Cm focus_main
 298 Focus on main window in workspace
 299 .It Cm swap_next
 300 Swap with next window in workspace
 301 .It Cm swap_prev
 302 Swap with previous window in workspace
 303 .It Cm bar_toggle
 304 Toggle status bar in all workspaces
 305 .It Cm wind_del
 306 Delete current window in workspace
 307 .It Cm wind_kill
 308 Destroy current window in workspace
 309 .It Cm ws_ Ns Ar n
 310 Switch to workspace
 311 .Ar n ,
 312 where
 313 .Ar n
 314 is 1 through 10
 315 .It Cm mvws_ Ns Ar n
 316 Move current window to workspace
 317 .Ar n ,
 318 where
 319 .Ar n
 320 is 1 through 10
 321 .It Cm ws_next
 322 Switch to next workspace with a window in it
 323 .It Cm ws_prev
 324 Switch to previous workspace with a window in it
 325 .It Cm screen_next
 326 Move pointer to next region
 327 .It Cm screen_prev
 328 Move pointer to previous region
 329 .It Cm screenshot_all
 330 Take screenshot of entire screen (if enabled)
 331 .It Cm screenshot_wind
 332 Take screenshot of selected window (if enabled)
 333 .It Cm version
 334 Toggle version in status bar
 335 .It Cm float_toggle
 336 Toggle focused window between tiled and floating
 337 .It Cm spawn_lock
 338 Lock screen
 339 .It Cm spawn_initscr
 340 Reinitialize physical screens
 341 .El
 342 .Pp
 343 Custom bindings in the configuration file are specified as follows:
 344 .Pp
 345 .Dl bind[<action>] = <keys>
 346 .Pp
 347 .Aq action
 348 is one of the actions listed above (or empty) and
 349 .Aq keys
 350 is in the form of zero or more modifier keys
 351 (MOD, Mod1, Shift, etc.) and one or more normal keys
 352 (b, space, etc.), separated by "+".
 353 For example:
 354 .Bd -literal -offset indent
 355 bind[reset] = Mod4+q # bind Windows-key + q to reset
 356 bind[] = Mod1+q # unbind Alt + q
 357 .Ed
 358 .Pp
 359 Multiple key combinations may be bound to the same action.
 360 .Sh QUIRKS
 361 .Nm
 362 provides "quirks" which handle windows that must be treated specially
 363 in a tiling window manager, such as some dialogs and fullscreen apps.
 364 .Pp
 365 The default quirks are described below:
 366 .Pp
 367 .Bl -tag -width "OpenOffice.org N.M:VCLSalFrame<TAB>XXX" -offset indent -compact
 368 .It Firefox-bin:firefox-bin
 369 TRANSSZ
 370 .It Firefox:Dialog
 371 FLOAT
 372 .It Gimp:gimp
 373 FLOAT | ANYWHERE
 374 .It MPlayer:xv
 375 FLOAT | FULLSCREEN
 376 .It OpenOffice.org 2.4:VCLSalFrame
 377 FLOAT
 378 .It OpenOffice.org 3.1:VCLSalFrame
 379 FLOAT
 380 .It pcb:pcb
 381 FLOAT
 382 .It xine:Xine Window
 383 FLOAT | ANYWHERE
 384 .It xine:xine Panel
 385 FLOAT | ANYWHERE
 386 .It xine:xine Video Fullscreen Window
 387 FULLSCREEN | FLOAT
 388 .It Xitk:Xitk Combo
 389 FLOAT | ANYWHERE
 390 .It Xitk:Xine Window
 391 FLOAT | ANYWHERE
 392 .It XTerm:xterm
 393 XTERM_FONTADJ
 394 .El
 395 .Pp
 396 The quirks themselves are described below:
 397 .Pp
 398 .Bl -tag -width "XTERM_FONTADJ<TAB>XXX" -offset indent -compact
 399 .It FLOAT
 400 This window should not be tiled, but allowed to float freely.
 401 .It TRANSSZ
 402 Adjusts size on transient windows that are too small using dialog_ratio
 403 (see
 404 .Sx CONFIGURATION FILES ) .
 405 .It ANYWHERE
 406 Allow window to position itself, uncentered.
 407 .It XTERM_FONTADJ
 408 Adjust xterm fonts when resizing.
 409 .It FULLSCREEN
 410 Remove border to allow window to use full screen size.
 411 .El
 412 .Pp
 413 Custom quirks in the configuration file are specified as follows:
 414 .Pp
 415 .Dl quirk[<class>:<name>] = <quirk> [ | <quirk> ... ]
 416 .Pp
 417 .Aq class
 418 and
 419 .Aq name
 420 specify the window to which the quirk(s) apply, and
 421 .Aq quirk
 422 is one of the quirks from the list above.
 423 For example:
 424 .Bd -literal -offset indent
 425 quirk[MPlayer:xv] = FLOAT | FULLSCREEN # let mplayer play
 426 quirk[pcb:pcb] = NONE  # remove existing quirk
 427 .Ed
 428 .Pp
 429 Note that spaces in
 430 .Aq class
 431 or
 432 .Aq name
 433 must be replaced by an underscore in the configuration.
 434 The config entry for "xine:Xine Panel" would be:
 435 .Bd -literal -offset indent
 436 quirk[xine:Xine_Panel] = FLOAT
 437 .Ed
 438 .Pp
 439 You can obtain
 440 .Aq class
 441 and
 442 .Aq name
 443 by running xprop(1) and then clicking on the desired window.
 444 In the following example the main window of Firefox was clicked:
 445 .Bd -literal -offset indent
 446 $ xprop | grep WM_CLASS
 447 WM_CLASS(STRING) = "Navigator", "Firefox"
 448 .Ed
 449 .Sh FILES
 450 .Bl -tag -width "/etc/scrotwm.confXXX" -compact
 451 .It Pa ~/.scrotwm.conf
 452 .Nm
 453 user specific settings.
 454 .It Pa /etc/scrotwm.conf
 455 .Nm
 456 global settings.
 457 .El
 458 .Sh HISTORY
 459 .Nm
 460 was inspired by xmonad & dwm.
 461 .Sh AUTHORS
 462 .An -nosplit
 463 .Pp
 464 .Nm
 465 was written by
 466 .An Marco Peereboom Aq marco@peereboom.us ,
 467 .An Ryan Thomas McBride Aq mcbride@countersiege.com
 468 and
 469 .An Darrin Chandler Aq dwchandler@stilyagin.com .
 470 .Sh BUGS
 471 Currently the menu, invoked with
 472 .Cm M-p ,
 473 depends on dmenu.