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