This is the ratpoison user manual.

Copyright © 2000, 2001 Shawn Betts

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled ``Copying'' and ``GNU General Public License'' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

This document explains how to use ratpoison.

About
*****

ratpoison is a simple Window Manager with no fat library dependencies, no fancy graphics, no window decorations, and no rodent dependence. It is largely modeled after GNU Screen which has done wonders in the virtual terminal market.

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.

ratpoison was written by Shawn Betts (sabetts@users.sourceforge.net).

Contacting
**********

ratpoison is hosted on sourceforge.net. To see the latest developments in ratpoison go to http://www.sourceforge.net/projects/ratpoison or visit the ratpoison webpage at http://ratpoison.sourceforge.net.

There is also a ratpoison mailing list: ratpoison-devel@lists.sourceforge.net. For details on subscribing and for the list archives go to the ratpoison sourceforge.net project.

There is a #ratpoison irc channel on irc.openprojects.net.

Concepts
********

ratpoison uses the concept of panes to place and size windows. Instead of allowing windows to have arbitary shapes at arbitary locations on the screen, the display is divided into panes, the same way a physical window might contain several pieces of glass seperated by wood. In ratpoison, the panes are called frames, and windows are placed in them, maximised. ratpoison starts with one frame, which can be split into an arbitary number of smaller ones. Each frame can be split in half either horizontally or vertically. You can move among them, making different ones the current. For more information, see Splitting Frames.

Each frame has at most one window associated with it, which is visible in that frame. If you select a window that is associated with a frame, the focus will move to its associated frame, rather than moving the window to the current frame. If you select a window that is not associated with a frame, that window will be opened in the current frame and resized to fit that frame.

If the window associated with a frame does not fill the frame completely, the various gravity commands control how it is placed.

If no window was open in that frame before the current window was opened, the X root will be visible behind it.

Transient windows (dialog boxes, splash screens, and the like) are handled specially. In order to understand the contents of a transient window, the previously focused window is often required. Take a search window, it is useful to be able to see the document you are searching as well as the search window. For this reason transient windows appear overtop (according to their gravity) of the previously focused window.

General Use
***********

When ratpoison starts you should see an empty X server. To open an x terminal hit C-t c. You can now run shell commands as you would on any terminal. Notice the terminal maximized full screen. C-t ! will run a single shell command and saves you the effort of opening a terminal.

Once you have a couple X programs running, you'll want to navigate between windows. To see what windows are being managed hit C-t w. Each window has a number. You can jump to a window by hitting C-t followed by the window's number. This assumes the the window's number is one digit. You can also switch to a window by typing in part of its name. To do this hit C-t '.

ratpoison allows you to cycle through the windows with C-t n and C-t p.

And That concludes a brief introduction on how to use ratpoison. Notice how we didn't have to drag a single window, or click a single maximize button? Beautiful wasn't it? Felt fast? Cool? It's modern computing at its best.

Splitting Frames
****************

Sometimes you may want to see two or more windows at the same time. ratpoison allows you to split the display into frames (see Concepts). Each frame can then contain 1 window. To split the current frame horizontally use C-t s. To split the current frame vertically use C-t S. If you have enough windows, you'll notice that the new frame will find a window for itself. You can now use the normal navigation commands to switch windows in the frame. Note, however, that if you switch by name or number to a window that is already in another frame, you'll switch to that frame.

Before too long, you'll probably want to switch to another frame. Use C-t tab to cycle through the frames. If you want to remove a frame use C-t R. ratpoison automatically adjusts the size of the other frames to take up the free space. Unfortunately ratpoison may not always fill it in the way you might like it to.

Finally, when you've had enough of the splitting and you just want good ol' full screen ratpoison press C-t Q to remove all splits and leave you with the current window full screen.

Multiple Monitors
*****************

When you've finally accumulated enough computer junk, you'll find youself attaching a second monitor to your computer. ratpoison has functionality to help you get around your new and improved desktop space.

