1RATPOISON(1) General Commands Manual RATPOISON(1)
2
6 ratpoison - window manager without mouse dependency
7
9 ratpoison --help | --version
10 ratpoison [-d dpy] [-s num] [-f file]
11 ratpoison [-d dpy] [-s num] [-i] -c command [-c command ... ]
12
14 Ratpoison is a Window Manager without fat library dependencies, fancy
15 graphics or rat dependence.
16 The screen can be split into non-overlapping frames. All windows are
18 kept maximized inside their frames.
19 All interaction with the window manager is done through keystrokes.
21 ratpoison has a prefix map to minimize key clobbering.
22
24 -h, --help
25 Show summary of options.
26 -v, --version
28 Show version of program.
29 -d, --display display
31 Set the X display to use or send commands to.
32 -s, --screen number
34 Only use the specified screen.
35 -f, --file filename
37 Specify an alternate configuration file. If this is not given,
38 ratpoison will try $HOME/.ratpoisonrc and if that does not exist
39 /etc/ratpoisonrc and execute each command when starting up.
40 -i, --interactive
42 Execute commands given with -c or --command in interactive mode.
43 That means it will behave exactly as if called with C-t : like
44 prompting for missing arguments and things like that.
45 -c, --command
47 Send ratpoison a command. There must be a ratpoison instance
48 running as window manager for the given display/screen for this
49 to work. Do not forget to quote the command if it contains spa‐
50 ces. For example:
51 ratpoison -c "echo hallo world"
52
54 To avoid conflicts with other programs, all default ratpoison key bind‐
55 ings start with an escape key, per default C-t (read Control-t). Some
56 important default key bindings:
57 C-t q Quit ratpoison
59 C-t ? Show key bindings
60 C-t c Start an X terminal
61 C-t n Switch to next window
62 C-t p Switch to previous window
63 C-t 1|2|3|4|5|6|7|8|9 Switch to window number 1|2|...
64 C-t k Close the current window
65 C-t K XKill the current application
66 C-t s|S Split the current frame into two vertical|horizontal ones
67 C-t Tab|Left|Up|Right|Down Switch to the next|left|top|right|bottom
68 frame.
69 C-t Q Make the current frame the only one
70 C-t : Execute a ratpoison command
71 Further default key bindings can be found in parentheses after the com‐
73 mands in the next section:
74
76 abort (C-t C-g)
77 Do nothing and that successfully. (Useful if you pressed C-t in
78 error).
79 addhook event command
81 Add a hook: Run command command whenever event is called. Pos‐
82 sible events are:
83 deletewindowRun after a window is withdrawn.
84 key Run whenever a top level key is pressed. (by default
85 C-t)
86 quit Run before exiting ratpoison.
87 restart Run before restarting ratpoison.
88 switchframeRun after a frame actually switched, but before the
89 window in it is focused.
90 switchgroupRun after selecting a new group.
91 switchwin Run after a new window is selected. (With dedication,
92 it may already be inactive again, if it was put into another
93 frame)
94 alias alias command
96 Add alias as new way to call command.
97 bind key command
99 alias for "definekey root key command"
100 banish (C-t b)
102 Banish the rat cursor to the lower right corner of the screen.
103 banishrel
105 Banish the rat cursor to the lower right corner of the curren
106 window. If there isn't a window in the current frame, it ban‐
107 ishes the rat cursor to the lower right corner of the frame.
108 chdir [directory]
110 If the optional argument is given, change the current directory
111 of ratpoison to directory. If nothing is given, change it to
112 the value of the environment variable "HOME".
113 clrunmanaged
115 Clears the unmanaged window list.
116 cnext
118 Like next but switch to the next window with another resource
119 class than the current one. (That means the next window belong‐
120 ing to another type of application
121 than the current one.)
122 cprev
124 Like prev but switch to the previous window with another
125 resource class than the current one. (That means the previous
126 window belonging to another type of application
127 than the current one.)
128 colon ratpoison-command (C-t :)
130 Execute ratpoison-command interactively. (i.e. ask for possible
131 missing arguments.)
132 compat
134 Add aliases for the new set commands starting with def to sup‐
135 port older scripts.
136 cother
138 Like other but switch to the window of the current group that
139 was last accessed and has an other resource class but is not
140 currently visible.
141 curframe (C-t F)
143 Show a bar marking the current frame.
144 definekey keymap key command
146 Add a new key binding in keymap for key to execute command.
147 Default keymaps are top normally only containing C-t, which
148 reads a key from root, containing all the normal commands.
149 Note that you have to describe ":" by "colon", "!" by "exclam"
151 and so on. If you cannot guess a name of a key, try either C-t
152 key and look at the error message, or try :describekey root and
153 pressing the key.
154 def...
156 When compat was called there are some aliases starting with def,
157 which alias the new form with set. I.e. instead of defresizeu‐
158 nit better use the new set resizeunit and so on...
159 dedicate [0|1]
161 Consider the current frame dedicated/chaste (1) or promiscuous
162 (0).
163 A dedicated frame will not accept new windows. When new windows
164 are to be focused, they will be opened in a non-dedicated frame
165 instead.
166 If no argument is given, toggle the current dedicateness. By
167 default no windows are dedicated.
168 delete (C-t k)
170 Close the current window.
171 delkmap keymap
173 Deletes the keymap named keymap, that was generated with
174 newkmap. The keymaps top (or whatever was specified by set top‐
175 kmap) and root cannot be deleted.
176 describekey keymap
178 Grab the next key. Similar to readkey, describekey shows only
179 the command in keymap, that would be executed by readkey.
180 echo text
182 Show text as ratpoison message.
183 escape key
185 Update the default escape key to key.
186 Strictly speaking it updates the the readkey root command in the
187 keymap top to key, the other binding in root to key, and meta
188 binding in root to key without modifiers or C-key if key has no
189 modifiers. (If set topkmap was called with an argument other
190 than top that will be used instead of top.)
191 exchangedown (C-t C-Down)
193 Exchange the window in the current frame with the window in the
194 frame below the current frame.
195 exchangeleft (C-t C-Left)
197 Exchange the window in the current frame with the window in the
198 frame left of the current frame.
199 exchangeright (C-t C-Right)
201 Exchange the window in the current frame with the window in the
202 frame right of the current frame.
203 exchangeup (C-t C-Up)
205 Exchange the window in the current frame with the window in the
206 frame above the current frame.
207 exec shell-command (C-t !)
209 Spawn a shell executing shell-command.
210 execa shell-command
212 Spawn a shell executing shell-command, without remembering the
213 current frame, so that _NET_WM_PID declaring programs will be
214 placed into the frame active when they open a window instead of
215 the frame active when ratpoison gets this command.
216 execf frame shell-command
218 Spawn a shell executing shell-command, showing _NET_WM_PID sup‐
219 porting programs in the given frame instead of the frame
220 selected when this program is run.
221 fdump [screenno]
223 Output the defining data for all frames of the current screen,
224 or for screen number screenno if this is specified.
225 focus (C-t Tab)
227 Focus the next frame.
228 focuslast
230 Switch to the last selected focus.
231 focusleft (C-t Left)
233 Switch to the frame to the left of the current one.
234 focusdown (C-t Down)
236 Switch to the frame beneath the current one.
237 focusright (C-t Right)
239 Switch to the frame to the right of the current one.
240 focusprev
242 Focus the previous frame.
243 focusup (C-t Up)
245 Switch to the frame above the current one.
246 frestore frames
248 Replace the current frames with the ones specified in frames in
249 the format as generated by fdump.
250 fselect [frameno] (C-t f)
252 If an argument is supplied, switch to a frame given by number
253 frameno.
254 If no argument is given, show a frame selector in each frame and
256 wait for a key to be pressed. If the key matches an existing
257 frame selector, this frame gets focused.
258 Frame selectors are by default the numbers starting with zero,
260 but they can be changed by seting framesels.
261 gdelete [group]
263 If the optional argument group is supplied, delete group group.
264 Otherwise delete the current group. If the last group is
265 deleted, a new group with name default is created. The group
266 has to be empty, otherwise it cannot be deleted.
267 getenv variable
269 Output the value of the environment variable variable.
270 getsel
272 Paste the current X Selection into the current window.
273 gmerge group
275 Move all windows from group group into the current group.
276 gmove group
278 Move the current window into group group.
279 gnew group
281 Create a new group with name group and select it. Most window
282 commands only see (and thus select, consider next, previous or
283 last) windows within the group active when they are issued.
284 gnewbg group
286 Create a new group named groupf, but do not select it.
287 gnext
289 Select the next group. Most window commands only see windows in
290 the effective group.
291 gother
293 Select the last accessed group. Most window commands only see
294 windows in the effective group.
295 gprev
297 Select the prior group. Most window commands only see windows in
298 the effective group.
299 gravity [nw|w|sw|n|c|s|ne|e|se]
301 Change how in its frame the current window is aligned.
302 grename
304 Rename current group.
305 groups
307 Output a list of all groups with their number.
308 gselect group
310 Select the group names group.
311 help [keymap]
313 If the optional parameter keymap is given, list all keybindings
314 in this keymap, otherwise list all key bindings in keymap root.
315 hsplit [l/p|pixels from left|-pixels from right] (C-t S)
317 Split the current frame into left frame and a right frame. If
318 no parameter is given, split in halves. If two numbers sepa‐
319 rated by a slash ("/") are given, the left one is l times the
320 pth part and the right one (p-l) times the pth part of the prior
321 width. Otherwise the right one is pixels from right wide or the
322 left one pixels from left wide, depending whether there is - in
323 front of the number or not.
324 inext
326 Like next but switch to the next window with the same resource
327 class as the current one. (That means the next window belonging
328 to the same application
329 as the current one.)
330 info (C-t i)
332 Output the current the width, height, window number and window
333 name of the current window. (What name means is chosen by
334 "set winname".)
335 iprev
337 Like prev but switch to the previous window with the same
338 resource class as the current one. (That means the previous
339 window belonging to the same application
340 as the current one.)
341 iother
343 Like other but switch to the window of the current group that
344 was last accessed and has the same resource class but is not
345 currently visible.
346 kill (C-t K)
348 Close the X-connection of the X-client responsible for the cur‐
349 rent window.
350 lastmsg (C-t m)
352 Reshow the last message.
353 license (C-t V)
355 Show ratpoison's license.
356 link key [keymap]
358 Do what key is bound to in the keymap keymap if supplied. Oth‐
359 erwise what key is bound to in keymap root.
360 listhook event
362 List all commands specified with addhook to be executed when
363 even event occurs.
364 meta [key] (C-t t)
366 Send the escape key (that which normally is C-t) to the current
367 window. If a key is specified, this is sent instead. Note that
368 some applications by default ignore the synthetic key that is
369 sent using this command as it is considered a security hole.
370 xterm is one such application.
371 msgwait [seconds]
373 Set the duration the message window is shown. If seconds is
374 zero, wait infinitely.
375 newkmap keymap
377 Generate a new keymap names keymap. This keymap can be used to
378 add new key-command mapping to it with definekey and can be
379 called with readkey.
380 newwm new window manager
382 Quit ratpoison and execute new window manager instead.
383 next (C-t Return|C-t n|C-t space)
385 Switch to the next window in the current group.
386 nextscreen
388 Switch to the next screen. (If you have multiple physical ones.)
389 number new [old]
391 Give the number new to the window with the number old or the
392 current window.
393 only (C-t Q)
395 Remove all frames on the current screen except the current frame
396 and maximise this one to the size of the whole screen.
397 other (C-t C-t)
399 Switch to the window of the current group that was last accessed
400 but is not currently visible.
401 prev (C-t p)
403 Switch to the previous window in the current group.
404 prevscreen
406 Switch to the previous screen. (If you have multiple physical
407 ones.)
408 prompt [prompt]
410 Ratpoison will ask the user for input, showing prompt (or a sin‐
411 gle colon, if no argument is given) and output the input the
412 user has made.
413 Note that this command probably does not make much sense in
414 interactive mode.
415 putsel x-selection
417 Replace the X selection with the text x-selection. It can be
418 inserted into the current window with getsel.
419 quit
421 Quit ratpoison.
422 ratinfo
424 Display the x y coordinates of the rat cursor relative to the
425 screen.
426 ratrelinfo
428 Display the x y coordinates of the rat cursor relative to the
429 current window or current frame if no window is focused
430 ratwarp x y
432 Move the rat cursor to the position (x,y).
433 ratrelwarp deltax deltay
435 Move the rat cursor to (deltax,deltay), relative to the current
436 position.
437 ratclick [button]
439 Simulate a rat click with button (button 1=left button if none
440 given).
441 rathold up|down [button]
443 Simulate pressing|releasing rat button button (1=left button if
444 none given).
445 readkey keymap
447 Grab the next key pressed, and execute the command associated to
448 this key in keymap. To show it is waiting for a key, ratpoison
449 will change the rat cursor to a square if waitcursor is set.
450 This command is perhaps best described with its usage in the
452 default configuration: By pressing C-t, which is the only key in
453 the keymap top, the command "readkey root" is executed. The next
454 key then executes the command in keymap root belonging to this
455 command.
456 redisplay (C-t l)
458 Extend the current window to the whole size of its current frame
459 and redisplay it. (Useful to redisplay normal windows or bring
460 transient windows to the full size of the frame as only normal
461 windows are maximized by ratpoison)
462 redo (C-t U)
464 Revert the last undo of frame changes.
465 remhook event command
467 Remove command command from the list of commands to be called
468 when event event is hit. (The command has to specified, as an
469 event can have multiple commands attached to it.) Use "listhook
470 hook" to get a list of all attached commands.
471 remove (C-t R)
473 Remove the current frame and extend some frames around to fill
474 the remaining gap.
475 resize [deltax deltay] (C-t r)
477 If deltax and deltay are supplied, resize the current frame by
478 that (i.e. move the bottom right corner by the given offsets and
479 then move this frame and resize adjacent frames to make the
480 frames fill the whole screen again.)
481 If in interactive mode no arguments are supplied, resize the
483 current frame interactively:
484 Return: finish resizing
485 C-g or Escape: abort resizing
486 C-n or Down or j: grow vertically
487 C-p or Up or k: shrink vertically
488 C-f or Right or l: grow horizontally
489 C-b or Up or h: shrink horizontally
490 s: shrink to size of current window
491 While resizing interactively, changes are in multiples of the
493 amount of pixels given by set resizeunit (by default 10).
494 restart
496 Restart ratpoison.
497 rudeness [rudeness]
499 Show or set what kind of windows are allowed to jostle into the
500 foreground.
501 rudeness is a bitwise or of the following values:
503 1 Transient windows may raise.
504 2 Normal windows may raise.
505 4 New transient windows end up in the foreground.
506 8 New normal windows end up in the foreground.
507 Default is all allowed i.e. 15.
509 sdump
512 Output the list of all screens. The screens are separated by
513 commas. Each screen is shown as 6 values: its number, its
514 x-coordinate, its y-coordinate, its width, its height and if it
515 is currently selected (1=true,0=false).
516 select -|name|nr (C-t ')
518 If a number is given, switch to the window with number nr. If a
519 name is given, switch to the window in the current group with
520 name name. Blank the current frame, if - is given.
521 set [variable [value]]
523 If no argument is given, output all ratpoison variables and
524 their values.
525 If one argument is given, output the value of ratpoison variable
526 variable.
527 Otherwise set ratpoison variable variable to value. What values
528 are valid depends on the variable. See the section VARIABLES
529 later in this document for details.
530 setenv variable value
532 Set the environment variable variable to value. (Environment
533 variables will be passed to all programs started from ratpoi‐
534 son.)
535 sfdump
537 Output all frames similar to fdump, but not limited to one
538 screen, but all screens at once and with the screen number after
539 each frame.
540 sfrestore
542 Replace the current frames with the ones specified in frames in
543 the format as generated by sfdump.
544 shrink
546 Shrink the current frame to the size of the current window with
547 in.
548 split [split] (C-t s)
550 alias for vsplit
551 source file
553 Read file and execute each line as ratpoison command.
554 sselect screennumber
556 Switch to the screen screennumber. (If you have multiple physi‐
557 cal ones.)
558 startup_message on|off
560 Select whether ratpoison will show a startup message or not.
561 swap [dest-frame [src-frame]] (C-t x)
563 Exchange the window in src-frame (or the current frame if there
564 is no second argument) with the window dest-frame (or ask inter‐
565 actively which frame to swap with if there is no argument).
566 time (C-t a)
568 Output current data and time.
569 title newname (C-t A)
571 Overwrite the title of the current window with newname. All
572 following ratpoison commands will only know the window under the
573 new name.
574 tmpwm tmpwm
576 Temporarily give control over to the other window manager tmpwm,
577 reclaiming control when that WM terminates.
578 unalias alias
580 Remove the alias alias.
581 unbind key
583 alias for "undefinekey root key"
584 undefinekey keymap key
586 Remove the binding for key from keymap.
587 undo (C-t _ or C-t u)
589 Un-do the last change to the frameset. (Like splitting, resiz‐
590 ing, deleting, ...)
591 The amount of steps that can be undone is specified by the vari‐
592 able maxundos.
593 unmanage [name]
595 Add name to the list of unmanaged windows. Thus, windows of
596 this name will not be managed but allowed to choose their posi‐
597 tion themselves.
598 In non-interactive mode calling it without arguments will print
600 the list.
601 The list can be cleared again by calling clrunmanaged.
603 unsetenv variable
605 Remove variable variable from the list of environment variables.
606 verbexec cmdline
608 Spawn a shell executing cmdline after showing a message with the
609 command.
610 version (C-t v)
612 Output version and compile time information.
613 vsplit [l/p|pixels from top|-pixels from bottom] (C-t s)
615 Split the current frame into upper frame and a lower frame. If
616 no parameter is given, split in halves. If two numbers sepa‐
617 rated by a slash ("/") are given, the upper one is l times the
618 pth part and the lower one (p-l) times the pth part of the prior
619 height. Otherwise the lower one is pixels from bottom wide or
620 the upper one pixels from top high, depending whether there is a
621 - in front of the number or not.
622 warp [on|off]
624 Select if focusing a window moves the rat cursor to the place it
625 had been last time this window was focused, or not.
626 windows [format] (C-t w)
628 In interactive mode, show the list of all windows in the current
629 group for the duration specified by msgwait If msgwait is zero,
630 toggle between indefinitely showing and not showing.
631 The messages are shown in columns or rows depending on the set‐
633 ting of winliststyle in the format set by set winfmt. The fol‐
634 lowing substitutions happen in format:
635 %a by the application name (resource name),
636 %c by the resource class,
637 %f by the frame number,
638 %g by the gravity of the window,
639 %h by the height of the window,
640 %H by the unit to resize the window vertically (height_inc)
641 %i by the X Window ID,
642 %p by the process ID,
643 %l by the last access number,
644 %M by the string Maxsize, if it specifies a maximum size,
645 %n by the window number,
646 %s by window status (* is active window, + would be chosen by
647 other, - otherwise)
648 %S by the screen number
649 %t by the window name (see set winname),
650 %T by the string Transient, if it is a transient window
651 %w by the width of the window
652 %W by the unit to resize the window horizontally (width_inc)
653 %x by the xine screen number and
654 %% by a single %
655 Additionally there can be a positive decimal integer number
657 between the percent sign and the format string to specify the
658 length this value should be truncated to if longer. (For exam‐
659 ple: %20t)
660 In non-interactive mode, output the list of windows in the cur‐
662 rent group line by line. The format string can be overwritten by
663 the optional parameter format.
664
666 Ratpoison variables can be shown and set with set. There are:
667 resizeunit pixels
669 Set the amount of pixels interactive resizeing will add/subtract
670 in each step.
671 Default is 5.
672 maxundos number
674 The maximal amount of step ratpoison can undo with the undo com‐
675 mand.
676 Default is 20.
677 wingravity nw|w|sw|n|c|s|ne|e|se
679 Set the default gravity new normal windows will get. Possible
680 values are the same as in the gravity command, which changes the
681 gravity of an existing window: cardinal points or numbers 1 to
682 9.
683 Default is northwest.
684 maxsizegravity nw|w|sw|n|c|s|ne|e|se
686 Set the default gravity new self-maximised windows will get.
687 Possible values are the same as in the gravity command, which
688 changes the gravity of an existing window: cardinal points or
689 numbers 1 to 9.
690 Default is center.
691 transgravity nw|w|sw|n|c|s|ne|e|se
693 Set the default gravity new transient windows will get. Possi‐
694 ble values are the same as in the gravity command, which changes
695 the gravity of an existing window: cardinal points or numbers 1
696 to 9.
697 Default is center.
698 bargravity nw|w|sw|n|c|s|ne|e|se
700 Select the location where message and prompt bars appear.
701 Default is northeast.
702 font font
704 Make ratpoison use font font.
705 padding left top right bottom
707 Set how much space at the borders of the screen will not be
708 used.
709 Default is 0 0 0 0.
710 border pixels
712 Selects how thick the frame around windows is.
713 Default is 1.
714 barborder pixels
716 Selects how thick the frame around ratpoison's prompt or message
717 windows is.
718 Default is 1.
719 inputwidth pixels
721 Determine the width of the input window.
722 Default is 200.
723 barinpadding 0|1
725 If there is padding, determines whether the bar appears at the
726 edge of the screen (1) or at the edge of the window area (0).
727 Default is 0.
728 topkmap kmap
730 Make kmap the top keymap ratpoison graps directly. The default
731 value is top.
732 waitcursor 0|1
734 Determine whether to change the rat cursor when waiting for a
735 key (1) or not (0). (see readkey and describekey).
736 Default is 1.
737 winfmt format
739 Choose the default format for the the windows command.
740 Default is %n%s%t.
741 winname title|name|class
743 Choose what is considered the "name" of the window by ratpoison:
744 title The title of the window.
745 name The resource name of the window.
746 class The resource class i.e. the name of the application.
747 Default is title.
748 fgcolor color
750 The foreground color of the windows ratpoison creates.
751 Default is black.
752 bgcolor color
754 The background color of the windows ratpoison creates.
755 Default is white.
756 fwcolor color
758 The border color of the focused window.
759 Default is black.
760 bwcolor color
762 The border color of unfocused windows.
763 Default is black.
764 barpadding x y
766 Set horizontal padding of ratpoison windows to x and vertical
767 padding to y.
768 Default is 4 0
769 winliststyle row|column
771 Determines whether windows are shown in rows or in columns.
772 Default is column.
773 framesels selectors
775 Override the frame selectors fselect uses. The first character
776 is the selector for the first frame, the second character is the
777 selector for the second frame and so on.
778 Using this variable, one can directly access more than 10
780 frames.
781 Default is an empty string, which is equivalent to "0123456789".
783 historysize number
785 Specify maximum number of values kept in input history.
786 Default is 20.
788 historycompaction 0|1
790 Decide if new input lines added to history delete older equal
791 lines from history.
792 Default is 1 (on).
794 historyexpansion 0|1
796 Decide if history expansion using ! is available. (Can only be
797 activated when compiled with readline's libhistory.)
798 Default is 0 (off).
800
802 Upstream Author is Shawn Betts <sabetts@vcn.bc.ca>.
803 See /usr/share/doc/ratpoison/AUTHORS for other contributors.
804 This manual page was written by Bernhard R. Link <brlink@debian.org>.
806 2008-06-15 RATPOISON(1)