summaryrefslogtreecommitdiff
path: root/doc/ratpoison.1
blob: 15367fa8427a3b95b5ff41242e1fdc3e9856f017 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
.TH RATPOISON 1 "26 January, 2002" "ratpoison" RATPOISON
.SH NAME
ratpoison \- fatless X window manager
.SH SYNOPSIS
.B ratpoison
[
\fIoptions\fP
]
.SH DESCRIPTION
ratpoison is a simple Window Manager with no fat library dependencies, no fancy graphics, no window decorations, and no flashy wank. It is largely modeled after GNU Screen which has done wonders in the virtual terminal market.
.PP
All interaction with the window manager is done through keystrokes. ratpoison has a prefix map to minimize the key clobbering that cripples EMACS and other quality pieces of software.
.PP
ratpoison is a very simple window manager. Each window is maximized and has no border decorations. 
.SH KEYSTROKES
The default keystrokes are listed in this chapter. Not all commands are accessible by default by keys. A full list of ratpoison commands is in the next section.
.TP
.B C\-t C\-t
Switch to the last window.
.TP
.B C\-t t
Sometimes you need to send a C\-t to the current window. This
keystroke does just that.
.TP
.B C\-t 0\-9
Switch to the numbered window.
.TP
.B C\-t \-
Select no window, essentially hiding all windows in the current
frame.
.TP
.B C\-t A, C\-t C\-A
Rename the current window. The window's new name will prevail for
the rest of its lifetime.
.TP
.B C\-t K, C\-t C\-K
Send a DestroyClient event to the current window. This will
terminate the application without question.
.TP
.B C\-t n, C\-t C\-n, C\-t Return, C\-t C\-Return, C\-t Space, C\-t C\-Space
Go to next window.
.TP
.B C\-t p, C\-t C\-p
Go to previous window.
.TP
.B C\-t ', C\-t C\-'
Go to a window by name. You will usually only need to type the
first few characters of the window name.
.TP
.B C\-t a, C\-t C\-a
Display the current time of day.
.TP
.B C\-t c, C\-t C\-c
Open a new X terminal.
.TP
.B C\-t :
This allows you to execute a single ratpoison command.
.TP
.B C\-t !
Run a shell command.
.TP
.B C\-t C\-!
Run a shell command through an X terminal.
.TP
.B C\-t i, C\-t C\-i
Display information about the current window.
.TP
.B C\-t k, C\-t C\-k
Close the current window.
.TP
.B C\-t l, C\-t C\-l
Redisplay the current window. Sometimes windows don't respond
correctly to the initial maximize event and need some coaxing.
This is a fancy way of saying there are still bugs in ratpoison.
`C\-t l' will force the current window to maximize.
.TP
.B C\-t m, C\-t C\-m
Display the last message.
.TP
.B C\-t v, C\-t C\-v
Display the version of ratpoison.
.TP
.B C\-t w, C\-t C\-w
Display the list of managed windows. The current window is
highlighted.
.TP
.B C\-t s
Split the current window horizontally in two. The last accessed
window not occupying a frame will be the second window.
.TP
.B C\-t S
Split the current window vertically in two. The last accessed
window not occupying a frame will be the second window.
.TP
.B C\-t tab
Cycle through ratpoison's frames.
.TP
.B C\-t M\-tab
Switch to the last focused frame.
.TP
.B C\-t Q
Kill all frames but the current one.
.TP
.B C\-t R
Kill the current frame. This is a no\-op if there is only one frame.
.TP
.B C\-t b, C\-t C\-b
Banish the mouse to the lower right corner of the screen.
.TP
.B C\-t ?
Display a help screen
.TP
.B C\-t f, C\-t C\-f
Indicate which frame is the current frame.
.SH COMMANDS
ratpoison can be controlled with commands (so called colon\-commands).
The summary of available commands is listed below:
.TP
.B abort
This is a pretty useless command. By default, it is bound to `C\-t
g', and its purpose is to abort other commands.
.TP
.B alias \fINAME COMMAND\fP
An alias allows you to name a ratpoison command something else. For
instance, if you frequently open emacs you may want to make an
alias called `emacs' that loads emacs. You would do it like this:

: alias emacs exec emacs

An alias is treated exactly like a colon command in that you can
call it from the colon prompt, bind it to a key, and call it
non\-interactively with `ratpoison \-c'.
.TP
.B banish
Banish the mouse to the lower right corner of the screen.
.TP
.B bind \fIKEY COMMAND\fP
Bind a key to a ratpoison command. This command takes two
arguments: the key to bind and the command to run. For example, to
bind `C\-t R' to restart ratpoison:

: bind R restart

If no command is specified then bind works exactly like `unbind',
unbinding the key.
.TP
.B chdir
Change the current directory for ratpoison.
.TP
.B colon \fICOMMAND\fP
Run a ratpoison command.
.TP
.B curframe
Indicate which frame is the current frame.
.TP
.B defbarborder \fIN\fP
Set the border width for the bar.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B defbarloc \fILOC\fP
Set the message bar location. \fILOC\fP can be one of `northeast', `northwest',
`southeast', `southwest', or their abbreviations.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B defbarpadding \fIX Y\fP
Set the horizontal and vertical padding inside the bar.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B defbgcolor \fICOLOR\fP
Set the background color for all text ratpoison displays. \fICOLOR\fP is any
valid X11 color.
.TP
.B defborder \fIN\fP
Set the border width for all windows.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B deffgcolor \fICOLOR\fP
Set the foreground color for all text ratpoison displays. \fICOLOR\fP is any
valid X11 color.
.TP
.B deffont \fIFONT\fP
Set the font. \fIFONT\fP is a font string like `9x15bold'.
.TP
.B definputwidth \fIN\fP
Set the width of the input window.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B defmaxsizegravity \fIG\fP
Set the default alignment for windows with maxsize hints. See the
`gravity' command.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B defpadding \fILEFT TOP RIGHT BOTTOM\fP
Set the padding around the edge of the screen.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B deftransgravity \fIG\fP
Set the default alignment for transient windows. See the `gravity'
command.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B defwaitcursor \fIN\fP
Set whether the rat cursor should change into a square when waiting
for a key. A non\-zero number means change the cursor. Zero means
don't change the cursor.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B defwinfmt \fIFMT\fP
Set the default window format for the `windows' command. By
default it is `N\-W'. The following is a list of valid format
characters:

`%n'
The window number