The X Windowing System assigns each monitor a screen number. To switch to another screen use the commands nextscreen and prevscreen. ratpoison will tell you which frame has focus by drawing the current frame indicator in it.

Many commands operate only on the current screen. This becomes apparent when you have 2 screens each with 1 frame. In each frame you have an xterm. If you try to switch to the other xterm with the command other, for instance, you'll get a message ``No other window.'' ratpoison means there's no other window to switch to in the current screen. If you want to switch to the other xterm you can switch to it by name (use select or C-t '), by number, or you can use nextscreen and prevscreen.

Keystrokes
**********

ratpoison is a very simple window manager. Each window is maximized and has no border decorations. 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.

C-t C-t
     Switch to the last window.

C-t t
     Sometimes you need to send a C-t to the current window. This keystroke does just that.

C-t 0-9
     Switch to the numbered window.

C-t -
     Select no window, essentially hiding all windows in the current frame.

C-t A

C-t C-A
     Rename the current window. The window's new name will prevail for the rest of its lifetime.

C-t K

C-t C-K
     Send a DestroyClient event to the current window. This will terminate the application without question.

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.

C-t p

C-t C-p
     Go to previous window.

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.

C-t a

C-t C-a
     Display the current time of day.

C-t c

C-t C-c
     Open a new X terminal.

C-t :
     This allows you to execute a single ratpoison command.

C-t !
     Run a shell command.

C-t C-!
     Run a shell command through an X terminal.

C-t i

C-t C-i
     Display information about the current window.

C-t k

C-t C-k
     Close the current window.

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.

C-t m

C-t C-m
     Display the last message.

C-t v

C-t C-v
     Display the version of ratpoison.

C-t V

C-t C-V
     Display ratpoison's license.

C-t w

C-t C-w
     Display the list of managed windows. The current window is highlighted.

C-t s

C-t C-s
     Split the current window horizontally in two. The last accessed window not occupying a frame will be the second window.

C-t S

C-t C-S
     Split the current window vertically in two. The last accessed window not occupying a frame will be the second window.

C-t tab
     Cycle through ratpoison's frames.

C-t M-tab
     Switch to the last focused frame.

C-t Q
     Kill all frames but the current one.

C-t R
     Kill the current frame. This is a no-op if there is only one frame.

C-t r

C-t C-r
     Resize the current frame.

C-t b

C-t C-b
     Banish the mouse to the lower right corner of the screen.

C-t ?
     Display a help screen.

C-t f

C-t C-f
     select a frame by number.

C-t F
     Indicate which frame is the current frame.

Commands
********

ratpoison can be controlled with commands (so called colon-commands). The summary of available commands is listed below:

abort
     This is a pretty useless command. By default, it is bound to C-t g, and its purpose is to abort other commands.

alias NAME COMMAND
     An 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.

banish
     Banish the mouse to the lower right corner of the screen.

bind KEY COMMAND
     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.

chdir
     Change the current directory for ratpoison.

colon COMMAND
     Run a ratpoison command.

curframe
     Indicate which frame is the current frame.

defbarborder N
     Set the border width for the bar window.

defbargravity G
     Set the default alignment for the message bar. See the gravity command.

     When called non-interactively with no arguments, the current setting is returned.

defbarpadding X Y
     Set the horizontal and vertical padding inside the bar.

     When called non-interactively with no arguments, the current setting is returned.

defbgcolor COLOR
     Set the background color for all text ratpoison displays. COLOR is any valid X11 color.

defborder N
     Set the border width for all windows.

     When called non-interactively with no arguments, the current setting is returned.

deffgcolor COLOR
     Set the foreground color for all text ratpoison displays. COLOR is any valid X11 color.

deffont FONT
     Set the font. FONT is a font string like 9x15bold.

definputwidth N
     Set the width of the input window.

     When called non-interactively with no arguments, the current setting is returned.

defmaxsizegravity G
     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.

defpadding LEFT TOP RIGHT BOTTOM
     Set the padding around the edge of the screen.

     When called non-interactively with no arguments, the current setting is returned.

defresizeunit PIXELS
     Set the number of pixels a frame will grow or shrink by when being dynamically resized.

deftransgravity G
     Set the default alignment for transient windows. See the gravity command.

     When called non-interactively with no arguments, the current setting is returned.

defwaitcursor N
     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.

defwinfmt FMT
     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.

defwingravity G
     Set the default gravity for normal windows. See the gravity command.

     When called non-interactively with no arguments, the current setting is returned.

defwinname NAME
     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. NAME 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.

delete
     This deletes the current window. You can access it with the C-t k keystroke.

echo TEXT
     Display TEXT as a message.

escape KEY
     Set the prefix to to KEY. For example escape C-b sets the prefix key to C-b.

exec COMMAND
     Execute a shell command. By default, C-t ! does this.

focus
     cycle through ratpoison's frames.

focusdown
     Move to the frame below the current frame.

focuslast
     Switch to the last focused frame.

focusleft
     Move to the frame left of the current frame.

focusright
     Move to the frame right of the current frame.

focusup
     Move to the frame above the current frame.

fselect N
     Select a frame by number. If an argument is passed to it then attempt to select the frame whose number is N. If not, ratpoison will print a number at the top left corner of each frame and wait for the user to type the number they wish to select. Currently there is no way to select a frame whose number is greater than 9 unless the number is passed as an argument.

getenv ENV
     Display the value of the environment variable, ENV.

gravity G
     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 G 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. G and can be abbreviated to the standard compass 1 and 2 letter abbreviations (i.e. nw, s, etc).

     When called non-interactively with no arguments, the current setting is returned.

help
     Display a help screen that lists all bound keystrokes.

info
     Display information about the current window.

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.

lastmsg
     Display the last message.

license
     Display ratpoison's license. By default, this is bound to C-t V.

link KEY
     Call the command that KEY is bound to. For instance link C-t would call the command other and switch to the last window.

meta
     Send a C-t to the current window.

msgwait N
     Set the bar's timeout in seconds.

     When called non-interactively with no arguments, the current setting is returned.

newwm WINDOW-MANAGER
     This is a bad-bad command. It kills ratpoison and revives that ugly rodent! Yuck! Avoid!

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.

nextscreen
     This jumps you to the next X11 screen. nextscreen is used for dual-head displays and multiple monitor setups.

number N TARGET
     Set a window's number to N. If another window occupies the requested number already, then the windows' numbers are swapped.

     The second argument, TARGET, is optional. It should be the number of the window whose number will be changed. If TARGET is omitted ratpoison defaults to the current window.

only
     Kill all frames but the current one.

other
     This toggles between the current window and the last window. By default, this is bound to C-t C-t.

prev
     This jumps you to the previous window in the window list. By default, this is bound to C-t p.

prevscreen
     This jumps you to the previous X11 screen. prevscreen is used for dual-head displays and multiple monitor setups.

quit
     Quit ratpoison.

redisplay
     Redisplay the current window, just like C-t l would do.

remove
     Kill the current frame. This is a no-op if there is only one frame.

resize HORIZONTAL VERTICAL
     Resize the current frame by HORIZONTAL pixels horizontally, and VERTICAL pixels vertically. If no arguments are given and the command is called interactively, ratpoison will let the user dynamically resize the frame using C-p to shrink vertically, C-n to grow vertically, C-b to shrink horizontally, C-f to grow horizontally, and s to shrink the frame to the size of the window (See the shrink command). When you have resized the frame to your liking, press Return to finish.

restart
     Restart ratpoison.

rudeness N
     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.

     N 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).

     When called non-interactively with no arguments, the current setting is returned.

