diff options
Diffstat (limited to 'doc/ratpoison.texi')
| -rw-r--r-- | doc/ratpoison.texi | 1224 |
1 files changed, 689 insertions, 535 deletions
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,11 +213,347 @@ 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 +@node Windows, Groups, General Use, Top +@chapter Windows + +Windows are what ratpoison manages. + +@menu +* Manipulating Windows:: +* Unmanaged Windows:: +* Rudeness:: +@end menu + +@node Manipulating Windows, Unmanaged Windows, Windows, Windows +@section Manipulating Windows + +The following are commands used to manipulate windows. + +@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 + +@deffn Command select @var{window-name} +Go to a window by name. A shortcut is @kbd{C-t '}. +@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 + +@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 + +@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 + +@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 + +@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 + +@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 + + +@deffn Command info +Display information about the current window. +@end deffn + +@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). + +When called non-interactively with no arguments, the current setting is +returned. +@end deffn + +@deffn Command delete +This deletes the current window. You can access it with the @kbd{C-t k} +keystroke. +@end deffn + +@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. + +When called non-interactively with no arguments, the current setting is +returned. +@end deffn + +@deffn Command defwingravity @var{g} +Set the default gravity for normal windows. See the +@command{gravity} command. + +When called non-interactively with no arguments, the current setting is +returned. +@end deffn + +@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 + +@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: + +@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 + +When called non-interactively with no arguments, the current setting is +returned. +@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. + +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 + +@deffn Command deftransgravity @var{g} +Set the default alignment for transient windows. See the +@command{gravity} command. + +When called non-interactively with no arguments, the current setting is +returned. +@end deffn + +@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. To split the +@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 @@ -237,12 +571,48 @@ 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. -@menu -* Resizing Frames:: -* Saving and Restoring Frame Sets:: -@end menu +@deffn Command remove +Kill the current frame. This is a no-op if there is only one frame. +@end deffn -@node Resizing Frames, Saving and Restoring Frame Sets, Splitting Frames, Splitting Frames +@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. + +@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 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 @@ -276,7 +646,71 @@ Abort and restore the frame to its original size. The increment size used to resize the frame interactively is customized with the command @command{defresizeunit}. -@node Saving and Restoring Frame Sets, , Resizing Frames, Splitting Frames +@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 + +@deffn Command focuslast +Switch to the last focused frame. +@end deffn + +@deffn Command focusleft +Move to the frame left of the current frame. +@end deffn + +@deffn Command focusright +Move to the frame right of the current frame. +@end deffn + +@deffn Command focusup +Move to the frame above the current frame. +@end deffn + +@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 @@ -298,7 +732,19 @@ 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. -@node Multiple Monitors, Keystrokes, Splitting Frames, Top +@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 + +@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 @@ -319,9 +765,91 @@ 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}. -@node Keystrokes, Commands, Multiple Monitors, Top +@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 prevscreen +This jumps you to the previous X11 screen. @command{prevscreen} is +used for dual-head displays and multiple monitor setups. +@end deffn + + +@node Keystrokes, Hooks, Multiple Monitors, Top @chapter Keystrokes +Interactive control of ratpoison is done entirely through +keystrokes. This chapter explains how keystrokes are stored and +manipulated. + +@menu +* Key Maps:: +* Default Key Bindings:: +@end menu + +@node Key Maps, Default Key Bindings, Keystrokes, Keystrokes +@section Key Maps + +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 delkmap @var{kmap} +Delete the keymap, @var{kmap}. +@end deffn + +@deffn Command bind @var{Key} @var{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 @kbd{C-t R} to +restart ratpoison: + +@example +: bind R restart +@end example + +If no command is specified then bind works exactly like @command{unbind}, +unbinding the key. +@end deffn + +@deffn Command unbind @var{key} +Unbind a keystroke. +@end deffn + +@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 undefinekey @var{kmap} @var{key} +Like @command{unbind} except that you pass it a key map in @var{kmap}. +@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}. +@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 + +@node Default Key Bindings, , Key Maps, Keystrokes +@section Default Key Bindings + 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 @@ -459,16 +987,23 @@ Indicate which frame is the current frame. @end table -@node Commands, Input, Keystrokes, Top -@chapter Commands +@node Hooks, The Status Bar, Keystrokes, Top +@chapter Hooks -ratpoison can be controlled with commands (so called colon-commands). -The summary of available commands is listed below: +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 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. -@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: + +@example +addhook key banish +@end example + +That should keep the rat out of your way. @deffn Command addhook @var{hook} @var{command} Add a @var{command} to @var{hook}. When the hook is run, @var{command} @@ -495,526 +1030,216 @@ Run when ratpoison restarts. @end deffn -@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: - -@example -: alias emacs exec emacs -@end example - -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 banish -Banish the mouse to the lower right corner of the screen. -@end deffn - -@deffn Command bind @var{Key} @var{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 @kbd{C-t R} to -restart ratpoison: - -@example -: bind R restart -@end example - -If no command is specified then bind works exactly like @command{unbind}, -unbinding the key. +@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 chdir -Change the current directory for ratpoison. -@end deffn -@deffn Command clrunmanaged -Clear the unmanaged window list. See @command{unmanage} for an -explanation of the unmanaged window list. -@end deffn +@node The Status Bar, Using Other Window Managers, Hooks, Top +@chapter The Status Bar -@deffn Command colon @var{command} -Run a ratpoison command. -@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 curframe -Indicate which frame is the current frame. -@end deffn +This chapter presents commands for manipulating the status bar. -@deffn Command defbarborder @var{n} -Set the border width for the bar window. -@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 defbargravity @var{g} -Set the default alignment for the message bar. See the @command{gravity} command. +@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 defbarpadding @var{x} @var{y} -Set the horizontal and vertical padding inside the bar. - -When called non-interactively with no arguments, the current setting is -returned. +@deffn Command lastmsg +Display the last message. @end deffn -@deffn Command defbgcolor @var{color} -Set the background color for all text ratpoison displays. @var{color} -is any valid X11 color. +@deffn Command echo @var{text} +Display @var{text} as a message. @end deffn -@deffn Command defborder @var{n} -Set the border width for all windows. +@deffn Command definputwidth @var{n} +Set the width of the input window. When called non-interactively with no arguments, the current setting is returned. @end deffn -@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 deffont @var{font} Set the font. @var{font} is a font string like @samp{9x15bold}. @end deffn -@deffn Command definputwidth @var{n} -Set the width of the input window. - -When called non-interactively with no arguments, the current setting is -returned. +@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 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. +@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 defpadding @var{left} @var{top} @var{right} @var{bottom} -Set the padding around the edge of the screen. +@deffn Command defbarpadding @var{x} @var{y} +Set the horizontal and vertical padding inside the bar. When called non-interactively with no arguments, the current setting is returned. @end deffn -@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 deftransgravity @var{g} -Set the default alignment for transient windows. See the -@command{gravity} command. +@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 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. +@deffn Command defbarborder @var{n} +Set the border width for the bar window. @end deffn -@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: -@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 - -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +@node Using Other Window Managers, Other Commands, The Status Bar, Top +@chapter Using Other Window Managers -@deffn Command defwingravity @var{g} -Set the default gravity for normal windows. See the -@command{gravity} command. +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}. -When called non-interactively with no arguments, the current setting is -returned. -@end deffn +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. -@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 +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. -@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. +@command{tmpwm} and @command{newwm} are provided for boasting and +completeness. -When called non-interactively with no arguments, the current setting is -returned. +@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 delete -This deletes the current window. You can access it with the @kbd{C-t k} -keystroke. +@deffn Command newwm @var{window-manager} +This is a bad-bad command. It kills ratpoison and revives that +ugly rodent! Yuck! Avoid! @end deffn -@deffn Command newkmap @var{kmap} -Delete the keymap, @var{kmap}. +@node Other Commands, Input, Using Other Window Managers, Top +@chapter Other Commands -@end deffn +The following is a list of commands that don't fit in any existing +chapters. -@deffn Command echo @var{text} -Display @var{text} as a message. +@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 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 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: -@deffn Command exec @var{command} -Execute a shell command. By default, @kbd{C-t !} does this. -@end deffn +@example +: alias emacs exec emacs +@end example -@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. +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 focus -cycle through ratpoison's frames. +@deffn Command banish +Banish the mouse to the lower right corner of the screen. @end deffn -@deffn Command focusdown -Move to the frame below the current frame. +@deffn Command chdir +Change the current directory for ratpoison. @end deffn -@deffn Command focuslast -Switch to the last focused frame. +@deffn Command colon @var{command} +Run a ratpoison command. @end deffn -@deffn Command focusleft -Move to the frame left of the current frame. -@end deffn +@deffn Command defpadding @var{left} @var{top} @var{right} @var{bottom} +Set the padding around the edge of the screen. -@deffn Command focusright -Move to the frame right of the current frame. +When called non-interactively with no arguments, the current setting is +returned. @end deffn -@deffn Command focusup -Move to the frame above the current frame. -@end deffn +@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. -@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}. +When called non-interactively with no arguments, the current setting is +returned. @end deffn -@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. +@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 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}. +@deffn Command exec @var{command} +Execute a shell command. By default, @kbd{C-t !} does this. @end deffn @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. -@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 - -@deffn Command gnewbg @var{name} -This is the same as @command{gnew} except that the current group does -not change. -@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 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). - -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}. -@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 help Display a help screen that lists all bound keystrokes. @end deffn -@deffn Command info -Display information about the current window. -@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}. -@end deffn - -@deffn Command lastmsg -Display the last message. -@end deffn - @deffn Command license Display ratpoison's license. By default, this is bound to @kbd{C-t V}. @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 meta Send a @kbd{C-t} to the current window. @end deffn -@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 newkmap @var{kmap} -Create a new keymap named @var{kmap}. - -@end deffn - -@deffn Command newwm @var{window-manager} -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 - -@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 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. - -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 - -@deffn Command only -Kill all frames but the current one. -@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}. -@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}. -@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. -@end deffn - @deffn Command quit Quit ratpoison. @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}. - -@end deffn - @deffn Command redisplay -Redisplay the current window, just like @kbd{C-t l} would do. -@end deffn - -@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 remove -Kill the current frame. This is a no-op if there is only one frame. -@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. +Redisplay the current window. This is often used to fix xterms that +didn't catch ratpoison's initial maximize event. @end deffn @deffn Command restart Restart ratpoison. @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)}. - -When called non-interactively with no arguments, the current setting is -returned. -@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 -}. -@end deffn - -@deffn Command select @var{window-name} -Go to a window by name. A shortcut is @kbd{C-t '}. -@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 |