`%s'
Window status (current window, last window, etc)

`%t'
Window Name

`%a'
Application Name

`%c'
Resource Class

`%i'
X11 Window ID

`%l'
A unique number based on when the window was last accessed.
The higher the number, the more recently it was accessed.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B defwingravity \fIG\fP
Set the default gravity for normal windows. See the `gravity'
command.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B defwinname \fINAME\fP
There are three resources ratpoison can get a window's name from:
the WMNAME hint, the res_name from the WMCLASS hint, or the
res_class from the WMCLASS hint. \fINAME\fP can be `title' which is what most
window managers put in the title bar, `name' which is the res_name, or `class'
which is the res_class.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B delete
This deletes the current window. You can access it with the `C\-t k'
keystroke.
.TP
.B echo \fITEXT\fP
Display \fITEXT\fP as a message.
.TP
.B escape \fIKEY\fP
Set the prefix to to \fIKEY\fP. For example `escape C\-b' sets the prefix key
to <C\-b>.
.TP
.B exec \fICOMMAND\fP
Execute a shell command. By default, `C\-t !' does this.
.TP
.B focus
cycle through ratpoison's frames.
.TP
.B focuslast
Switch to the last focused frame.
.TP
.B focusup
Move to the frame above the current frame.
.TP
.B focusdown
Move to the frame below the current frame.
.TP
.B focusleft
Move to the frame left of the current frame.
.TP
.B focusright
Move to the frame right of the current frame.
.TP
.B gravity \fIG\fP
Change the gravity of the current window. A normal window will default to the
top\-left corner of the screen, but it can also be placed at the bottom\-right
corner of the screen. Valid values for \fIG\fP are the 8 directions
`northwest', `north', `northeast', `east', `southeast', `south', `southwest'
and `west', clockwise from the top left corner. `center' will center the window
in the frame. \fIG\fP and can be abbreviated to one or two letters.
.TP
.B help
Display a help screen that lists all bound keystrokes.
.TP
.B info
Display information about the current window.
.TP
.B kill
This destroys the current window. Normally you should only need to
use `delete', but just in case you need to rip the heart out of a
misbehaving window this command should do the trick. Also
available as `C\-t K'.
.TP
.B lastmsg
Display the last message.
.TP
.B link \fIKEY\fP
Call the command that \fIKEY\fP is bound to. For instance `link C\-t' would
call the command `other' and switch to the last window.
.TP
.B meta
Send a `C\-t' to the current window.
.TP
.B msgwait \fIN\fP
Set the bar's timeout in seconds.

When called non\-interactively with no arguments, the current
setting is returned.
.TP
.B redisplay
Redisplay the current window, just like `C\-t l' would do.
.TP
.B restart
Restart ratpoison.
.TP
.B newwm \fIWINDOW\-MANAGER\fP
This is a bad\-bad command. It kills ratpoison and revives that
ugly rodent! Yuck! Avoid!
.TP
.B next
This jumps you to the next window in the window list. This one is
bound to three keystrokes, namely `C\-t n', `C\-t space', and `C\-t
enter'.
.TP
.B number \fIN TARGET\fP
Set a window's number to \fIN\fP. If another window occupies the requested
number already, then the windows' numbers are swapped.

