1RATPOISON(1) BSD General Commands Manual RATPOISON(1)
2
4 ratpoison — window manager without mouse dependency
5
7 ratpoison [-hv]
8 ratpoison [-d dpy] [-s num] [-f file]
9 ratpoison [-d dpy] [-s num] [-i] -c command [-c command ...]
10
12 ratpoison is a Window Manager without fat library dependencies, fancy
13 graphics or rat dependence.
14 The screen can be split into non-overlapping frames. All windows are
16 kept maximized inside their frames.
17 All interaction with the window manager is done through keystrokes.
19 ratpoison has a prefix map to minimize key clobbering.
20 The options are as follows:
22 -c, --command
24 Send ratpoison a command. There must be a ratpoison instance running
25 as window manager for the given display/screen for this to work. Do
26 not forget to quote the command if it contains spaces. For example:
27 ratpoison -c "echo hello world"
28 -d, --display display
30 Set the X display to use or send commands to.
31 -f, --file filename
33 Specify an alternate configuration file. If this is not given,
34 ratpoison will try $HOME/.ratpoisonrc and if that does not exist
35 /etc/ratpoisonrc and execute each command when starting up.
36 -h, --help
38 Show summary of options.
39 -i, --interactive
41 Execute commands given with -c or --command in interactive mode.
42 That means it will behave exactly as if called with C-t : like
43 prompting for missing arguments and things like that.
44 -s, --screen number
46 Only use the specified screen.
47 -v, --version
49 Show version of program.
50
52 To avoid conflicts with other programs, all default ratpoison key bind‐
53 ings start with an escape key, per default C-t (read Control-t). Some
54 important default key bindings:
55 C-t ? Show key bindings
57 C-t c Start an X terminal
59 C-t n Switch to next window
61 C-t p Switch to previous window
63 C-t 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
65 Switch to window number 1 | 2 | ...
66 C-t k Close the current window
68 C-t K XKill the current application
70 C-t s | S
72 Split the current frame into two vertical | horizontal ones
73 C-t Tab | Left | Up | Right | Down
75 Switch to the next | left | top | right | bottom frame.
76 C-t Q Make the current frame the only one
78 C-t : Execute a ratpoison command
80 Further default key bindings can be found in parentheses after the com‐
82 mands in the next section.
83
85 abort (C-t C-g) Do nothing and that successfully. (Useful if you
86 pressed C-t in error).
87 addhook event command
89 Add a hook: run command whenever event is called. Possible
90 events are:
91 deletewindow
93 Run after a window is withdrawn.
94 newwindow
96 Run after a new window is mapped.
97 key Run whenever a top level key is pressed (by default C-t).
99 quit Run before exiting ratpoison.
101 restart
103 Run before restarting ratpoison.
104 switchframe
106 Run after a frame actually switched, but before the win‐
107 dow in it is focused.
108 switchgroup
110 Run after selecting a new group.
111 switchscreen
113 Run when the user switches to a different screen.
114 switchwin
116 Run after a new window is selected. (With dedication, it
117 may already be inactive again, if it was put into another
118 frame)
119 alias alias command
121 Add alias as new way to call command.
122 bind key command
124 alias for "definekey root key command"
125 banish (C-t b) Banish the rat cursor to the lower right corner of the
127 screen.
128 banishrel
130 Banish the rat cursor to the lower right corner of the current
131 window. If there isn't a window in the current frame, it ban‐
132 ishes the rat cursor to the lower right corner of the frame.
133 chdir [directory]
135 If the optional argument is given, change the current directory
136 of ratpoison to directory. If nothing is given, change it to the
137 value of the environment variable "HOME".
138 clrunmanaged
140 Clears the unmanaged window list.
141 cnext Like next but switch to the next window with another resource
143 class than the current one. (That means the next window belong‐
144 ing to another type of application than the current one.)
145 cprev Like prev but switch to the previous window with another resource
147 class than the current one. (That means the previous window
148 belonging to another type of application than the current one.)
149 colon ratpoison-command (C-t :)
151 Execute ratpoison-command interactively. (i.e. ask for possible
152 missing arguments.)
153 cother Like other but switch to the window of the current group that was
155 last accessed and has another resource class but is not currently
156 visible.
157 curframe (C-t F)
159 Show a bar marking the current frame.
160 definekey keymap key command
162 Add a new key binding in keymap for key to execute command.
163 Default keymaps are top normally only containing C-t, which reads
164 a key from root, containing all the normal commands.
165 Note that you have to describe ":" by "colon", "!" by "exclam"
167 and so on. If you cannot guess a name of a key, try either C-t
168 key and look at the error message, or try :describekey root and
169 pressing the key.
170 dedicate [0 | 1]
172 Consider the current frame dedicated/chaste (1) or promiscuous
173 (0).
174 A dedicated frame will not accept new windows. When new windows
176 are to be focused, they will be opened in a non-dedicated frame
177 instead.
178 If no argument is given, toggle the current dedicateness. By
180 default no windows are dedicated.
181 delete (C-t k)
183 Close the current window.
184 delkmap keymap
186 Deletes the keymap named keymap, that was generated with newkmap.
187 The keymaps top (or whatever was specified by set topkmap) and
188 root cannot be deleted.
189 describekey keymap
191 Grab the next key. Similar to readkey, describekey shows only the
192 command in keymap, that would be executed by readkey.
193 echo text
195 Show text as ratpoison message.
196 escape key
198 Update the default escape key to key.
199 Strictly speaking it updates the readkey root command in the
201 keymap top to key, the other binding in root to key, and meta
202 binding in root to key without modifiers or C-key if key has no
203 modifiers. (If set topkmap was called with an argument other
204 than top that will be used instead of top.)
205 exchangedown (C-t C-Down)
207 Exchange the window in the current frame with the window in the
208 frame below the current frame.
209 exchangeleft (C-t C-Left)
211 Exchange the window in the current frame with the window in the
212 frame left of the current frame.
213 exchangeright (C-t C-Right)
215 Exchange the window in the current frame with the window in the
216 frame right of the current frame.
217 exchangeup (C-t C-Up)
219 Exchange the window in the current frame with the window in the
220 frame above the current frame.
221 exec shell-command (C-t !)
223 Spawn a shell executing shell-command.
224 execa shell-command
226 Spawn a shell executing shell-command, without remembering the
227 current frame, so that _NET_WM_PID declaring programs will be
228 placed into the frame active when they open a window instead of
229 the frame active when ratpoison gets this command.
230 execf frame shell-command
232 Spawn a shell executing shell-command, showing _NET_WM_PID sup‐
233 porting programs in the given frame instead of the frame selected
234 when this program is run.
235 fdump [screenno]
237 Output the defining data for all frames of the current screen, or
238 for screen number screenno if this is specified.
239 focus (C-t Tab)
241 Focus the next frame.
242 focuslast
244 Switch to the last selected focus.
245 focusleft (C-t Left)
247 Switch to the frame to the left of the current one.
248 focusdown (C-t Down)
250 Switch to the frame beneath the current one.
251 focusright (C-t Right)
253 Switch to the frame to the right of the current one.
254 focusprev
256 Focus the previous frame.
257 focusup (C-t Up)
259 Switch to the frame above the current one.
260 frestore frames
262 Replace the current frames with the ones specified in frames in
263 the format as generated by fdump.
264 fselect [frameno] (C-t f)
266 If an argument is supplied, switch to a frame given by number
267 frameno.
268 If no argument is given, show a frame selector in each frame and
270 wait for a key to be pressed. If the key matches an existing
271 frame selector, this frame gets focused.
272 Frame selectors are by default the numbers starting with zero,
274 but they can be changed by setting framesels.
275 gdelete [group]
277 If the optional argument group is supplied, delete group. Other‐
278 wise delete the current group. If the last group is deleted, a
279 new group with name default is created. The group has to be
280 empty, otherwise it cannot be deleted.
281 getenv variable
283 Output the value of the environment variable variable.
284 getsel Paste the current X Selection into the current window.
286 gmerge group
288 Move all windows from group group into the current group.
289 gmove group
291 Move the current window into group group.
292 gnew group
294 Create a new group with name group and select it. Most window
295 commands only see (and thus select, consider next, previous or
296 last) windows within the group active when they are issued.
297 gnewbg group
299 Create a new group named group, but do not select it.
300 gnext Select the next group. Most window commands only see windows in
302 the effective group.
303 gnumber [old new]
305 Give the number new to the group with the number old or the cur‐
306 rent group.
307 gother Select the last accessed group. Most window commands only see
309 windows in the effective group.
310 gprev Select the prior group. Most window commands only see windows in
312 the effective group.
313 gravity [nw | w | sw | n | c | s | ne | e | se]
315 Change how in its frame the current window is aligned.
316 grename
318 Rename current group.
319 groups Output a list of all groups with their number.
321 gselect group
323 Select the group named group.
324 help [keymap]
326 If the optional parameter keymap is given, list all keybindings
327 in this keymap, otherwise list all key bindings in keymap root.
328 hsplit [l/p | [-]pixels] (C-t S)
330 Split the current frame into left frame and a right frame. If no
331 parameter is given, split in halves. If two numbers separated by
332 a slash (‘/’) are given, the left one is l times the pth part and
333 the right one (p - l) times the pth part of the prior width.
334 Otherwise the right half is pixels wide or the left one is pixels
335 wide, depending whether there is ‘-’ in front of the number or
336 not.
337 inext Like next but switch to the next window with the same resource
339 class as the current one. (That means the next window belonging
340 to the same application as the current one.)
341 info (C-t i)
343 Output the current the width, height, window number and window
344 name of the current window. (What name means is chosen by “set
345 winname”.)
346 iprev Like prev but switch to the previous window with the same
348 resource class as the current one. (That means the previous win‐
349 dow belonging to the same application as the current one.)
350 iother Like other but switch to the window of the current group that was
352 last accessed and has the same resource class but is not cur‐
353 rently visible.
354 kill (C-t K)
356 Close the X-connection of the X-client responsible for the cur‐
357 rent window.
358 lastmsg (C-t m)
360 Reshow the last message.
361 license (C-t V)
363 Show ratpoison's license.
364 link key [keymap]
366 Do what key is bound to in the keymap keymap if supplied. Other‐
367 wise what key is bound to in keymap root.
368 listhook event
370 List all commands specified with addhook to be executed when even
371 event occurs.
372 meta [key] (C-t t)
374 Send the escape key (that which normally is C-t) to the current
375 window. If a key is specified, this is sent instead. Note that
376 some applications by default ignore the synthetic key that is
377 sent using this command as it is considered a security hole.
378 xterm is one such application.
379 msgwait [seconds]
381 Set the duration the message window is shown. If seconds is
382 zero, wait infinitely. This command is deprecated, please set
383 the msgwait variable instead.
384 newkmap keymap
386 Generate a new keymap named keymap. This keymap can be used to
387 add new key-command mappings to it with definekey and can be
388 called with readkey.
389 newwm new-window-manager
391 Quit ratpoison and execute new-window-manager instead.
392 next (C-t Return | C-t n | C-t space)
394 Switch to the next window in the current group.
395 nextscreen (C-t N)
397 Switch to the next screen. (If you have multiple physical ones.)
398 number new [old]
400 Give the number new to the window with the number old or the cur‐
401 rent window.
402 only (C-t Q)
404 Remove all frames on the current screen except the current frame
405 and maximize this one to the size of the whole screen.
406 other (C-t C-t)
408 Switch to the window of the current group that was last accessed
409 but is not currently visible.
410 prev (C-t p)
412 Switch to the previous window in the current group.
413 prevscreen (C-t P)
415 Switch to the previous screen. (If you have multiple physical
416 ones.)
417 prompt [prompt]
419 ratpoison will ask the user for input, showing prompt (or a sin‐
420 gle colon, if no argument is given) and output the input the user
421 has made. Note that this command probably does not make much
422 sense in interactive mode.
423 putsel x-selection
425 Replace the X selection with the text x-selection. It can be
426 inserted into the current window with getsel.
427 quit Quit ratpoison.
429 ratinfo
431 Display the x y coordinates of the rat cursor relative to the
432 screen.
433 ratrelinfo
435 Display the x y coordinates of the rat cursor relative to the
436 current window or current frame if no window is focused
437 ratwarp x y
439 Move the rat cursor to the position (x, y).
440 ratrelwarp deltax deltay
442 Move the rat cursor to (deltax, deltay), relative to the current
443 position.
444 ratclick [button]
446 Simulate a rat click with button (button 1=left button if none
447 given).
448 rathold (up | down) [button]
450 Simulate pressing|releasing rat button button (1=left button if
451 none given).
452 readkey keymap
454 Grab the next key pressed, and execute the command associated to
455 this key in keymap. To show it is waiting for a key, ratpoison
456 will change the rat cursor to a square if waitcursor is set.
457 This command is perhaps best described with its usage in the
458 default configuration: by pressing C-t, which is the only key in
459 the keymap top , the command "readkey root" is executed. The
460 next key then executes the command in keymap root belonging to
461 this command.
462 redisplay (C-t l)
464 Extend the current window to the whole size of its current frame
465 and redisplay it. (Useful to redisplay normal windows or bring
466 transient windows to the full size of the frame as only normal
467 windows are maximized by ratpoison)
468 redo (C-t U)
470 Revert the last undo of frame changes.
471 remhook event command
473 Remove command command from the list of commands to be called
474 when event event is hit. (The command has to specified, as an
475 event can have multiple commands attached to it.) Use "listhook
476 hook" to get a list of all attached commands.
477 remove (C-t R)
479 Remove the current frame and extend some frames around to fill
480 the remaining gap.
481 resize [deltax deltay] (C-t r)
483 If deltax and deltay are supplied, resize the current frame by
484 that (i.e. move the bottom right corner by the given offsets and
485 then move this frame and resize adjacent frames to make the
486 frames fill the whole screen again.)
487 If in interactive mode no arguments are supplied, resize the cur‐
489 rent frame interactively:
490 Return finish resizing
492 C-g, Escape abort resizing
493 C-n, Down, j grow vertically
494 C-p, Up, k shrink vertically
495 C-f, Right, l grow horizontally
496 C-b, Up, h shrink horizontally
497 s shrink to size of current window
498 While resizing interactively, changes are in multiples of the
500 amount of pixels given by set resizeunit (by default 10).
501 restart
503 Restart ratpoison.
504 rudeness [rudeness]
506 This command is deprecated, please use the rudeness variable
507 instead.
508 sdump Output the list of all screens. The screens are separated by
510 commas. Each screen is shown as 6 values: its number, its x-coor‐
511 dinate, its y-coordinate, its width, its height and if it is cur‐
512 rently selected (1=true, 0=false).
513 select (- | name | number) (C-t ')
515 If a number is given, switch to the window with number number.
516 If a name is given, switch to the window in the current group
517 with name name. Blank the current frame, if - is given.
518 set [variable [value]]
520 If no argument is given, output all ratpoison variables and their
521 values.
522 If one argument is given, output the value of ratpoison variable
524 variable. Otherwise set variable to value. What values are
525 valid depends on the variable. See the section VARIABLES later
526 in this document for details.
527 setenv variable value
529 Set the environment variable variable to value. (Environment
530 variables will be passed to all programs started from ratpoison.)
531 sfdump Output all frames similar to fdump, but not limited to one
533 screen, but all screens at once and with the screen number after
534 each frame.
535 sfrestore frames
537 Replace the current frames with the ones specified in frames in
538 the format as generated by sfdump.
539 shrink Shrink the current frame to the size of the current window with
541 in.
542 split [split] (C-t s)
544 alias for vsplit
545 source file
547 Read file and execute each line as ratpoison command.
548 sselect screennumber
550 Switch to the screen screennumber. (If you have multiple physi‐
551 cal ones.)
552 startup_message (on | off)
554 Select whether ratpoison will show a startup message or not.
555 This command is deprecated, please use the startupmessage vari‐
556 able instead.
557 swap dest-frame [src-frame] (C-t x)
559 Exchange the window in src-frame (or the current frame if there
560 is no second argument) with the window dest-frame (or ask inter‐
561 actively which frame to swap with if there is no argument).
562 time (C-t a)
564 Output current data and time.
565 title newname (C-t A)
567 Overwrite the title of the current window with newname. All fol‐
568 lowing ratpoison commands will only know the window under the new
569 name.
570 tmpwm tmpwm
572 Temporarily give control over to the other window manager tmpwm,
573 reclaiming control when that WM terminates.
574 unalias alias
576 Remove the alias alias.
577 unbind key
579 alias for
580 undefinekey root key
581 undefinekey keymap key
583 Remove the binding for key from keymap.
584 undo (C-t _, C-t u)
586 Un-do the last change to the frameset. (Like splitting, resiz‐
587 ing, deleting, ...)
588 The amount of steps that can be undone is specified by the vari‐
590 able maxundos.
591 unmanage [name]
593 Add name to the list of unmanaged windows. Thus, windows of this
594 name will not be managed but allowed to choose their position
595 themselves.
596 In non-interactive mode calling it without arguments will print
598 the list.
599 The list can be cleared again by calling clrunmanaged.
601 unsetenv variable
603 Remove variable variable from the list of environment variables.
604 verbexec cmdline
606 Spawn a shell executing cmdline after showing a message with the
607 command.
608 version (C-t v)
610 Output version and compile time information.
611 vsplit [l/p | pixels-from-top | -pixels-from-bottom] (C-t s)
613 Split the current frame into upper frame and a lower frame. If
614 no parameter is given, split in halves. If two numbers separated
615 by a slash (“/”) are given, the upper one is l times the pth part
616 and the lower one (p - l) times the pth part of the prior height.
617 Otherwise the lower one is pixels from bottom wide or the upper
618 one pixels from top high, depending whether there is a “-” in
619 front of the number or not.
620 warp (on | off)
622 Select if focusing a window moves the rat cursor to the place it
623 had been last time this window was focused, or not. This command
624 is deprecated, please set the warp variable instead.
625 windows [format] (C-t w)
627 In interactive mode, show the list of all windows in the current
628 group for the duration specified by the variable msgwait. If
629 msgwait was zero, toggle between indefinitely showing and not
630 showing.
631 The messages are shown in columns or rows depending on the value
633 of winliststyle in the format set by set winfmt. The following
634 substitutions happen in format:
635 %a application name (resource name)
637 %c resource class
638 %f frame number
639 %g gravity of the window
640 %h height of the window
641 %H unit to resize the window vertically (height_inc)
642 %i X Window ID
643 %p process ID
644 %l last access number
645 %M string Maxsize, if it specifies a maximum size
646 %n window number
647 %s window status (‘*’ is active window, ‘+’ would be chosen by
648 other, ‘-’ otherwise)
649 %S screen number
650 %t window name (see set winname),
651 %T the string “Transient”, if it is a transient window
652 %w width of the window
653 %W unit to resize the window horizontally (width_inc)
654 %x xine screen number
655 %% litteral ‘%’
656 Additionally there can be a positive decimal integer number
658 between the percent sign and the format string to specify the
659 length this value should be truncated to if longer. (For
660 example: %20t)
661 In non-interactive mode, output the list of windows in the cur‐
663 rent group line by line. The format string can be overwritten by
664 the optional parameter format.
665
667 ratpoison variables can be shown and set with set. The following vari‐
668 ables are supported:
669 resizeunit pixels
671 Set the amount of pixels interactive resize will add/subtract in
672 each step.
673 Default is 5.
675 maxundos number
677 The maximal amount of step ratpoison can undo with the undo com‐
678 mand.
679 Default is 20.
681 wingravity nw | w | sw | n | c | s | ne | e | se
683 Set the default gravity new normal windows will get. Possible
684 values are the same as in the gravity command, which changes the
685 gravity of an existing window: cardinal points or numbers 1 to 9.
686 Default is nw.
688 maxsizegravity nw | w | sw | n | c | s | ne | e | se
690 Set the default gravity new self-maximized windows will get.
691 Possible values are the same as in the gravity command, which
692 changes the gravity of an existing window: cardinal points or
693 numbers 1 to 9.
694 Default is c.
696 transgravity nw | w | sw | n | c | s | ne | e | se
698 Set the default gravity new transient windows will get. Possible
699 values are the same as in the gravity command, which changes the
700 gravity of an existing window: cardinal points or numbers 1 to 9.
701 Default is c.
703 bargravity nw | w | sw | n | c | s | ne | e | se
705 Select the location where message and prompt bars appear.
706 Default is ne.
708 font font
710 Make ratpoison use font font.
711 padding left top right bottom
713 Set how much space at the borders of the screen will not be used.
714 Default is 0 0 0 0.
716 border pixels
718 Selects how thick the frame around windows is.
719 Default is 1.
721 barborder pixels
723 Selects how thick the frame around ratpoison's prompt or message
724 windows is.
725 Default is 1.
727 inputwidth pixels
729 Determine the width of the input window.
730 Default is 200.
732 barinpadding 0 | 1
734 If there is padding, determines whether the bar appears at the
735 edge of the screen (1) or at the edge of the window area (0).
736 Default is 0.
738 topkmap kmap
740 Make kmap the top keymap ratpoison grabs directly.
741 The default value is top.
743 waitcursor 0 | 1
745 Determine whether to change the rat cursor when waiting for a key
746 (1) or not (0) See readkey and describekey.
747 Default is 1.
749 winfmt format
751 Choose the default format for the the windows command.
752 Default is %n%s%t.
754 winname title | name | class
756 Choose what is considered the "name" of the window by ratpoison:
757 title The title of the window.
759 name The resource name of the window.
760 class The resource class i.e. the name of the application.
761 Default is title.
763 fgcolor color
765 The foreground color of the windows ratpoison creates.
766 Default is black.
768 bgcolor color
770 The background color of the windows ratpoison creates.
771 Default is white.
773 fwcolor color
775 The border color of the focused window.
776 Default is black.
778 bwcolor color
780 The border color of unfocused windows.
781 Default is black.
783 barpadding x y
785 Set horizontal padding of ratpoison windows to x and vertical
786 padding to y.
787 Default is 4 0.
789 winliststyle row | column
791 Determines whether windows are shown in rows or in columns.
792 Default is column.
794 framesels selectors
796 Override the frame selectors fselect uses. The first character
797 is the selector for the first frame, the second character is the
798 selector for the second frame and so on.
799 Using this variable, one can directly access more than 10 frames.
801 Default is an empty string, which is equivalent to "0123456789".
803 historysize number
805 Specify maximum number of values kept in input history.
806 Default is 20.
808 historycompaction 0 | 1
810 Decide if new input lines added to history delete older equal
811 lines from history.
812 Default is 1 (on).
814 historyexpansion 0 | 1
816 Decide if history expansion using ! is available. (Can only be
817 activated when compiled with readline's libhistory.)
818 msgwait seconds
820 The duration the message window is shown. If seconds is zero,
821 wait infinitely.
822 framemsgwait seconds
824 The duration the ‘Current frame’ indicator is shown. If seconds
825 is zero, wait until the next interactive command. If seconds is
826 -1, don't show any message.
827 startupmessage 0 | 1
829 Decide whether to show a greeting message at startup.
830 warp 0 | 1
832 Decide if focusing a window moves the rat cursor to the place it
833 had been last time this window was focused, or not.
834 Default is 0 (off).
836 rudeness number
838 Show or set what kind of windows are allowed to jostle into the
839 foreground.
840 number is a bitwise OR of the following values:
842 1 Transient windows may raise.
844 2 Normal windows may raise.
845 4 New transient windows end up in the foreground.
846 8 New normal windows end up in the foreground.
847 Default is all allowed i.e. 15.
849
851 ~/.ratpoisonrc Configuration file read at startup time, if present.
852 /etc/ratpoisonrc Fallback configuration file, if ~/.ratpoisonrc is not
853 found.
854
856 The ratpoison utility exits 0 on success, and >0 if an error occurs.
857
859 Upstream author is Shawn Betts <sabetts@gmail.com>.
860 See the /usr/share/doc/ratpoison/AUTHORS file for other contributors.
862 This manual page was written by Bernhard R. Link <brlink@debian.org>.
864 The conversion to the mdoc(7) language (http://mdocml.bsd.lv) was done by
865 Jeremie Courreges-Anglas <jca@wxcvbn.org>.
866
868 Please report any bug you find to the ratpoison mailing-list,
869 ⟨ratpoison-devel@nongnu.org⟩.
870BSD June 20, 2019 BSD