select N
     This jumps you to window N where N 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 -.

select WINDOW-NAME
     Go to a window by name. A shortcut is C-t '.

setenv ENV VALUE
     Set the environment variable ENV to VALUE

shrink
     If a window has resize increment hints, such as xterms, the window may not be able to take up the whole frame. In this case, use this command to suck the frame up to the to window, reclaiming any wasted space.

source FILE
     Read a text file containing ratpoison commands.

split N

hsplit N
     Split the current frame horizontally in two. The last accessed window not occupying a frame will be the second window.

     N is either a fraction of the form x/y or a number. If it is a fraction then the current frame is resized to that fraction of its original size and the new frame takes up the remaining space. For instance, split 1/4 will split the current frame to a quarter of its original size and the new frame will then be 3/4 of the size of the original frame.

     If it is a pixel, the original frame is resized to that many pixels. If N has a minus sign before it, then the new frame will shrink by that many pixels.

startup_message STATE
     Turn on or off the startup_message. This is most useful in your .ratpoisonrc file. STATE can be on or off.

     When called non-interactively with no arguments, the current setting is returned.

tmpwm WM
     Gives control over to another window manager and regains control once it has terminated. WM is the path to the new window manager. This command is useful when you want to temporarily take a look at another window manager, or program under a different window manager, but you want to come back to ratpoison when you've finished your investigation.

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.

