NAME
ratpoison - window manager without mouse dependency
SYNOPSIS
ratpoison --help | --version
ratpoison [-d dpy] [-s num] [-f file]
ratpoison [-d dpy] [-s num] [-i] -c command [-c command ... ]
DESCRIPTION
Ratpoison is a Window Manager without fat library dependencies, fancy
graphics or rat dependence.
The screen can be split into non-overlapping frames. All windows are
kept maximized inside their frames.
All interaction with the window manager is done through keystrokes.
ratpoison has a prefix map to minimize key clobbering.
OPTIONS
-h, --help
Show summary of options.
-v, --version
Show version of program.
-d, --display display
Set the X display to use or send commands to.
-s, --screen number
Only use the specified screen.
-f, --file filename
Specify an alternate configuration file. If this is not given,
ratpoison will try $HOME/.ratpoisonrc and if that does not exist
/etc/ratpoisonrc and execute each command when starting up.
-i, --interactive
Execute commands given with -c or --command in interactive mode.
That means it will behave exactly as if called with C-t : like
prompting for missing arguments and things like that.
-c, --command
Send ratpoison a command. There must be a ratpoison instance
running as window manager for the given display/screen for this
to work. Do not forget to quote the command if it contains
spaces. For example:
ratpoison -c "echo hallo world"
KEY BINDINGS
To avoid conflicts with other programs, all default ratpoison key
bindings start with an escape key, per default C-t (read Control-t).
Some important default key bindings:
C-t q Quit ratpoison
C-t ? Show key bindings
C-t c Start an X terminal
C-t n Switch to next window
C-t p Switch to previous window
C-t 1|2|3|4|5|6|7|8|9 Switch to window number 1|2|...
C-t k Close the current window
C-t K XKill the current application
C-t s|S Split the current frame into two vertical|horizontal ones
C-t Tab|Left|Up|Right|Down Switch to the next|left|top|right|bottom
frame.
C-t Q Make the current frame the only one
C-t : Execute a ratpoison command
Further default key bindings can be found in parentheses after the
commands in the next section:
COMMANDS AND DEFAULT ALIASES
abort (C-t C-g)
Do nothing and that successfully. (Useful if you pressed C-t in
error).
addhook event command
Add a hook: Run command command whenever event is called.
Possible events are:
deletewindowRun after a window is withdrawn.
key Run whenever a top level key is pressed. (by default
C-t)
quit Run before exiting ratpoison.
restart Run before restarting ratpoison.
switchframeRun after a frame actually switched, but before the
window in it is focused.
switchgroupRun after selecting a new group.
switchwin Run after a new window is selected. (With dedication,
it may already be inactive again, if it was put into another
frame)
alias alias command
Add alias as new way to call command.
bind key command
alias for "definekey root key command"
banish (C-t b)
Banish the rat cursor to the lower right corner of the screen.
banishrel
Banish the rat cursor to the lower right corner of the curren
window. If there isn’t a window in the current frame, it
banishes the rat cursor to the lower right corner of the frame.
chdir [directory]
If the optional argument is given, change the current directory
of ratpoison to directory. If nothing is given, change it to
the value of the environment variable "HOME".
clrunmanaged
Clears the unmanaged window list.
cnext
Like next but switch to the next window with another resource
class than the current one. (That means the next window
belonging to another type of application
than the current one.)
cprev
Like prev but switch to the previous window with another
resource class than the current one. (That means the previous
window belonging to another type of application
than the current one.)
colon ratpoison-command (C-t :)
Execute ratpoison-command interactively. (i.e. ask for possible
missing arguments.)
compat
Add aliases for the new set commands starting with def to
support older scripts.
cother
Like other but switch to the window of the current group that
was last accessed and has an other resource class but is not
currently visible.
curframe (C-t F)
Show a bar marking the current frame.
definekey keymap key command
Add a new key binding in keymap for key to execute command.
Default keymaps are top normally only containing C-t, which
reads a key from root, containing all the normal commands.
Note that you have to describe ":" by "colon", "!" by "exclam"
and so on. If you cannot guess a name of a key, try either C-t
key and look at the error message, or try :describekey root and
pressing the key.
def...
When compat was called there are some aliases starting with def,
which alias the new form with set. I.e. instead of
defresizeunit better use the new set resizeunit and so on...
dedicate [0|1]
Consider the current frame dedicated/chaste (1) or promiscuous
(0).
A dedicated frame will not accept new windows. When new windows
are to be focused, they will be opened in a non-dedicated frame
instead.
If no argument is given, toggle the current dedicateness. By
default no windows are dedicated.
delete (C-t k)
Close the current window.
delkmap keymap
Deletes the keymap named keymap, that was generated with
newkmap. The keymaps top (or whatever was specified by set
topkmap) and root cannot be deleted.
describekey keymap
Grab the next key. Similar to readkey, describekey shows only
the command in keymap, that would be executed by readkey.
echo text
Show text as ratpoison message.
escape key
Update the default escape key to key.
Strictly speaking it updates the the readkey root command in the
keymap top to key, the other binding in root to key, and meta
binding in root to key without modifiers or C-key if key has no
modifiers. (If set topkmap was called with an argument other
than top that will be used instead of top.)
exchangedown (C-t C-Down)
Exchange the window in the current frame with the window in the
frame below the current frame.
exchangeleft (C-t C-Left)
Exchange the window in the current frame with the window in the
frame left of the current frame.
exchangeright (C-t C-Right)
Exchange the window in the current frame with the window in the
frame right of the current frame.
exchangeup (C-t C-Up)
Exchange the window in the current frame with the window in the
frame above the current frame.
exec shell-command (C-t !)
Spawn a shell executing shell-command.
execa shell-command
Spawn a shell executing shell-command, without remembering the
current frame, so that _NET_WM_PID declaring programs will be
placed into the frame active when they open a window instead of
the frame active when ratpoison gets this command.
execf frame shell-command
Spawn a shell executing shell-command, showing _NET_WM_PID
supporting programs in the given frame instead of the frame
selected when this program is run.
fdump [screenno]
Output the defining data for all frames of the current screen,
or for screen number screenno if this is specified.
focus (C-t Tab)
Focus the next frame.
focuslast
Switch to the last selected focus.
focusleft (C-t Left)
Switch to the frame to the left of the current one.
focusdown (C-t Down)
Switch to the frame beneath the current one.
focusright (C-t Right)
Switch to the frame to the right of the current one.
focusprev
Focus the previous frame.
focusup (C-t Up)
Switch to the frame above the current one.
frestore frames
Replace the current frames with the ones specified in frames in
the format as generated by fdump.
fselect [frameno] (C-t f)
If an argument is supplied, switch to a frame given by number
frameno.
If no argument is given, show a frame selector in each frame and
wait for a key to be pressed. If the key matches an existing
frame selector, this frame gets focused.
Frame selectors are by default the numbers starting with zero,
but they can be changed by seting framesels.
gdelete [group]
If the optional argument group is supplied, delete group group.
Otherwise delete the current group. If the last group is
deleted, a new group with name default is created. The group
has to be empty, otherwise it cannot be deleted.
getenv variable
Output the value of the environment variable variable.
getsel
Paste the current X Selection into the current window.
gmerge group
Move all windows from group group into the current group.
gmove group
Move the current window into group group.
gnew group
Create a new group with name group and select it. Most window
commands only see (and thus select, consider next, previous or
last) windows within the group active when they are issued.
gnewbg group
Create a new group named groupf, but do not select it.
gnext
Select the next group. Most window commands only see windows in
the effective group.
gother
Select the last accessed group. Most window commands only see
windows in the effective group.
gprev
Select the prior group. Most window commands only see windows in
the effective group.
gravity [nw|w|sw|n|c|s|ne|e|se]
Change how in its frame the current window is aligned.
grename
Rename current group.
groups
Output a list of all groups with their number.
gselect group
Select the group names group.
help [keymap]
If the optional parameter keymap is given, list all keybindings
in this keymap, otherwise list all key bindings in keymap root.
hsplit [l/p|pixels from left|-pixels from right] (C-t S)
Split the current frame into left frame and a right frame. If
no parameter is given, split in halves. If two numbers
separated by a slash ("/") are given, the left one is l times
the pth part and the right one (p-l) times the pth part of the
prior width. Otherwise the right one is pixels from right wide
or the left one pixels from left wide, depending whether there
is - in front of the number or not.
inext
Like next but switch to the next window with the same resource
class as the current one. (That means the next window belonging
to the same application
as the current one.)
info (C-t i)
Output the current the width, height, window number and window
name of the current window. (What name means is chosen by
"set winname".)
iprev
Like prev but switch to the previous window with the same
resource class as the current one. (That means the previous
window belonging to the same application
as the current one.)
iother
Like other but switch to the window of the current group that
was last accessed and has the same resource class but is not
currently visible.
kill (C-t K)
Close the X-connection of the X-client responsible for the
current window.
lastmsg (C-t m)
Reshow the last message.
license (C-t V)
Show ratpoison’s license.
link key [keymap]
Do what key is bound to in the keymap keymap if supplied.
Otherwise what key is bound to in keymap root.
listhook event
List all commands specified with addhook to be executed when
even event occurs.
meta [key] (C-t t)
Send the escape key (that which normally is C-t) to the current
window. If a key is specified, this is sent instead. Note that
some applications by default ignore the synthetic key that is
sent using this command as it is considered a security hole.
xterm is one such application.
msgwait [seconds]
Set the duration the message window is shown. If seconds is
zero, wait infinitely.
newkmap keymap
Generate a new keymap names keymap. This keymap can be used to
add new key-command mapping to it with definekey and can be
called with readkey.
newwm new window manager
Quit ratpoison and execute new window manager instead.
next (C-t Return|C-t n|C-t space)
Switch to the next window in the current group.
nextscreen
Switch to the next screen. (If you have multiple physical ones.)
number new [old]
Give the number new to the window with the number old or the
current window.
only (C-t Q)
Remove all frames on the current screen except the current frame
and maximise this one to the size of the whole screen.
other (C-t C-t)
Switch to the window of the current group that was last accessed
but is not currently visible.
prev (C-t p)
Switch to the previous window in the current group.
prevscreen
Switch to the previous screen. (If you have multiple physical
ones.)
prompt [prompt]
Ratpoison will ask the user for input, showing prompt (or a
single colon, if no argument is given) and output the input the
user has made.
Note that this command probably does not make much sense in
interactive mode.
putsel x-selection
Replace the X selection with the text x-selection. It can be
inserted into the current window with getsel.
quit
Quit ratpoison.
ratinfo
Display the x y coordinates of the rat cursor relative to the
screen.
ratrelinfo
Display the x y coordinates of the rat cursor relative to the
current window or current frame if no window is focused
ratwarp x y
Move the rat cursor to the position (x,y).
ratrelwarp deltax deltay
Move the rat cursor to (deltax,deltay), relative to the current
position.
ratclick [button]
Simulate a rat click with button (button 1=left button if none
given).
rathold up|down [button]
Simulate pressing|releasing rat button button (1=left button if
none given).
readkey keymap
Grab the next key pressed, and execute the command associated to
this key in keymap. To show it is waiting for a key, ratpoison
will change the rat cursor to a square if waitcursor is set.
This command is perhaps best described with its usage in the
default configuration: By pressing C-t, which is the only key in
the keymap top, the command "readkey root" is executed. The next
key then executes the command in keymap root belonging to this
command.
redisplay (C-t l)
Extend the current window to the whole size of its current frame
and redisplay it. (Useful to redisplay normal windows or bring
transient windows to the full size of the frame as only normal
windows are maximized by ratpoison)
redo (C-t U)
Revert the last undo of frame changes.
remhook event command
Remove command command from the list of commands to be called
when event event is hit. (The command has to specified, as an
event can have multiple commands attached to it.) Use "listhook
hook" to get a list of all attached commands.
remove (C-t R)
Remove the current frame and extend some frames around to fill
the remaining gap.
removedown (C-t M-Down)
Kill frames directly below the current frame, extending the
current frame as much as possible.
removeleft (C-t M-Left)
Kill frames directly left of the current frame, extending the
current frame as much as possible.
removeup (C-t M-Up)
Kill frames directly above the current frame, extending the
current frame as much as possible.
removeright (C-t M-Right)
Kill frames directly right of the current frame, extending the
current frame as much as possible.
resize [deltax deltay] (C-t r)
If deltax and deltay are supplied, resize the current frame by
that (i.e. move the bottom right corner by the given offsets and
then move this frame and resize adjacent frames to make the
frames fill the whole screen again.)
If in interactive mode no arguments are supplied, resize the
current frame interactively:
Return: finish resizing
C-g or Escape: abort resizing
C-n or Down or j: grow vertically
C-p or Up or k: shrink vertically
C-f or Right or l: grow horizontally
C-b or Up or h: shrink horizontally
s: shrink to size of current window
While resizing interactively, changes are in multiples of the
amount of pixels given by set resizeunit (by default 10).
restart
Restart ratpoison.
rudeness [rudeness]
Show or set what kind of windows are allowed to jostle into the
foreground.
rudeness is a bitwise or of the following values:
1 Transient windows may raise.
2 Normal windows may raise.
4 New transient windows end up in the foreground.
8 New normal windows end up in the foreground.
Default is all allowed i.e. 15.
sdump
Output the list of all screens. The screens are separated by
commas. Each screen is shown as 6 values: its number, its
x-coordinate, its y-coordinate, its width, its height and if it
is currently selected (1=true,0=false).
select -|name|nr (C-t ’)
If a number is given, switch to the window with number nr. If a
name is given, switch to the window in the current group with
name name. Blank the current frame, if - is given.
set [variable [value]]
If no argument is given, output all ratpoison variables and
their values.
If one argument is given, output the value of ratpoison variable
variable.
Otherwise set ratpoison variable variable to value. What values
are valid depends on the variable. See the section VARIABLES
later in this document for details.
setenv variable value
Set the environment variable variable to value. (Environment
variables will be passed to all programs started from
ratpoison.)
sfdump
Output all frames similar to fdump, but not limited to one
screen, but all screens at once and with the screen number after
each frame.
sfrestore
Replace the current frames with the ones specified in frames in
the format as generated by sfdump.
shrink
Shrink the current frame to the size of the current window with
in.
split [split] (C-t s)
alias for vsplit
source file
Read file and execute each line as ratpoison command.
sselect screennumber
Switch to the screen screennumber. (If you have multiple
physical ones.)
startup_message on|off
Select whether ratpoison will show a startup message or not.
swap [dest-frame [src-frame]] (C-t x)
Exchange the window in src-frame (or the current frame if there
is no second argument) with the window dest-frame (or ask
interactively which frame to swap with if there is no argument).
time (C-t a)
Output current data and time.
title newname (C-t A)
Overwrite the title of the current window with newname. All
following ratpoison commands will only know the window under the
new name.
tmpwm tmpwm
Temporarily give control over to the other window manager tmpwm,
reclaiming control when that WM terminates.
unalias alias
Remove the alias alias.
unbind key
alias for "undefinekey root key"
undefinekey keymap key
Remove the binding for key from keymap.
undo (C-t _ or C-t u)
Un-do the last change to the frameset. (Like splitting,
resizing, deleting, ...)
The amount of steps that can be undone is specified by the
variable maxundos.
unmanage [name]
Add name to the list of unmanaged windows. Thus, windows of
this name will not be managed but allowed to choose their
position themselves.
In non-interactive mode calling it without arguments will print
the list.
The list can be cleared again by calling clrunmanaged.
unsetenv variable
Remove variable variable from the list of environment variables.
verbexec cmdline
Spawn a shell executing cmdline after showing a message with the
command.
version (C-t v)
Output version and compile time information.
vsplit [l/p|pixels from top|-pixels from bottom] (C-t s)
Split the current frame into upper frame and a lower frame. If
no parameter is given, split in halves. If two numbers
separated by a slash ("/") are given, the upper one is l times
the pth part and the lower one (p-l) times the pth part of the
prior height. Otherwise the lower one is pixels from bottom
wide or the upper one pixels from top high, depending whether
there is a - in front of the number or not.
warp [on|off]
Select if focusing a window moves the rat cursor to the place it
had been last time this window was focused, or not.
windows [format] (C-t w)
In interactive mode, show the list of all windows in the current
group for the duration specified by msgwait If msgwait is zero,
toggle between indefinitely showing and not showing.
The messages are shown in columns or rows depending on the
setting of winliststyle in the format set by set winfmt. The
following substitutions happen in format:
%a by the application name (resource name),
%c by the resource class,
%f by the frame number,
%g by the gravity of the window,
%h by the height of the window,
%H by the unit to resize the window vertically (height_inc)
%i by the X Window ID,
%p by the process ID,
%l by the last access number,
%M by the string Maxsize, if it specifies a maximum size,
%n by the window number,
%s by window status (* is active window, + would be chosen by
other, - otherwise)
%S by the screen number
%t by the window name (see set winname),
%T by the string Transient, if it is a transient window
%w by the width of the window
%W by the unit to resize the window horizontally (width_inc)
%x by the xine screen number and
%% by a single %
Additionally there can be a positive decimal integer number
between the percent sign and the format string to specify the
length this value should be truncated to if longer. (For
example: %20t)
In non-interactive mode, output the list of windows in the
current group line by line. The format string can be overwritten
by the optional parameter format.
VARIABLES
Ratpoison variables can be shown and set with set. There are:
resizeunit pixels
Set the amount of pixels interactive resizeing will add/subtract
in each step.
Default is 5.
maxundos number
The maximal amount of step ratpoison can undo with the undo
command.
Default is 20.
wingravity nw|w|sw|n|c|s|ne|e|se
Set the default gravity new normal windows will get. Possible
values are the same as in the gravity command, which changes the
gravity of an existing window: cardinal points or numbers 1 to
9.
Default is northwest.
maxsizegravity nw|w|sw|n|c|s|ne|e|se
Set the default gravity new self-maximised windows will get.
Possible values are the same as in the gravity command, which
changes the gravity of an existing window: cardinal points or
numbers 1 to 9.
Default is center.
transgravity nw|w|sw|n|c|s|ne|e|se
Set the default gravity new transient windows will get.
Possible values are the same as in the gravity command, which
changes the gravity of an existing window: cardinal points or
numbers 1 to 9.
Default is center.
bargravity nw|w|sw|n|c|s|ne|e|se
Select the location where message and prompt bars appear.
Default is northeast.
font font
Make ratpoison use font font.
padding left top right bottom
Set how much space at the borders of the screen will not be
used.
Default is 0 0 0 0.
border pixels
Selects how thick the frame around windows is.
Default is 1.
barborder pixels
Selects how thick the frame around ratpoison’s prompt or message
windows is.
Default is 1.
inputwidth pixels
Determine the width of the input window.
Default is 200.
barinpadding 0|1
If there is padding, determines whether the bar appears at the
edge of the screen (1) or at the edge of the window area (0).
Default is 0.
topkmap kmap
Make kmap the top keymap ratpoison graps directly. The default
value is top.
waitcursor 0|1
Determine whether to change the rat cursor when waiting for a
key (1) or not (0). (see readkey and describekey).
Default is 1.
winfmt format
Choose the default format for the the windows command.
Default is %n%s%t.
winname title|name|class
Choose what is considered the "name" of the window by ratpoison:
title The title of the window.
name The resource name of the window.
class The resource class i.e. the name of the application.
Default is title.
fgcolor color
The foreground color of the windows ratpoison creates.
Default is black.
bgcolor color
The background color of the windows ratpoison creates.
Default is white.
fwcolor color
The border color of the focused window.
Default is black.
bwcolor color
The border color of unfocused windows.
Default is black.
barpadding x y
Set horizontal padding of ratpoison windows to x and vertical
padding to y.
Default is 4 0
winliststyle row|column
Determines whether windows are shown in rows or in columns.
Default is column.
framesels selectors
Override the frame selectors fselect uses. The first character
is the selector for the first frame, the second character is the
selector for the second frame and so on.
Using this variable, one can directly access more than 10
frames.
Default is an empty string, which is equivalent to "0123456789".
historysize number
Specify maximum number of values kept in input history.
Default is 20.
historycompaction 0|1
Decide if new input lines added to history delete older equal
lines from history.
Default is 1 (on).
historyexpansion 0|1
Decide if history expansion using ! is available. (Can only be
activated when compiled with readline’s libhistory.)
Default is 0 (off).
AUTHOR
Upstream Author is Shawn Betts <sabetts@vcn.bc.ca>.
See /usr/share/doc/ratpoison/AUTHORS for other contributors.
This manual page was written by Bernhard R. Link <brlink@debian.org>.
2008-06-15