From 366c3fac7c52becf29ff3be0b56b66d9efdecde5 Mon Sep 17 00:00:00 2001 From: sabetts Date: Sun, 18 Apr 2004 23:59:26 +0000 Subject: documentation refactoring --- doc/ratpoison.texi | 1532 +++++++++++++++++++++++++++++----------------------- 1 file changed, 843 insertions(+), 689 deletions(-) (limited to 'doc') diff --git a/doc/ratpoison.texi b/doc/ratpoison.texi index a54e4f2..856427d 100644 --- a/doc/ratpoison.texi +++ b/doc/ratpoison.texi @@ -79,28 +79,45 @@ This document explains how to use ratpoison. @end ifinfo @menu -* About:: What is ratpoison? -* Contacting:: How do I contact the ratpoison developers? -* Concepts:: Window manipulation concepts -* Groups:: Grouping windows together -* General Use:: How does this thing work?? -* Splitting Frames:: When you want to see more than one window -* Multiple Monitors:: What to do with all your computer junk -* Keystrokes:: Key commands and functionality -* Commands:: ratpoison commands -* Input:: Typing text into ratpoison -* Command Line Arguments:: ratpoison command-line actions -* Startup file:: They threatened me...with violence! +* About:: What Is Ratpoison? +* Contacting:: How Do I Contact The Ratpoison Developers? +* Concepts:: Window Manipulation Concepts +* General Use:: How Does This Thing Work?? +* Windows:: Navigating The Windows +* Groups:: Grouping Windows Together +* Frames:: Dividing The Screen +* Multiple Monitors:: What To Do With All Your Computer Junk +* Keystrokes:: Key Commands And Functionality +* Hooks:: Attaching Scripts To Ratpoison Events +* The Status Bar:: Ratpoison's Input/Output Area +* Using Other Window Managers:: Return To Evil +* Other Commands:: Miscellaneous Commands +* Input:: Typing Text Into Ratpoison +* Command Line Arguments:: ratpoison Command-Line Actions +* Startup file:: They Threatened Me...With Violence! * Command Index:: Index @detailmenu --- The Detailed Node Listing --- -Splitting Frames +Windows +* Manipulating Windows:: +* Unmanaged Windows:: +* Rudeness:: + +Frames + +* Splitting Frames:: * Resizing Frames:: +* Frame Navigation Commands:: * Saving and Restoring Frame Sets:: +Keystrokes + +* Key Maps:: +* Default Key Bindings:: + @end detailmenu @end menu @@ -131,7 +148,7 @@ and for the list archives go to the ratpoison sourceforge.net project. There is a #ratpoison irc channel on irc.openprojects.net. -@node Concepts, Groups, Contacting, Top +@node Concepts, General Use, Contacting, Top @chapter Concepts ratpoison uses the concept of @dfn{panes} to place and size @@ -172,26 +189,7 @@ creates a window it will be added to the current group. Groups are generally used to organize windows into different classes such as work and wasting-time-at-work. -@node Groups, General Use, Concepts, Top -@chapter Groups -ratpoison provides functionality to group windows together. This -coupled with saving and restoring frames configurations is what most -people would call @dfn{virtual desktops} or @dfn{workspaces}. - -While ratpoison doesn't explicity provide support for such things, it -does allow you to write scripts to this end. Such a script exists in -@file{contrib/} called @file{rpws}. Consult that file for details on -seting up workspaces inside ratpoison. - -Groups are more general purpose than workspaces. windows from one -group can be visible along with windows from another group. If you -switch to a different group nothing changes except the list of windows -you can cycle through. ratpoison allows the user to move a window from -one group to another, merge two groups, create new groups, and delete -existing ones. @xref{Commands}, for information on the commands for -manipulating groups. - -@node General Use, Splitting Frames, Groups, Top +@node General Use, Windows, Concepts, Top @chapter General Use When ratpoison starts you should see an empty X server. To open an x @@ -215,302 +213,600 @@ 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. -@node Splitting Frames, Multiple Monitors, General Use, Top -@chapter 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 -@ref{Concepts}). Each frame can then contain 1 window. To split the -current frame horizontally use @kbd{C-t s}. To split the current frame -vertically use @kbd{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 -@kbd{C-t tab} to cycle through the frames. If you want to remove a -frame use @kbd{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. +@node Windows, Groups, General Use, Top +@chapter Windows -Finally, when you've had enough of the splitting and you just want -good ol' full screen ratpoison press @kbd{C-t Q} to remove all splits -and leave you with the current window full screen. +Windows are what ratpoison manages. @menu -* Resizing Frames:: -* Saving and Restoring Frame Sets:: +* Manipulating Windows:: +* Unmanaged Windows:: +* Rudeness:: @end menu -@node Resizing Frames, Saving and Restoring Frame Sets, Splitting Frames, Splitting Frames -@section Resizing Frames -ratpoison provides a command, @command{resize}, that resizes the -current frame. It is bound to the key @kbd{C-t r} by -default. @command{resize} can be used non-interactively by providing -two arguments: the number of pixels to grow horizontally and the -number to grow vertically. For example, if you wanted to grow the -current window by 10 pixels horizontally and shrink it vertically by -50 you could enter the command: - -@example -resize 10 -50 -@end example - -When resizing interactively, the following keys are used: - -@table @kbd -@item C-p -Grow the frame vertically. -@item C-n -Shrink the frame vertically. -@item C-f -Grow the frame horizontally. -@item C-b -Shrink the frame horizontally. -@item return -Accept the new frame size. -@item C-g -Abort and restore the frame to its original size. -@end table +@node Manipulating Windows, Unmanaged Windows, Windows, Windows +@section Manipulating Windows -The increment size used to resize the frame interactively is -customized with the command @command{defresizeunit}. +The following are commands used to manipulate windows. -@node Saving and Restoring Frame Sets, , Resizing Frames, Splitting Frames -@section Saving and Restoring Frame Sets -ratpoison provides two commands, @command{fdump} and -@command{frestore}, that allow the user to save and restore frame -configurations. Let's say, for example, you have split your desktop -into several frames with some windows in these frames and now you want -to quickly bring Emacs forward and browse some code (full-screen of -course) then return to your funky frame configuration. You could use -@command{fdump} to dump the frames, hit @kbd{C-t Q} to remove all -frames, and then select your emacs window. When you've finished with -emacs you could use @command{frestore} to restore the windows and -frames. +@deffn Command select @var{n} +This jumps you to window @var{n} where @var{n} is the window number as +shown in the Program Bar. You can do the same trick with +@command{C-@var{n}} too. To select no window, blanking the current +frame, type @samp{select -}. +@end deffn -If a frame contained a window when you dumped the frame layout but -that window is not present when you restore the layout, the frame -holding that window will be blank. +@deffn Command select @var{window-name} +Go to a window by name. A shortcut is @kbd{C-t '}. +@end deffn -Calling @command{fdump} and @command{frestore} and copying and pasting -the layout by hand each time is a bit cumbersome. There are some -simple bindings in @file{doc/sample.ratpoisonrc} that allow you to -save and restore frame layouts with the press of a key. +@deffn Command windows @var{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 @kbd{C-t @var{n}} where @var{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 @kbd{C-t '} and type the number at the +prompt. -@node Multiple Monitors, Keystrokes, Splitting Frames, Top -@chapter 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. +After 5 seconds the Program Bar disappears. -The X Windowing System assigns each monitor a screen number. To switch -to another screen use the commands @command{nextscreen} and -@command{prevscreen}. ratpoison will tell you which frame has focus by -drawing the current frame indicator in it. +This command is bound to @kbd{C-t w} by default. -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 @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 @command{select} or @kbd{C-t '}), by number, -or you can use @command{nextscreen} and @command{prevscreen}. +When invoked from the command-line like this, -@node Keystrokes, Commands, Multiple Monitors, Top -@chapter Keystrokes +@example +$ ratpoison -c windows +@end example -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. +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 @var{fmt} comes into play. If +@command{windows} is given an arg it treats it as the format string as +described in @command{defwinfmt}. +@end deffn -@table @kbd +@deffn Command title @var{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 @kbd{C-t A} keystroke is bound to this command. +@end deffn -@item C-t C-t -Switch to the last window. +@deffn Command other +This toggles between the current window and the last window. By +default, this is bound to @kbd{C-t C-t}. +@end deffn -@item C-t t -Sometimes you need to send a C-t to the current window. This keystroke -does just that. +@deffn Command prev +This jumps you to the previous window in the window list. By default, +this is bound to @kbd{C-t p}. +@end deffn -@item C-t 0-9 -Switch to the numbered window. +@deffn Command next +This jumps you to the next window in the window list. This one is +bound to three keystrokes, namely @kbd{C-t n}, @kbd{C-t space}, +and @kbd{C-t enter}. +@end deffn -@item C-t - -Select no window, essentially hiding all windows in the current frame. +@deffn Command kill +This destroys the current window. Normally you should only need to +use @command{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 +@kbd{C-t K}. +@end deffn -@item C-t A -@item C-t C-A -Rename the current window. The window's new name will prevail for the -rest of its lifetime. -@item C-t K -@item C-t C-K -Send a DestroyClient event to the current window. This will terminate -the application without question. +@deffn Command info +Display information about the current window. +@end deffn -@item C-t n -@item C-t C-n -@item C-t Return -@item C-t C-Return -@item C-t Space -@item C-t C-Space -Go to next window. +@deffn Command gravity @var{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 @var{g} are the 8 +directions @samp{northwest}, @samp{north}, @samp{northeast}, +@samp{east}, @samp{southeast}, @samp{south}, @samp{southwest} and +@samp{west}, clockwise from the top left corner. @samp{center} will +center the window in the frame. @var{g} and can be abbreviated to the +standard compass 1 and 2 letter abbreviations (i.e. @samp{nw}, +@samp{s}, etc). -@item C-t p -@item C-t C-p -Go to previous window. +When called non-interactively with no arguments, the current setting is +returned. +@end deffn -@item C-t ' -@item C-t C-' -Go to a window by name. You will usually only need to type the first -few characters of the window name. +@deffn Command delete +This deletes the current window. You can access it with the @kbd{C-t k} +keystroke. +@end deffn -@item C-t a -@item C-t C-a -Display the current time of day. +@deffn Command defwinname @var{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. @var{name} can be @samp{title} which is what most +window managers put in the title bar, @samp{name} which is the +res_name, or @samp{class} which is the res_class. -@item C-t c -@item C-t C-c -Open a new X terminal. +When called non-interactively with no arguments, the current setting is +returned. +@end deffn -@item C-t : -This allows you to execute a single ratpoison command. +@deffn Command defwingravity @var{g} +Set the default gravity for normal windows. See the +@command{gravity} command. -@item C-t ! -Run a shell command. +When called non-interactively with no arguments, the current setting is +returned. +@end deffn -@item C-t C-! -Run a shell command through an X terminal. +@deffn Command defwinliststyle @var{setting} +The window list can be displayed in a row or a column. @var{setting} +can be @samp{row} or @samp{column}. +@end deffn -@item C-t i -@item C-t C-i -Display information about the current window. +@deffn Command defwinfmt @var{fmt} +Set the default window format for the @command{windows} command. By +default it is @samp{%n%s%t}. The following is a list of valid format +characters: -@item C-t k -@item C-t C-k -Close the current window. +@table @samp +@item %n +The window number +@item %s +Window status (current window, last window, etc) +@item %t +Window Name +@item %a +Application Name +@item %c +Resource Class +@item %i +X11 Window ID +@item %l +A unique number based on when the window was last accessed. The higher +the number, the more recently it was accessed. +@end table -@item C-t l -@item 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. @kbd{C-t l} will force the -current window to maximize. +When called non-interactively with no arguments, the current setting is +returned. +@end deffn -@item C-t m -@item C-t C-m -Display the last message. +@deffn Command number @var{n} @var{target} +Set a window's number to @var{n}. If another window occupies the +requested number already, then the windows' numbers are swapped. -@item C-t v -@item C-t C-v -Display the version of ratpoison. +The second argument, @var{target}, is optional. It should be the +number of the window whose number will be changed. If @var{target} is +omitted ratpoison defaults to the current window. +@end deffn -@item C-t V -@item C-t C-V -Display ratpoison's license. +@deffn Command deftransgravity @var{g} +Set the default alignment for transient windows. See the +@command{gravity} command. -@item C-t w -@item C-t C-w -Display the list of managed windows. The current window is highlighted. +When called non-interactively with no arguments, the current setting is +returned. +@end deffn -@item C-t s -@item C-t C-s -Split the current window horizontally in two. The last accessed window +@deffn Command defmaxsizegravity @var{g} +Set the default alignment for windows with maxsize hints. See the +@command{gravity} command. + +When called non-interactively with no arguments, the current setting is +returned. +@end deffn + +@deffn Command defborder @var{n} +Set the border width for all windows. + +When called non-interactively with no arguments, the current setting is +returned. +@end deffn + +@node Unmanaged Windows, Rudeness, Manipulating Windows, Windows +@section Unmanaged Windows + +ratpoison can intentionally not manage windows. ratpoison keeps a list +of strings and if any new window's name matches a string in the list, +then it will not be picked up and managed by ratpoison. + +The following are commands to manipulate this list + + +@deffn Command clrunmanaged +Clear the unmanaged window list. +@end deffn + +@deffn Command unmanage @var{text} +Add @var{text} to the unmanaged window list. Any window whose name +matches any of the strings in the unmanaged window list will not be +handled in any way by ratpoison. This only applies to new windows (not +windows already managed by ratpoison). + +When called non-interactively with no arguments, the list is returned. +@end deffn + +@node Rudeness, , Unmanaged Windows, Windows +@section Rudeness + +Some programs will attempt to steal the focus without the users +permission. Not only is this a sign of a lame programmers attempt to fix +a window manager problem in the wrong place, it's just plain rude. By +default ratpoison will honour these rudeness requests, but it doesn't +have to. Use the @command{rudeness} command to deal with such programs. + +@deffn Command rudeness @var{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. + +@var{n} is a number from 0 to 15. Each of the four bits determine +which requests ratpoison grants. + +@table @asis +@item Bit 0 +Tells ratpoison to grant raise requests on transient windows + +@item Bit 1 +Tells ratpoison to grant raise requests on normal windows + +@item Bit 2 +Tells ratpoison to grant display requests on new transient windows + +@item Bit 3 +Tells ratpoison to grant display requests on new normal windows +@end table + +For example, if you wanted only wanted to grant transient windows +raise requests and display requests you would type @samp{rudeness +5}. If a request is not granted ratpoison will tell you about the +request with a message like @samp{Raise request from window 1 +(emacs)}. + +When called non-interactively with no arguments, the current setting is +returned. +@end deffn + +@node Groups, Frames, Windows, Top +@chapter Groups +ratpoison provides functionality to group windows together. This +coupled with saving and restoring frames configurations is what most +people would call @dfn{virtual desktops} or @dfn{workspaces}. + +While ratpoison doesn't explicity provide support for such things, it +does allow you to write scripts to this end. Such a script exists in +@file{contrib/} called @file{rpws}. Consult that file for details on +seting up workspaces inside ratpoison. + +Groups are more general purpose than workspaces. windows from one +group can be visible along with windows from another group. If you +switch to a different group nothing changes except the list of windows +you can cycle through. ratpoison allows the user to move a window from +one group to another, merge two groups, create new groups, and delete +existing ones. + +The following is a list of of commands used for manipulating groups. + +@deffn Command gnew @var{name} +Create a new group with the name @var{name}. @var{name} is +optional. This new group becomes the new group. +@end deffn + +@deffn Command gnewbg @var{name} +This is the same as @command{gnew} except that the current group does +not change. +@end deffn + +@deffn Command groups +Display a list of groups with a similar format to @command{windows}. +@end deffn + +@deffn Command gmove @var{group} +Move the current window to @var{group}. +@end deffn + +@deffn Command gnext +Go to the next group in the list. +@end deffn + +@deffn Command gprev +Go to the previous group in the list. +@end deffn + +@deffn Command gselect @var{group} +Select a particular group by name or number. If @var{group} is not +provided, ratpoison will interactively prompt for the group. +@end deffn + +@deffn Command gmerge @var{group} +Merge @var{group} with the current group. All windows in @var{group} +will be moved to the current group. @var{group} is not deleted. +@end deffn + +@deffn Command gdelete @var{group} +Delete a group. @var{group} is optional. If it is not specified +ratpoison will attempt to delete the current group. Only empty groups +can be deleted. To empty a group see @command{gmerge}. +@end deffn + +@node Frames, Multiple Monitors, Groups, Top +@chapter 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 +@ref{Concepts}). Each frame can then contain 1 window. + +@menu +* Splitting Frames:: +* Resizing Frames:: +* Frame Navigation Commands:: +* Saving and Restoring Frame Sets:: +@end menu + +@node Splitting Frames, Resizing Frames, Frames, Frames +@section Splitting Frames + +To split the +current frame horizontally use @kbd{C-t s}. To split the current frame +vertically use @kbd{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 +@kbd{C-t tab} to cycle through the frames. If you want to remove a +frame use @kbd{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 @kbd{C-t Q} to remove all splits +and leave you with the current window full screen. + +@deffn Command remove +Kill the current frame. This is a no-op if there is only one frame. +@end deffn + +@deffn Command only +Kill all frames but the current one. +@end deffn + +@deffn Command split @var{n} +@deffnx Command vsplit @var{n} +Split the current frame vertically in two. The last accessed window not occupying a frame will be the second window. -@item C-t S -@item C-t C-S -Split the current window vertically in two. The last accessed window not -occupying a frame will be the second window. +@var{n} is either a fraction of the form @code{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, @code{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. -@item C-t tab -Cycle through ratpoison's frames. +If it is a pixel, the original frame is resized to that many +pixels. If @var{n} has a minus sign before it, then the new frame will +shrink by that many pixels. +@end deffn + +@deffn Command hsplit @var{n} +Split the current frame horizontally in two. The last accessed window +not occupying a frame will be the second window. + +@var{n} is either a fraction of the form @code{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, @code{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 @var{n} has a minus sign before it, then the new frame will +shrink by that many pixels. +@end deffn + +@node Resizing Frames, Frame Navigation Commands, Splitting Frames, Frames +@section Resizing Frames +ratpoison provides a command, @command{resize}, that resizes the +current frame. It is bound to the key @kbd{C-t r} by +default. @command{resize} can be used non-interactively by providing +two arguments: the number of pixels to grow horizontally and the +number to grow vertically. For example, if you wanted to grow the +current window by 10 pixels horizontally and shrink it vertically by +50 you could enter the command: + +@example +resize 10 -50 +@end example + +When resizing interactively, the following keys are used: + +@table @kbd +@item C-p +Grow the frame vertically. +@item C-n +Shrink the frame vertically. +@item C-f +Grow the frame horizontally. +@item C-b +Shrink the frame horizontally. +@item return +Accept the new frame size. +@item C-g +Abort and restore the frame to its original size. +@end table + +The increment size used to resize the frame interactively is +customized with the command @command{defresizeunit}. + +@deffn Command defresizeunit @var{pixels} +Set the number of pixels a frame will grow or shrink by when being +dynamically resized. +@end deffn + +@deffn Command resize @var{horizontal} @var{vertical} +Resize the current frame by @var{horizontal} pixels horizontally, and +@var{vertical} pixels vertically. If no arguments are given and the +command is called interactively, ratpoison will let the user +dynamically resize the frame using @kbd{C-p} to shrink vertically, +@kbd{C-n} to grow vertically, @kbd{C-b} to shrink horizontally, +@kbd{C-f} to grow horizontally, and @kbd{s} to shrink the frame to the +size of the window (See the @command{shrink} command). When you have +resized the frame to your liking, press @kbd{Return} to finish. +@end deffn + +@deffn Command 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. +@end deffn + +@node Frame Navigation Commands, Saving and Restoring Frame Sets, Resizing Frames, Frames +@section Frame Navigation Commands + +Here are the commands for Navigating frames. + +@deffn Command fselect @var{n} +Select a frame by number. If an argument is passed to it then attempt +to select the frame whose number is @var{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. +@end deffn + +@deffn Command curframe +Indicate which frame is the current frame. +@end deffn + +@deffn Command focus +cycle through ratpoison's frames. +@end deffn + +@deffn Command focusdown +Move to the frame below the current frame. +@end deffn -@item C-t M-tab +@deffn Command focuslast Switch to the last focused frame. +@end deffn -@item C-t Q -Kill all frames but the current one. +@deffn Command focusleft +Move to the frame left of the current frame. +@end deffn -@item C-t R -Kill the current frame. This is a no-op if there is only one frame. +@deffn Command focusright +Move to the frame right of the current frame. +@end deffn -@item C-t r -@item C-t C-r -Resize the current frame. +@deffn Command focusup +Move to the frame above the current frame. +@end deffn -@item C-t b -@item C-t C-b -Banish the mouse to the lower right corner of the screen. +@node Saving and Restoring Frame Sets, , Frame Navigation Commands, Frames +@section Saving and Restoring Frame Sets +ratpoison provides two commands, @command{fdump} and +@command{frestore}, that allow the user to save and restore frame +configurations. Let's say, for example, you have split your desktop +into several frames with some windows in these frames and now you want +to quickly bring Emacs forward and browse some code (full-screen of +course) then return to your funky frame configuration. You could use +@command{fdump} to dump the frames, hit @kbd{C-t Q} to remove all +frames, and then select your emacs window. When you've finished with +emacs you could use @command{frestore} to restore the windows and +frames. -@item C-t ? -Display a help screen. +If a frame contained a window when you dumped the frame layout but +that window is not present when you restore the layout, the frame +holding that window will be blank. -@item C-t f -@item C-t C-f -select a frame by number. +Calling @command{fdump} and @command{frestore} and copying and pasting +the layout by hand each time is a bit cumbersome. There are some +simple bindings in @file{doc/sample.ratpoisonrc} that allow you to +save and restore frame layouts with the press of a key. -@item C-t F -Indicate which frame is the current frame. +@deffn Command fdump +dump the current frame layout as text. When used non-interactively +(from the command-line), ratpoison will print the frame layout. When +used interactively, nothing happens. +@end deffn -@end table +@deffn Command frestore @var{frames} +Restore the frame layout based on the list of frames +@var{frames}. @var{frames} should be the text that was printed after +calling @code{fdump}. +@end deffn + +@node Multiple Monitors, Keystrokes, Frames, Top +@chapter 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. -@node Commands, Input, Keystrokes, Top -@chapter Commands +The X Windowing System assigns each monitor a screen number. To switch +to another screen use the commands @command{nextscreen} and +@command{prevscreen}. ratpoison will tell you which frame has focus by +drawing the current frame indicator in it. -ratpoison can be controlled with commands (so called colon-commands). -The summary of available commands is listed below: +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 @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 @command{select} or @kbd{C-t '}), by number, +or you can use @command{nextscreen} and @command{prevscreen}. -@deffn Command abort -This is a pretty useless command. By default, it is bound to -@kbd{C-t g}, and its purpose is to abort other commands. +@deffn Command nextscreen +This jumps you to the next X11 screen. @command{nextscreen} is +used for dual-head displays and multiple monitor setups. @end deffn -@deffn Command addhook @var{hook} @var{command} -Add a @var{command} to @var{hook}. When the hook is run, @var{command} -will be executed. +@deffn Command prevscreen +This jumps you to the previous X11 screen. @command{prevscreen} is +used for dual-head displays and multiple monitor setups. +@end deffn -The following hooks are available: -@table @asis -@item key -Run when a top level key is pressed (by default the only top level key -is the prefix key). -@item switchwin -Run when the user switches to a different window in the current frame. -@item switchframe -Run when the user switches to another frame. This is also run when the -user switches to a different screen, since a frame switch also occurs. -@item switchgroup -Run when the user switches to a different group. -@item quit -Run when ratpoison exits. -@item restart -Run when ratpoison restarts. -@end table +@node Keystrokes, Hooks, Multiple Monitors, Top +@chapter Keystrokes -@end deffn +Interactive control of ratpoison is done entirely through +keystrokes. This chapter explains how keystrokes are stored and +manipulated. -@deffn Command alias @var{name} @var{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 @samp{emacs} that loads emacs. You would do it like this: +@menu +* Key Maps:: +* Default Key Bindings:: +@end menu -@example -: alias emacs exec emacs -@end example +@node Key Maps, Default Key Bindings, Keystrokes, Keystrokes +@section Key Maps -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 @command{ratpoison -c}. +All keystrokes exist inside a keymap. When you press the prefix key you +are accessing the @samp{root} keymap. By default all commands reside in +the @samp{root} key map and are accessed by pressing @kbd{C-t}. + +There is also a top level key map, @samp{top}. Any keystroke in this key +map can be accessed simply by pressing the key. This is where the prefix +key resides. + +The following functions control creating, editing, and deleting key maps. + +@deffn Command newkmap @var{kmap} +Create a new keymap named @var{kmap}. @end deffn -@deffn Command banish -Banish the mouse to the lower right corner of the screen. +@deffn Command delkmap @var{kmap} +Delete the keymap, @var{kmap}. @end deffn @deffn Command bind @var{Key} @var{command} @@ -526,329 +822,317 @@ If no command is specified then bind works exactly like @command{unbind}, unbinding the key. @end deffn -@deffn Command chdir -Change the current directory for ratpoison. +@deffn Command unbind @var{key} +Unbind a keystroke. @end deffn -@deffn Command clrunmanaged -Clear the unmanaged window list. See @command{unmanage} for an -explanation of the unmanaged window list. +@deffn Command definekey @var{kmap} @var{key} @var{command} +@command{definekey} works exactly like @command{bind} and +@command{unbind} except that it can bind keys on any key map (not just +@samp{root}). @end deffn -@deffn Command colon @var{command} -Run a ratpoison command. +@deffn Command undefinekey @var{kmap} @var{key} +Like @command{unbind} except that you pass it a key map in @var{kmap}. @end deffn -@deffn Command curframe -Indicate which frame is the current frame. +@deffn Command readkey @var{kmap} +Read a key from the keyboard and execute the command associated with +it in the keymap, @var{kmap}. @end deffn -@deffn Command defbarborder @var{n} -Set the border width for the bar window. +@deffn Command link @var{key} +Call the command that @var{key} is bound to. For instance +@command{link C-t} would call the command @command{other} and switch +to the last window. @end deffn -@deffn Command defbargravity @var{g} -Set the default alignment for the message bar. See the @command{gravity} command. +@node Default Key Bindings, , Key Maps, Keystrokes +@section Default Key Bindings -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +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. -@deffn Command defbarpadding @var{x} @var{y} -Set the horizontal and vertical padding inside the bar. +@table @kbd -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t C-t +Switch to the last window. -@deffn Command defbgcolor @var{color} -Set the background color for all text ratpoison displays. @var{color} -is any valid X11 color. -@end deffn +@item C-t t +Sometimes you need to send a C-t to the current window. This keystroke +does just that. -@deffn Command defborder @var{n} -Set the border width for all windows. +@item C-t 0-9 +Switch to the numbered window. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t - +Select no window, essentially hiding all windows in the current frame. -@deffn Command deffgcolor @var{color} -Set the foreground color for all text ratpoison displays. @var{color} -is any valid X11 color. -@end deffn +@item C-t A +@item C-t C-A +Rename the current window. The window's new name will prevail for the +rest of its lifetime. -@deffn Command deffont @var{font} -Set the font. @var{font} is a font string like @samp{9x15bold}. -@end deffn +@item C-t K +@item C-t C-K +Send a DestroyClient event to the current window. This will terminate +the application without question. -@deffn Command definputwidth @var{n} -Set the width of the input window. +@item C-t n +@item C-t C-n +@item C-t Return +@item C-t C-Return +@item C-t Space +@item C-t C-Space +Go to next window. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t p +@item C-t C-p +Go to previous window. -@deffn Command defmaxsizegravity @var{g} -Set the default alignment for windows with maxsize hints. See the -@command{gravity} command. +@item C-t ' +@item C-t C-' +Go to a window by name. You will usually only need to type the first +few characters of the window name. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t a +@item C-t C-a +Display the current time of day. -@deffn Command defpadding @var{left} @var{top} @var{right} @var{bottom} -Set the padding around the edge of the screen. +@item C-t c +@item C-t C-c +Open a new X terminal. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t : +This allows you to execute a single ratpoison command. -@deffn Command defresizeunit @var{pixels} -Set the number of pixels a frame will grow or shrink by when being -dynamically resized. -@end deffn +@item C-t ! +Run a shell command. -@deffn Command deftransgravity @var{g} -Set the default alignment for transient windows. See the -@command{gravity} command. +@item C-t C-! +Run a shell command through an X terminal. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t i +@item C-t C-i +Display information about the current window. -@deffn Command defwaitcursor @var{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. +@item C-t k +@item C-t C-k +Close the current window. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t l +@item 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. @kbd{C-t l} will force the +current window to maximize. -@deffn Command defwinfmt @var{fmt} -Set the default window format for the @command{windows} command. By -default it is @samp{%n%s%t}. The following is a list of valid format -characters: +@item C-t m +@item C-t C-m +Display the last message. -@table @samp -@item %n -The window number -@item %s -Window status (current window, last window, etc) -@item %t -Window Name -@item %a -Application Name -@item %c -Resource Class -@item %i -X11 Window ID -@item %l -A unique number based on when the window was last accessed. The higher -the number, the more recently it was accessed. -@end table +@item C-t v +@item C-t C-v +Display the version of ratpoison. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t V +@item C-t C-V +Display ratpoison's license. -@deffn Command defwingravity @var{g} -Set the default gravity for normal windows. See the -@command{gravity} command. +@item C-t w +@item C-t C-w +Display the list of managed windows. The current window is highlighted. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t s +@item C-t C-s +Split the current window horizontally in two. The last accessed window +not occupying a frame will be the second window. -@deffn Command defwinliststyle @var{setting} -The window list can be displayed in a row or a column. @var{setting} -can be @samp{row} or @samp{column}. -@end deffn +@item C-t S +@item C-t C-S +Split the current window vertically in two. The last accessed window not +occupying a frame will be the second window. -@deffn Command defwinname @var{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. @var{name} can be @samp{title} which is what most -window managers put in the title bar, @samp{name} which is the -res_name, or @samp{class} which is the res_class. +@item C-t tab +Cycle through ratpoison's frames. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@item C-t M-tab +Switch to the last focused frame. -@deffn Command delete -This deletes the current window. You can access it with the @kbd{C-t k} -keystroke. -@end deffn +@item C-t Q +Kill all frames but the current one. -@deffn Command newkmap @var{kmap} -Delete the keymap, @var{kmap}. +@item C-t R +Kill the current frame. This is a no-op if there is only one frame. -@end deffn +@item C-t r +@item C-t C-r +Resize the current frame. -@deffn Command echo @var{text} -Display @var{text} as a message. -@end deffn +@item C-t b +@item C-t C-b +Banish the mouse to the lower right corner of the screen. -@deffn Command escape @var{key} -Set the prefix to @var{key}. For example @samp{escape C-b} sets the -prefix key to @key{C-b}. -@end deffn +@item C-t ? +Display a help screen. -@deffn Command exec @var{command} -Execute a shell command. By default, @kbd{C-t !} does this. -@end deffn +@item C-t f +@item C-t C-f +select a frame by number. -@deffn Command fdump -dump the current frame layout as text. When used non-interactively -(from the command-line), ratpoison will print the frame layout. When -used interactively, nothing happens. -@end deffn +@item C-t F +Indicate which frame is the current frame. -@deffn Command focus -cycle through ratpoison's frames. -@end deffn +@end table -@deffn Command focusdown -Move to the frame below the current frame. -@end deffn +@node Hooks, The Status Bar, Keystrokes, Top +@chapter Hooks -@deffn Command focuslast -Switch to the last focused frame. -@end deffn +One of the goals of ratpoison is to allow users to create exciting +customization to fit their specific needs. Hooks allow a user to latch +scripts onto certain events. -@deffn Command focusleft -Move to the frame left of the current frame. -@end deffn +Each hook contains a list of commands to be executed when the +appropriate event occurs in ratpoison. For example, if you want to warp +the rat to corner of the screen everytime you press a top level bound +key, you could add this to you .ratpoisonrc file: -@deffn Command focusright -Move to the frame right of the current frame. -@end deffn +@example +addhook key banish +@end example -@deffn Command focusup -Move to the frame above the current frame. -@end deffn +That should keep the rat out of your way. -@deffn Command frestore @var{frames} -Restore the frame layout based on the list of frames -@var{frames}. @var{frames} should be the text that was printed after -calling @code{fdump}. -@end deffn +@deffn Command addhook @var{hook} @var{command} +Add a @var{command} to @var{hook}. When the hook is run, @var{command} +will be executed. -@deffn Command fselect @var{n} -Select a frame by number. If an argument is passed to it then attempt -to select the frame whose number is @var{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. -@end deffn +The following hooks are available: -@deffn Command gdelete @var{group} -Delete a group. @var{group} is optional. If it is not specified -ratpoison will attempt to delete the current group. Only empty groups -can be deleted. To empty a group see @command{gmerge}. -@end deffn +@table @asis +@item key +Run when a top level key is pressed (by default the only top level key +is the prefix key). +@item switchwin +Run when the user switches to a different window in the current frame. +@item switchframe +Run when the user switches to another frame. This is also run when the +user switches to a different screen, since a frame switch also occurs. +@item switchgroup +Run when the user switches to a different group. +@item quit +Run when ratpoison exits. +@item restart +Run when ratpoison restarts. +@end table -@deffn Command getenv @var{env} -Display the value of the environment variable, @var{env}. @end deffn -@deffn Command gmerge @var{group} -Merge @var{group} with the current group. All windows in @var{group} -will be moved to the current group. @var{group} is not deleted. +@deffn Command remhook @var{hook} @var{command} +Remove @var{command} from the hook. See @command{addhook} for a list +of available hooks. @end deffn -@deffn Command gmove @var{group} -Move the current window to @var{group}. -@end deffn -@deffn Command gnew @var{name} -Create a new group with the name @var{name}. @var{name} is -optional. This new group becomes the new group. -@end deffn +@node The Status Bar, Using Other Window Managers, Hooks, Top +@chapter The Status Bar -@deffn Command gnewbg @var{name} -This is the same as @command{gnew} except that the current group does -not change. -@end deffn +ratpoison presents status and output through the status bar. By default +it is located in the top right corner of the screen. -@deffn Command gnext -Go to the next group in the list. -@end deffn +This chapter presents commands for manipulating the status bar. -@deffn Command gprev -Go to the previous group in the list. -@end deffn +Since it is the only visible evidence that ratpoison is running (as +opposed to the invisible evidence including the lack of title bars and +your favorite desktop background) there are also copious visual +customizations available for those rainy days. -@deffn Command gravity @var{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 @var{g} are the 8 -directions @samp{northwest}, @samp{north}, @samp{northeast}, -@samp{east}, @samp{southeast}, @samp{south}, @samp{southwest} and -@samp{west}, clockwise from the top left corner. @samp{center} will -center the window in the frame. @var{g} and can be abbreviated to the -standard compass 1 and 2 letter abbreviations (i.e. @samp{nw}, -@samp{s}, etc). +@deffn Command msgwait @var{n} +Set the bar's timeout in seconds. When called non-interactively with no arguments, the current setting is returned. @end deffn -@deffn Command groups -Display a list of groups with a similar format to @command{windows}. +@deffn Command lastmsg +Display the last message. @end deffn -@deffn Command gselect @var{group} -Select a particular group by name or number. If @var{group} is not -provided, ratpoison will interactively prompt for the group. +@deffn Command echo @var{text} +Display @var{text} as a message. @end deffn -@deffn Command help -Display a help screen that lists all bound keystrokes. -@end deffn +@deffn Command definputwidth @var{n} +Set the width of the input window. -@deffn Command info -Display information about the current window. +When called non-interactively with no arguments, the current setting is +returned. @end deffn -@deffn Command kill -This destroys the current window. Normally you should only need to -use @command{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 -@kbd{C-t K}. +@deffn Command deffont @var{font} +Set the font. @var{font} is a font string like @samp{9x15bold}. @end deffn -@deffn Command lastmsg -Display the last message. +@deffn Command deffgcolor @var{color} +Set the foreground color for all text ratpoison displays. @var{color} +is any valid X11 color. @end deffn -@deffn Command license -Display ratpoison's license. By default, this is bound to @kbd{C-t V}. +@deffn Command defbgcolor @var{color} +Set the background color for all text ratpoison displays. @var{color} +is any valid X11 color. @end deffn -@deffn Command link @var{key} -Call the command that @var{key} is bound to. For instance -@command{link C-t} would call the command @command{other} and switch -to the last window. -@end deffn +@deffn Command defbarpadding @var{x} @var{y} +Set the horizontal and vertical padding inside the bar. -@deffn Command meta -Send a @kbd{C-t} to the current window. +When called non-interactively with no arguments, the current setting is +returned. @end deffn -@deffn Command msgwait @var{n} -Set the bar's timeout in seconds. +@deffn Command defbargravity @var{g} +Set the default alignment for the message bar. See the @command{gravity} command. When called non-interactively with no arguments, the current setting is returned. @end deffn -@deffn Command newkmap @var{kmap} -Create a new keymap named @var{kmap}. +@deffn Command defbarborder @var{n} +Set the border width for the bar window. +@end deffn + + +@node Using Other Window Managers, Other Commands, The Status Bar, Top +@chapter Using Other Window Managers + +There are times when a program has been so badly written that it is +virtually impossible to use under ratpoison. Some authors have tailored +their programs to certain window management paradigms so aggressively +that very little can be done. Ratpoison has two commands to help you +through these difficult times: @command{tmpwm} and @command{newwm}. + +These commands should be used sparingly. They were created to allow +users to understand how a poorly designed program is intended to +function so they can build a replacement or patch an existing +alternative's missing functionality. + +According to independant studies, @command{tmpwm} has been used almost +exclusively to verify it's correct operation -- like a vintage sports +care: always kept in prime condition and never used. + +@command{tmpwm} and @command{newwm} are provided for boasting and +completeness. + +@deffn Command tmpwm @var{WM} +Gives control over to another window manager and regains control once +it has terminated. @var{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. @end deffn @deffn Command newwm @var{window-manager} @@ -856,165 +1140,106 @@ This is a bad-bad command. It kills ratpoison and revives that ugly rodent! Yuck! Avoid! @end deffn -@deffn Command next -This jumps you to the next window in the window list. This one is -bound to three keystrokes, namely @kbd{C-t n}, @kbd{C-t space}, -and @kbd{C-t enter}. -@end deffn +@node Other Commands, Input, Using Other Window Managers, Top +@chapter Other Commands -@deffn Command nextscreen -This jumps you to the next X11 screen. @command{nextscreen} is -used for dual-head displays and multiple monitor setups. +The following is a list of commands that don't fit in any existing +chapters. + +@deffn Command abort +This is a pretty useless command. By default, it is bound to @kbd{C-t +g} and its purpose is to abort the current chain of keystrokes (just +like @kbd{C-g} in @samp{Emacs}). @end deffn -@deffn Command number @var{n} @var{target} -Set a window's number to @var{n}. If another window occupies the -requested number already, then the windows' numbers are swapped. +@deffn Command alias @var{name} @var{command} +Allows you to name a ratpoison command something else. For +instance, if you frequently open emacs you may want to make an alias +called @samp{emacs} that loads emacs. You would do it like this: -The second argument, @var{target}, is optional. It should be the -number of the window whose number will be changed. If @var{target} is -omitted ratpoison defaults to the current window. -@end deffn +@example +: alias emacs exec emacs +@end example -@deffn Command only -Kill all frames but the current one. +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 @command{ratpoison -c}. @end deffn -@deffn Command other -This toggles between the current window and the last window. By -default, this is bound to @kbd{C-t C-t}. +@deffn Command banish +Banish the mouse to the lower right corner of the screen. @end deffn -@deffn Command prev -This jumps you to the previous window in the window list. By default, -this is bound to @kbd{C-t p}. +@deffn Command chdir +Change the current directory for ratpoison. @end deffn -@deffn Command prevscreen -This jumps you to the previous X11 screen. @command{prevscreen} is -used for dual-head displays and multiple monitor setups. +@deffn Command colon @var{command} +Run a ratpoison command. @end deffn -@deffn Command quit -Quit ratpoison. +@deffn Command defpadding @var{left} @var{top} @var{right} @var{bottom} +Set the padding around the edge of the screen. + +When called non-interactively with no arguments, the current setting is +returned. @end deffn -@deffn Command readkey @var{kmap} -Read a key from the keyboard and execute the command associated with -it in the keymap, @var{kmap}. +@deffn Command defwaitcursor @var{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. @end deffn -@deffn Command redisplay -Redisplay the current window, just like @kbd{C-t l} would do. +@deffn Command escape @var{key} +Set the prefix to @var{key}. For example @samp{escape C-b} sets the +prefix key to @key{C-b}. @end deffn -@deffn Command remhook @var{hook} @var{command} -Remove @var{command} from the hook. See @command{addhook} for a list -of available hooks. +@deffn Command exec @var{command} +Execute a shell command. By default, @kbd{C-t !} does this. @end deffn -@deffn Command remove -Kill the current frame. This is a no-op if there is only one frame. +@deffn Command getenv @var{env} +Display the value of the environment variable, @var{env}. @end deffn -@deffn Command resize @var{horizontal} @var{vertical} -Resize the current frame by @var{horizontal} pixels horizontally, and -@var{vertical} pixels vertically. If no arguments are given and the -command is called interactively, ratpoison will let the user -dynamically resize the frame using @kbd{C-p} to shrink vertically, -@kbd{C-n} to grow vertically, @kbd{C-b} to shrink horizontally, -@kbd{C-f} to grow horizontally, and @kbd{s} to shrink the frame to the -size of the window (See the @command{shrink} command). When you have -resized the frame to your liking, press @kbd{Return} to finish. +@deffn Command help +Display a help screen that lists all bound keystrokes. @end deffn -@deffn Command restart -Restart ratpoison. +@deffn Command license +Display ratpoison's license. By default, this is bound to @kbd{C-t V}. @end deffn -@deffn Command rudeness @var{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. - -@var{n} is a number from 0 to 15. Each of the four bits determine -which requests ratpoison grants. - -@table @asis -@item Bit 0 -Tells ratpoison to grant raise requests on transient windows - -@item Bit 1 -Tells ratpoison to grant raise requests on normal windows - -@item Bit 2 -Tells ratpoison to grant display requests on new transient windows - -@item Bit 3 -Tells ratpoison to grant display requests on new normal windows -@end table - -For example, if you wanted only wanted to grant transient windows -raise requests and display requests you would type @samp{rudeness -5}. If a request is not granted ratpoison will tell you about the -request with a message like @samp{Raise request from window 1 -(emacs)}. +@deffn Command meta +Send a @kbd{C-t} to the current window. +@end deffn -When called non-interactively with no arguments, the current setting is -returned. +@deffn Command quit +Quit ratpoison. @end deffn -@deffn Command select @var{n} -This jumps you to window @var{n} where @var{n} is the window number as -shown in the Program Bar. You can do the same trick with -@command{C-@var{n}} too. To select no window, blanking the current -frame, type @samp{select -}. +@deffn Command redisplay +Redisplay the current window. This is often used to fix xterms that +didn't catch ratpoison's initial maximize event. @end deffn -@deffn Command select @var{window-name} -Go to a window by name. A shortcut is @kbd{C-t '}. +@deffn Command restart +Restart ratpoison. @end deffn @deffn Command setenv @var{env} @var{value} Set the environment variable @var{env} to @var{value} @end deffn -@deffn Command 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. -@end deffn - @deffn Command source @var{file} Read a text file containing ratpoison commands. @end deffn -@deffn Command split @var{n} -@deffnx Command vsplit @var{n} -Split the current frame vertically in two. The last accessed window -not occupying a frame will be the second window. - -@var{n} is either a fraction of the form @code{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, @code{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 @var{n} has a minus sign before it, then the new frame will -shrink by that many pixels. -@end deffn - @deffn Command startup_message @var{state} Turn on or off the startup_message. This is most useful in your .ratpoisonrc file. @var{state} can be @code{on} or @code{off}. @@ -1023,43 +1248,14 @@ When called non-interactively with no arguments, the current setting is returned. @end deffn -@deffn Command tmpwm @var{WM} -Gives control over to another window manager and regains control once -it has terminated. @var{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. -@end deffn - @deffn Command time -Show current time. Disappears after 5 seconds, like all other info bars. -In the default setup, the @kbd{C-t a} keystroke is bound to this command. -@end deffn - -@deffn Command title @var{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 @kbd{C-t A} keystroke is bound to this command. +Show current time in the status bar. @end deffn @deffn Command unalias @var{name} Remove @var{name} from the list of defined aliases. @end deffn -@deffn Command unbind @var{key} -Unbind a keystroke. -@end deffn - -@deffn Command unmanage @var{text} -Add @var{text} to the unmanaged window list. Any window whose name -matches any of the strings in the unmanaged window list will not be -handled in any way by ratpoison. This only applies to new windows (not -windows already managed by ratpoison). - -When called non-interactively with no arguments, the list is returned. -@end deffn - @deffn Command unsetenv @var{env} Clear the value of the environment variable, @var{env}. @end deffn @@ -1073,22 +1269,6 @@ message saying command was executed. Print ratpoison version. By default, this is bound to @kbd{C-t v}. @end deffn -@deffn Command hsplit @var{n} -Split the current frame horizontally in two. The last accessed window -not occupying a frame will be the second window. - -@var{n} is either a fraction of the form @code{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, @code{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 @var{n} has a minus sign before it, then the new frame will -shrink by that many pixels. -@end deffn - @deffn Command warp @var{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 @@ -1096,33 +1276,7 @@ rat's position is restored. This can be counter-intuitive, so you can toggle it with this command. @var{state} can be @code{on} or @code{off}. @end deffn -@deffn Command windows @var{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 @kbd{C-t @var{n}} where @var{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 @kbd{C-t '} and type the number at the -prompt. - -After 5 seconds the Program Bar disappears. - -This command is bound to @kbd{C-t w} by default. - -When invoked from the command-line like this, - -@example -$ ratpoison -c windows -@end example - -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 @var{fmt} comes into play. If -@command{windows} is given an arg it treats it as the format string as -described in @command{defwinfmt}. -@end deffn - -@node Input, Command Line Arguments, Commands, Top +@node Input, Command Line Arguments, Other Commands, Top @chapter Input At various times ratpoison will prompt you for input. Ratpoison sports a fully featured line editor. The following table lists the keystrokes -- cgit v1.2.3