title TITLE
     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.

unalias NAME
     Remove NAME from the list of defined aliases.

unbind KEY
     Unbind a keystroke.

unsetenv ENV
     Clear the value of the environment variable, ENV.

version
     Print ratpoison version.  By default, this is bound to C-t v.

vsplit N
     Split the current frame vertically in two. The last accessed window not occupying a frame will be the second window.

     N is either a fraction of the form x/y or a number. If it is a fraction then the current frame is resized to that fraction of its original size and the new frame takes up the remaining space. For instance, split 1/4 will split the current frame to a quarter of its original size and the new frame will then be 3/4 of the size of the original frame.

     If it is a pixel, the original frame is resized to that many pixels. If N has a minus sign before it, then the new frame will shrink by that many pixels.

warp STATE
     Toggle rat warping. By default ratpoison saves the position of the rat when leaving a window and when the user returns to the window the rat's position is restored. This can be counter-intuitive, so you can toggle it with this command. STATE can be on or off.

windows FMT
     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 FMT comes into play. If windows is given an arg it treats it as the format string as described in defwinfmt.

Input
*****

At various times ratpoison will prompt you for input. Currently only very basic text editing commands exist.

Backspace
     Deletes one letter preceding the cursor.

C-p
     Cycle backwards through the history.

C-n
     Cycle forwards through the history.

All input is stored in the same history list. By default ratpoison has a history length of 50 entries.

Command Line Arguments
**********************

ratpoison supports command line arguments to request various actions when invoking ratpoison.

-h, --help
     Display this help screen

-v, --version
     Display the version

-c, --command
     Send ratpoison a colon-command. This allows you to control ratpoison from the command-line. with the -c option you can script ratpoison using any programming language that can spawn a process. Some commands behave differently when invoked this way. Currently the only commands that behaves differently are the windows command and some def* commands. Instead of displaying the window list in a message window, it is printed to stdout. The output can then be captured and used in the ratpoison script. For instance, this could be used to check whether a program is running and if it is switch to its window otherwise launch it.

     It should also be noted that multiple -c options can be used.

          $ ratpoison -c split -c split

     Here ratpoison would split the current frame twice.

Startup file
************

Now you've probably read the web page, and you've no doubt dug up some old file I forgot about. You're probably wondering, ``say, didn't he say there was no configuration file to customize?''. Okay, ya got me. But let's be honest here: ratpoison is so pure and fast-acting, customization is barely worth the extra effort. In the off chance that you need to make ratpoison your own, we now support it.

On startup ratpoison looks for ~/.ratpoisonrc and runs it through the command parser. If ~/.ratpoisonrc does not exist, ratpoison tries /etc/ratpoisonrc. This means any command you can bind a key to or run at the command prompt (C-t :) you can execute in this rc file.