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.  Disable by
 105 setting to 0 so a custom clock could be used in the bar_action script.
 106 .It Cm spawn_term
 107 External application that gets spawned when
 108 .Cm M-S- Ns Aq Cm Return
 109 is used.
 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, e.g. screen[1]:800x1200+0+0.
 118 .It Cm screenshot_enabled
 119 Enable or disable screenshot capability.
 120 .It Cm screenshot_app
 121 Set to the script that will take screenshots.
 122 It will be called with "full" or "window" as parameter 1 to indicate what
 123 screenshot action is expected.
 124 The script shall handle those cases accordingly.
 125 .It Cm term_width
 126 Set a preferred minimum width for the terminal
 127 If this value is greater than 0,
 128 .Nm
 129 will attempt to adjust the font sizes in the terminal to keep the terminal
 130 width above this number as the window is resized.
 131 Only
 132 .Xr xterm 1
 133 is currently supported.
 134 The
 135 .Xr xterm 1
 136 binary must not be setuid or setgid, which it is by default on most systems.
 137 Users may need to set spawn term to use an alternate copy of the
 138 .Xr xterm 1
 139 binary without the setgid bit set.
 140 .It Cm modkey
 141 Change mod key.
 142 Mod1 is generally the ALT key and Mod4 is the windows key on a PC.
 143 .It Cm bind Ns Bq Ar x
 144 Bind key combo to action
 145 .Ar x .
 146 See the
 147 .Sx BINDINGS
 148 section below.
 149 .El
 150 .Pp
 151 Colors need to be specified per the
 152 .Xr XQueryColor 3
 153 specification and fonts need to be specified per the
 154 .Xr XQueryFont 3
 155 specification.
 156 .Sh BINDINGS
 157 .Nm
 158 provides many functions (or actions) accessed via key or mouse bindings.
 159 .Pp
 160 The current mouse bindings are described below:
 161 .Pp
 162 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 163 .It Cm M1
 164 Focus window
 165 .It Cm M-M1
 166 Move window
 167 .It Cm M-M3
 168 Resize window
 169 .It Cm M-S-M3
 170 Resize window while maintaining it centered
 171 .El
 172 .Pp
 173 The default key bindings are described below:
 174 .Pp
 175 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 176 .It Cm M-S- Ns Aq Cm Return
 177 spawn_term
 178 .It Cm M-p
 179 spawn_menu
 180 .It Cm M-S-q
 181 quit
 182 .It Cm M-q
 183 restart
 184 .Nm
 185 .It Cm M- Ns Aq Cm Space
 186 cycle_layout
 187 .It Cm M-S- Ns Aq Cm Space
 188 reset_layout
 189 .It Cm M-h
 190 master_shrink
 191 .It Cm M-l
 192 master_grow
 193 .It Cm M-,
 194 master_add
 195 .It Cm M-.
 196 master_del
 197 .It Cm M-S-,
 198 stack_inc
 199 .It Cm M-S-.
 200 stack_del
 201 .It Cm M- Ns Aq Cm Return
 202 swap_main
 203 .It Xo
 204 .Cm M-j ,
 205 .Cm M- Ns Aq Cm TAB
 206 .Xc
 207 focus_next
 208 .It Xo
 209 .Cm M-k ,
 210 .Cm M-S- Ns Aq Cm TAB
 211 .Xc
 212 focus_prev
 213 .It Cm M-m
 214 focus_main
 215 .It Cm M-S-j
 216 swap_next
 217 .It Cm M-S-k
 218 swap_prev
 219 .It Cm M-b
 220 bar_toggle
 221 .It Cm M-x
 222 wind_del
 223 .It Cm M-S-x
 224 wind_kill
 225 .It Cm M- Ns Aq Ar n
 226 .Ns ws_ Ns Ar n
 227 .It Cm M-S- Ns Aq Ar n
 228 .Ns mvws_ Ns Ar n
 229 .It Cm M- Ns Aq Cm Right
 230 ws_next
 231 .It Cm M- Ns Aq Cm Left
 232 ws_prev
 233 .It Cm M-S- Ns Aq Cm Right
 234 screen_next
 235 .It Cm M-S- Ns Aq Cm Left
 236 screen_prev
 237 .It Cm M-s
 238 screenshot_all
 239 .It Cm M-S-s
 240 screenshot_wind
 241 .It Cm M-S-v
 242 version
 243 .It Cm M-t
 244 float_toggle
 245 .It Cm M-S Aq Cm Delete
 246 spawn_lock
 247 .It Cm M-S-i
 248 spawn_initscr
 249 .El
 250 .Pp
 251 The action names and descriptions are listed below:
 252 .Pp
 253 .Bl -tag -width "M-j, M-<TAB>XXX" -offset indent -compact
 254 .It Cm spawn_term
 255 Spawn a new terminal
 256 .It Cm spawn_menu
 257 Menu
 258 .It Cm quit
 259 Quit
 260 .Nm
 261 .It Cm restart
 262 Restart
 263 .Nm
 264 .It Cm cycle_layout
 265 Cycle layout
 266 .It Cm reset_layout
 267 Reset layout
 268 .It Cm master_shrink
 269 Shrink master area
 270 .It Cm master_grow
 271 Grow master area
 272 .It Cm master_add
 273 Add windows to master area
 274 .It Cm master_del
 275 Remove windows from master area
 276 .It Cm stack_inc
 277 Add columns/rows to stacking area
 278 .It Cm stack_del
 279 Remove columns/rows from stacking area
 280 .It Cm swap_main
 281 Move current window to master area
 282 .It Cm focus_next
 283 Focus next window in workspace
 284 .It Cm focus_prev
 285 Focus previous window in workspace
 286 .It Cm focus_main
 287 Focus on main window in workspace
 288 .It Cm swap_next
 289 Swap with next window in workspace
 290 .It Cm swap_prev
 291 Swap with previous window in workspace
 292 .It Cm bar_toggle
 293 Toggle status bar in all workspaces
 294 .It Cm wind_del
 295 Delete current window in workspace
 296 .It Cm wind_kill
 297 Destroy current window in workspace
 298 .It Cm ws_ Ns Ar n
 299 Switch to workspace
 300 .Ar n ,
 301 where
 302 .Ar n
 303 is 1 through 10
 304 .It Cm mvws_ Ns Ar n
 305 Move current window to workspace
 306 .Ar n ,
 307 where
 308 .Ar n
 309 is 1 through 10
 310 .It Cm ws_next
 311 Switch to next workspace with a window in it
 312 .It Cm ws_prev
 313 Switch to previous workspace with a window in it
 314 .It Cm screen_next
 315 Move pointer to next region
 316 .It Cm screen_prev
 317 Move pointer to previous region
 318 .It Cm screenshot_all
 319 Take screenshot of entire screen (if enabled)
 320 .It Cm screenshot_wind
 321 Take screenshot of selected window (if enabled)
 322 .It Cm version
 323 Toggle version in status bar
 324 .It Cm float_toggle
 325 Toggle focused window between tiled and floating
 326 .It Cm spawn_lock
 327 Lock screen
 328 .It Cm spawn_initscr
 329 Reinitialize physical screens
 330 .El
 331 .Pp
 332 Custom bindings in the configuration file are specified as follows:
 333 .Pp
 334 .Dl bind[<action>] = <keys>
 335 .Pp
 336 .Aq action
 337 is one of the actions listed above (or empty) and
 338 .Aq keys
 339 is in the form of zero or more modifier keys
 340 (MOD, Mod1, Shift, etc.) and one or more normal keys
 341 (b, space, etc.), separated by "+". For example:
 342 .Bd -literal -offset indent
 343 bind[reset] = Mod4+q # bind Windows-key + q to reset
 344 bind[] = Mod1+q # unbind Alt + q
 345 .Ed
 346 .Pp
 347 Multiple key combinations may be bound to the same action.
 348 .Sh FILES
 349 .Bl -tag -width "/etc/scrotwm.confXXX" -compact
 350 .It Pa ~/.scrotwm.conf
 351 .Nm
 352 user specific settings.
 353 .It Pa /etc/scrotwm.conf
 354 .Nm
 355 global settings.
 356 .El
 357 .Sh HISTORY
 358 .Nm
 359 was inspired by xmonad & dwm.
 360 .Sh AUTHORS
 361 .An -nosplit
 362 .Pp
 363 .Nm
 364 was written by
 365 .An Marco Peereboom Aq marco@peereboom.us ,
 366 .An Ryan Thomas McBride Aq mcbride@countersiege.com
 367 and
 368 .An Darrin Chandler Aq dwchandler@stilyagin.com .
 369 .Sh BUGS
 370 Currently the menu, invoked with
 371 .Cm M-p ,
 372 depends on dmenu.