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 flashy wank. 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.

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? Its modern computing at its best boys and girls.

Splitting The Screen
********************

Sometimes you may want to see two or more windows at the same time. ratpoison allows you to split the screen into frames. 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.

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 :

C-t C-:
     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 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 v

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

C-t w

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

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

C-t 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 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 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
     Indicate which frame is the current frame.

ratpoison 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.

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 exec ratpoison --restart

     If no command is specified then bind works exactly like unbind, unbinding the key.

clock
     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.

colon COMMAND
     Run a ratpoison command.

curframe
     Indicate which frame is the current frame.

defbarloc N
     Set the message bar location. N is a value between 0 and 3. 0 is the top left and the values move clockwise around the screen to the bottom left which is 3.

msgwait N
     Set the bar's timeout in seconds.

defborder N
     Set the border width for all windows.

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

definputwidth N
     Set the width of the input window.

defmaxsizepos X Y
     Set the default alignment for windows with maxsize hints. See the pos command.

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

deftranspos X Y
     Set the default alignment for transient windows. See the pos command.

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.

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

     -
          Window status (current window, last window, etc)

     W
          Window Name

     w
          Window res name

     c
          Window res class

     n
          X11 Window ID

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.

defwinpos X Y
     Set the default alignment for normal windows. See the pos command.

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

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

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

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

focus
     cycle through ratpoison's frames.

meta
     Send a C-t to the current window.

help
     Display a help screen that lists all bound keystrokes.

echo TEXT
     Display TEXT as a message.

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

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.

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

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.

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

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

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.

pos X Y
     Change the alignment of the current window. A normal window will default to aligning itself to the top-left corner of the screen, but it can also be aligned to, say, the bottom-right. Valid values for X are left, center, and right. Valid values for Y are top, center, bottom. X and Y can be abbreviated to the first letter.

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

quit
     Quit ratpoison.

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

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

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 '.

source FILE
     Read a text file containing ratpoison commands.

split

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

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.

unbind KEY
     Unbind a keystroke.

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

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

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.

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

-r, --restart
     Restart ratpoison

-k, --kill
     Kill ratpoison

-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 command that behaves differently is the windows command. 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.

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 lets 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.