The second argument, \fITARGET\fP, is optional. It should be the number of the
window whose number will be changed. If \fITARGET\fP is omitted ratpoison
defaults to the current window.
.TP
.B only
Kill all frames but the current one.
.TP
.B other
This toggles between the current window and the last window. By
default, this is bound to `C\-t C\-t'.
.TP
.B prev
This jumps you to the previous window in the window list. By
default, this is bound to `C\-t p'.
.TP
.B quit
Quit ratpoison.
.TP
.B remove
Kill the current frame. This is a no\-op if there is only one frame.
.TP
.B rudeness \fIN\fP
The rudeness command lets you decide what windows pop\-up
automatically and when. This is often useful for those deep hack
sessions when you absolutely can't be disturbed.

There are two kinds of windows: normal windows (like an xterm) and
transient windows (generally pop\-up dialog boxes). When a client
program wants to display a new window it makes a requests to
ratpoison. ratpoison then decides whether to grant the request and
display the window or ignore it. A client program can also request
that one of its windows be raised. You can customize ratpoison to
either honour these requests (the default operation) or ignore
them.

\fIN\fP is a number from 0 to 15. Each of the four bits determine which
requests ratpoison grants.

Bit 0
Tells ratpoison to grant raise requests on transient windows

Bit 1
Tells ratpoison to grant raise requests on normal windows

Bit 2
Tells ratpoison to grant display requests on new transient
windows

Bit 3
Tells ratpoison to grant display requests on new normal
windows

For example, if you wanted only wanted to grant transient windows raise
requests and display requests you would type `rudeness 5'. If a request is not
granted ratpoison will tell you about the request with a message like `Raise
request from window 1 (emacs)'.
.TP
.B select \fIN\fP
This jumps you to window \fIN\fP where \fIN\fP is the window number as shown in
the Program Bar. You can do the same trick with `C\-N' too. To select no
window, blanking the current frame, type `select \-'.
.TP
.B select \fIWINDOW\-NAME\fP
Go to a window by name. A shortcut is `C\-t ''.
.TP
.B setenv \fIENV VALUE\fP
Set the environment variable \fIENV\fP to \fIVALUE\fP
.TP
.B source \fIFILE\fP
Read a text file containing ratpoison commands.
.TP
.B split
.PP
.B hsplit
Split the current window horizontally in two. The last accessed
window not occupying a frame will be the second window.
.TP
.B startup_message \fISTATE\fP
Turn on or off the startup_message. This is most useful in your
~/.ratpoisonrc file. \fISTATE\fP can be `on' or `off'.
.TP
.B time
Show current time. Disappears after 5 seconds, like all other info
bars. In the default setup, the `C\-t a' keystroke is bound to
this command.
.TP
.B title \fITITLE\fP
Rename the currently active window. This name will remain for the
duration of the window's life, unless you change it again. By
default, the `C\-t A' keystroke is bound to this command.
.TP
.B unbind \fIKEY\fP
Unbind a keystroke.
.TP
.B unsetenv \fIENV\fP
Clear the value of the environment variable, \fIENV\fP.
.TP
.B version
Print ratpoison version. By default, this is bound to `C\-t v'.
.TP
.B vsplit
Split the current window vertically in two. The last accessed
window not occupying a frame will be the second window.
.TP
.B windows \fIFMT\fP
This displays the Program Bar which displays the windows you
currently have running. The number before each window name is used
to jump to that window. You can do this by typing `C\-t N' where N
is the number of the window. Note that only windows with numbers
from 0 to 9 can be referenced using this keystroke. To reach
windows with numbers greater than 9, use `C\-t '' and type the
number at the prompt.

After 5 seconds the Program Bar disappears.

This command is bound to `C\-t w' by default.

When invoked from the command\-line like this,

$ ratpoison \-c windows

Instead of a message bar, you will get a list of the windows
printed to stdout. This allows you to write more advanced scripts
than simple keyboard macros. This is where \fIFMT\fP comes into play. If
`windows' is given an arg it treats it as the format string as described in
`defwinfmt'.
.SH OPTIONS
.TP
.B \-h, \-\-help
Display this help screen
.TP
.B \-v, \-\-version
Display the version
.TP
.B \-c \fIcmd\fP, \-\-command \fIcmd\fP
Send ratpoison a colon\-command.
.SH FILES
.TP
.B /etc/ratpoisonrc
System-wide configuration file.
.TP
.B $HOME/.ratpoisonrc
User configuration file.
.SH "REPORTING BUGS"
Report bugs to <ratpoison\-devel@lists.sourceforge.net>.
.SH COPYRIGHT
Copyright \(co 2000, 2001, 2002 Shawn Betts
.br 
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
ratmenu(1), X(7x)
.PP
The full documentation for
.B ratpoison 
is maintained as a Texinfo manual. If the
.B info
and
.B ratpoison
programs are properly installed at your site, the command
.IP
.B info ratpoison
.PP 
should give you access to the complete manual.
.SH AUTHOR
Ratpoison was written by Shawn Betts <sabetts@users.sourceforge.net>.

This manual page was written by Gergely Nagy <8@free.bsd.hu> and
updated by Shawn Betts <sabetts@users.sourceforge.net> and Doug
Kearns <djkea2@mugca.cc.monash.edu.au>.