code.delx.au - spectrwm/blob - scrotwm.1

   1 .\"     $scrotwm$
   2 .\"
   3 .\" Copyright (c) 2009 Marco Peereboom <marco@peereboom.us>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate$
  18 .Dt SCROTWM 1
  19 .Os
  20 .Sh NAME
  21 .Nm scrotwm
  22 .Nd window manager for X11
  23 .Sh SYNOPSIS
  24 .Nm scrotwm
  25 .Sh DESCRIPTION
  26 .Nm
  27 is a minimalistic window manager that tries to stay out of the way so that
  28 valuable screen real estate can be used for much more important stuff.
  29 It has sane defaults and does not require one to learn a language to do any
  30 configuration.
  31 It was written by hackers for hackers and it strives to be small, compact and
  32 fast.
  33 .Pp
  34 When
  35 .Nm
  36 starts up, it reads settings from its configuration file,
  37 .Pa scrotwm.conf .
  38 See the
  39 .Sx CONFIGURATION FILES
  40 section below.
  41 .Pp
  42 The following notation is used throughout this page:
  43 .Pp
  44 .Bl -tag -width Ds -offset indent -compact
  45 .It Cm M
  46 Meta
  47 .It Cm S
  48 Shift
  49 .It Aq Cm Name
  50 Named key
  51 .It Cm M1
  52 Mouse button 1
  53 .It Cm M3
  54 Mouse button 3
  55 .El
  56 .Pp
  57 .Nm
  58 is very simple in its use.
  59 Most of the actions are initiated via key or mouse bindings.
  60 See the
  61 .Sx BINDINGS
  62 section below for defaults and customizations.
  63 .Sh CONFIGURATION FILES
  64 .Nm
  65 first tries to open the user specific file,
  66 .Pa ~/.scrotwm.conf .
  67 If that file is unavailable,
  68 it then tries to open the global configuration file
  69 .Pa /etc/scrotwm.conf .
  70 .Pp
  71 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
  72 For example:
  73 .Pp
  74 .Dl color_focus = red
  75 .Pp
  76 Enabling or disabling an option is done by using 1 or 0 respectively.
  77 .Pp
  78 The file supports the following keywords:
  79 .Pp
  80 .Bl -tag -width "screenshot_enabledXXX" -offset indent -compact
  81 .It Cm color_focus
  82 Border color of the currently focussed window.
  83 .It Cm color_unfocus
  84 Border color of unfocussed windows.
  85 .It Cm bar_enabled
  86 Enable or disable status bar.
  87 .It Cm bar_border Ns Bq Ar x
  88 Color of the status bar border in screen
  89 .Ar x .
  90 .It Cm bar_color Ns Bq Ar x
  91 Color of the status bar window in screen
  92 .Ar x .
  93 .It Cm bar_font_color Ns Bq Ar x
  94 Color of the font in status bar in screen
  95 .Ar x .
  96 .It Cm bar_font
  97 Status bar font.
  98 .It Cm bar_action
  99 External script that populates additional information in the status bar,
 100 such as battery life.
 101 .It Cm bar_delay
 102 Update frequency, in seconds, of external script that populates the status bar.
 103 .It Cm clock_enabled
 104 Enable or disable displaying the clock in the status bar.
 105 Disable by setting to 0
 106 so a custom clock could be used in the bar_action script.
 107 .It Cm spawn_term
 108 External application that gets spawned when
 109 .Cm M-S- Ns Aq Cm Return
 110 is used.
 111 .It Cm dialog_ratio
 112 Some applications have dialogue windows that are too small to be useful.
 113 This ratio is the screen size to what they will be resized.
 114 For example, 0.6 is 60% of the physical screen size.
 115 .It Cm region
 116 Allocates a custom region, removing any autodetected regions which occupy the same
 117 space on the screen.
 118 Defined in the format screen[<idx>]:WIDTHxHEIGHT+X+Y,
 119 e.g.\& screen[1]:800x1200+0+0.
 120 .It Cm screenshot_enabled
 121 Enable or disable screenshot capability.
 122 .It Cm screenshot_app
 123 Set to the script that will take screenshots.
 124 It will be called with "full" or "window" as parameter 1 to indicate what
 125 screenshot action is expected.
 126 The script shall handle those cases accordingly.
 127 .It Cm term_width
 128 Set a preferred minimum width for the terminal
 129 If this value is greater than 0,
 130 .Nm
 131 will attempt to adjust the font sizes in the terminal to keep the terminal
 132 width above this number as the window is resized.
 133 Only
 134 .Xr xterm 1
 135 is currently supported.
 136 The
 137 .Xr xterm 1
 138 binary must not be setuid or setgid, which it is by default on most systems.
 139 Users may need to set spawn term to use an alternate copy of the
 140 .Xr xterm 1
 141 binary without the setgid bit set.
 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 bind Ns Bq Ar x
 146 Bind key combo to action
 147 .Ar x .
 148 See the
 149 .Sx BINDINGS
 150 section below.
 151 .It Cm quirk Ns Bq Ar c:n
 152 Add "quirk" for windows with class
 153 .Ar c
 154 and name
 155 .Ar n .
 156 See the
 157 .Sx QUIRKS
 158 section below.
 159 .El
 160 .Pp
 161 Colors need to be specified per the
 162 .Xr XQueryColor 3
 163 specification and fonts need to be specified per the
 164 .Xr XQueryFont 3
 165 specification.
 166 .Sh BINDINGS
 167 .Nm
 168 provides many functions (or actions) accessed via key or mouse bindings.
 169 .Pp
 170 The current mouse bindings are described below:
 171 .Pp
 172 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 173 .It Cm M1
 174 Focus window
 175 .It Cm M-M1
 176 Move window
 177 .It Cm M-M3
 178 Resize window
 179 .It Cm M-S-M3
 180 Resize window while maintaining it centered
 181 .El
 182 .Pp
 183 The default key bindings are described below:
 184 .Pp
 185 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 186 .It Cm M-S- Ns Aq Cm Return
 187 spawn_term
 188 .It Cm M-p
 189 spawn_menu
 190 .It Cm M-S-q
 191 quit
 192 .It Cm M-q
 193 restart
 194 .Nm
 195 .It Cm M- Ns Aq Cm Space
 196 cycle_layout
 197 .It Cm M-S- Ns Aq Cm Space
 198 reset_layout
 199 .It Cm M-h
 200 master_shrink
 201 .It Cm M-l
 202 master_grow
 203 .It Cm M-,
 204 master_add
 205 .It Cm M-.
 206 master_del
 207 .It Cm M-S-,
 208 stack_inc
 209 .It Cm M-S-.
 210 stack_del
 211 .It Cm M- Ns Aq Cm Return
 212 swap_main
 213 .It Xo
 214 .Cm M-j ,
 215 .Cm M- Ns Aq Cm TAB
 216 .Xc
 217 focus_next
 218 .It Xo
 219 .Cm M-k ,
 220 .Cm M-S- Ns Aq Cm TAB
 221 .Xc
 222 focus_prev
 223 .It Cm M-m
 224 focus_main
 225 .It Cm M-S-j
 226 swap_next
 227 .It Cm M-S-k
 228 swap_prev
 229 .It Cm M-b
 230 bar_toggle
 231 .It Cm M-x
 232 wind_del
 233 .It Cm M-S-x
 234 wind_kill
 235 .It Cm M- Ns Aq Ar n
 236 .Ns ws_ Ns Ar n
 237 .It Cm M-S- Ns Aq Ar n
 238 .Ns mvws_ Ns Ar n
 239 .It Cm M- Ns Aq Cm Right
 240 ws_next
 241 .It Cm M- Ns Aq Cm Left
 242 ws_prev
 243 .It Cm M-S- Ns Aq Cm Right
 244 screen_next
 245 .It Cm M-S- Ns Aq Cm Left
 246 screen_prev
 247 .It Cm M-s
 248 screenshot_all
 249 .It Cm M-S-s
 250 screenshot_wind
 251 .It Cm M-S-v
 252 version
 253 .It Cm M-t
 254 float_toggle
 255 .It Cm M-S Aq Cm Delete
 256 spawn_lock
 257 .It Cm M-S-i
 258 spawn_initscr
 259 .El
 260 .Pp
 261 The action names and descriptions are listed below:
 262 .Pp
 263 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 264 .It Cm spawn_term
 265 Spawn a new terminal
 266 .It Cm spawn_menu
 267 Menu
 268 .It Cm quit
 269 Quit
 270 .Nm
 271 .It Cm restart
 272 Restart
 273 .Nm
 274 .It Cm cycle_layout
 275 Cycle layout
 276 .It Cm reset_layout
 277 Reset layout
 278 .It Cm master_shrink
 279 Shrink master area
 280 .It Cm master_grow
 281 Grow master area
 282 .It Cm master_add
 283 Add windows to master area
 284 .It Cm master_del
 285 Remove windows from master area
 286 .It Cm stack_inc
 287 Add columns/rows to stacking area
 288 .It Cm stack_del
 289 Remove columns/rows from stacking area
 290 .It Cm swap_main
 291 Move current window to master area
 292 .It Cm focus_next
 293 Focus next window in workspace
 294 .It Cm focus_prev
 295 Focus previous window in workspace
 296 .It Cm focus_main
 297 Focus on main window in workspace
 298 .It Cm swap_next
 299 Swap with next window in workspace
 300 .It Cm swap_prev
 301 Swap with previous window in workspace
 302 .It Cm bar_toggle
 303 Toggle status bar in all workspaces
 304 .It Cm wind_del
 305 Delete current window in workspace
 306 .It Cm wind_kill
 307 Destroy current window in workspace
 308 .It Cm ws_ Ns Ar n
 309 Switch to workspace
 310 .Ar n ,
 311 where
 312 .Ar n
 313 is 1 through 10
 314 .It Cm mvws_ Ns Ar n
 315 Move current window to workspace
 316 .Ar n ,
 317 where
 318 .Ar n
 319 is 1 through 10
 320 .It Cm ws_next
 321 Switch to next workspace with a window in it
 322 .It Cm ws_prev
 323 Switch to previous workspace with a window in it
 324 .It Cm screen_next
 325 Move pointer to next region
 326 .It Cm screen_prev
 327 Move pointer to previous region
 328 .It Cm screenshot_all
 329 Take screenshot of entire screen (if enabled)
 330 .It Cm screenshot_wind
 331 Take screenshot of selected window (if enabled)
 332 .It Cm version
 333 Toggle version in status bar
 334 .It Cm float_toggle
 335 Toggle focused window between tiled and floating
 336 .It Cm spawn_lock
 337 Lock screen
 338 .It Cm spawn_initscr
 339 Reinitialize physical screens
 340 .El
 341 .Pp
 342 Custom bindings in the configuration file are specified as follows:
 343 .Pp
 344 .Dl bind[<action>] = <keys>
 345 .Pp
 346 .Aq action
 347 is one of the actions listed above (or empty) and
 348 .Aq keys
 349 is in the form of zero or more modifier keys
 350 (MOD, Mod1, Shift, etc.) and one or more normal keys
 351 (b, space, etc.), separated by "+".
 352 For example:
 353 .Bd -literal -offset indent
 354 bind[reset] = Mod4+q # bind Windows-key + q to reset
 355 bind[] = Mod1+q # unbind Alt + q
 356 .Ed
 357 .Pp
 358 Multiple key combinations may be bound to the same action.
 359 .Sh QUIRKS
 360 .Nm
 361 provides "quirks" which handle windows that must be treated specially
 362 in a tiling window manager, such as some dialogs and fullscreen apps.
 363 .Pp
 364 The default quirks are described below:
 365 .Pp
 366 .Bl -tag -width "OpenOffice.org N.M:VCLSalFrame<TAB>XXX" -offset indent -compact
 367 .It Firefox-bin:firefox-bin
 368 TRANSSZ
 369 .It Firefox:Dialog
 370 FLOAT
 371 .It Gimp:gimp
 372 FLOAT | ANYWHERE
 373 .It MPlayer:xv
 374 FLOAT | FULLSCREEN
 375 .It OpenOffice.org 2.4:VCLSalFrame
 376 FLOAT
 377 .It OpenOffice.org 3.1:VCLSalFrame
 378 FLOAT
 379 .It pcb:pcb
 380 FLOAT
 381 .It xine:Xine Window
 382 FLOAT | ANYWHERE
 383 .It xine:xine Panel
 384 FLOAT | ANYWHERE
 385 .It xine:xine Video Fullscreen Window
 386 FULLSCREEN | FLOAT
 387 .It Xitk:Xitk Combo
 388 FLOAT | ANYWHERE
 389 .It Xitk:Xine Window
 390 FLOAT | ANYWHERE
 391 .It XTerm:xterm
 392 XTERM_FONTADJ
 393 .El
 394 .Pp
 395 The quirks themselves are described below:
 396 .Pp
 397 .Bl -tag -width "XTERM_FONTADJ<TAB>XXX" -offset indent -compact
 398 .It FLOAT
 399 This window should not be tiled, but allowed to float freely.
 400 .It TRANSSZ
 401 Adjusts size on transient windows that are too small using dialog_ratio
 402 (see
 403 .Sx CONFIGURATION FILES ) .
 404 .It ANYWHERE
 405 Allow window to position itself, uncentered.
 406 .It XTERM_FONTADJ
 407 Adjust xterm fonts when resizing.
 408 .It FULLSCREEN
 409 Remove border to allow window to use full screen size.
 410 .El
 411 .Pp
 412 Custom quirks in the configuration file are specified as follows:
 413 .Pp
 414 .Dl quirk[<class>:<name>] = <quirk> [ | <quirk> ... ]
 415 .Pp
 416 .Aq class
 417 and
 418 .Aq name
 419 specify the window to which the quirk(s) apply, and
 420 .Aq quirk
 421 is one of the quirks from the list above.
 422 For example:
 423 .Bd -literal -offset indent
 424 quirk[MPlayer:xv] = FLOAT | FULLSCREEN # let mplayer play
 425 quirk[pcb:pcb] = NONE  # remove existing quirk
 426 .Ed
 427 .Pp
 428 Note that spaces in
 429 .Aq class
 430 or
 431 .Aq name
 432 must be replaced by an underscore in the configuration.
 433 The config entry for "xine:Xine Panel" would be:
 434 .Bd -literal -offset indent
 435 quirk[xine:Xine_Panel] = FLOAT
 436 .Ed
 437 .Pp
 438 You can obtain
 439 .Aq class
 440 and
 441 .Aq name
 442 by running xprop(1) and then clicking on the desired window.
 443 In the following example the main window of Firefox was clicked:
 444 .Bd -literal -offset indent
 445 $ xprop | grep WM_CLASS
 446 WM_CLASS(STRING) = "Navigator", "Firefox"
 447 .Ed
 448 .Sh FILES
 449 .Bl -tag -width "/etc/scrotwm.confXXX" -compact
 450 .It Pa ~/.scrotwm.conf
 451 .Nm
 452 user specific settings.
 453 .It Pa /etc/scrotwm.conf
 454 .Nm
 455 global settings.
 456 .El
 457 .Sh HISTORY
 458 .Nm
 459 was inspired by xmonad & dwm.
 460 .Sh AUTHORS
 461 .An -nosplit
 462 .Pp
 463 .Nm
 464 was written by
 465 .An Marco Peereboom Aq marco@peereboom.us ,
 466 .An Ryan Thomas McBride Aq mcbride@countersiege.com
 467 and
 468 .An Darrin Chandler Aq dwchandler@stilyagin.com .
 469 .Sh BUGS
 470 Currently the menu, invoked with
 471 .Cm M-p ,
 472 depends on dmenu.