ratmen(1)ratmen(1)NAMEratmen - create a menu to run commands
SYNOPSISratmen [OPTION]... MENUITEM COMMAND...
ratmen [OPTION]... {-d##|--delimiter ##} MENUITEM##COMMAND ...
DESCRIPTION
Ratmen is a simple program that accepts a list of MENUITEM and COMMAND
pairs on the command line. It creates a window that consists of nothing
but a menu. When a particular MENUITEM is selected by the user, the
corresponding COMMAND is executed or (using --print) printed on
standard output.
Menu items and commands may either be given separately (as in ratmenu)
using two arguments for each menu option, or, optionally you may
specify a delimiter (using the --delimiter option) and specify both
menu item and command in the same argument (similar to 9menu). The
delimiter may be of any length.
If the command is omitted (or if an empty command is supplied when not
using --delimiter) then the menu item text will be used as the command.
OPTIONS
Some options may be specified using X resouces (allowing you to define
some defaults you like in your in you ~/.Xresources, ~/.Xdefaults or
similar). To make this mechanism as useful as possible I would suggest
that you refrain from using such options on the command line, unless
you really need to, and instead enable/disable the corresponding X
resource setting.
ratmen's default resource class is the name of the executed file,
either ratmen or, if the executable was called through a link, the name
of the link in question. The command line option --class may be used to
override the default X resource class name.
--align {left|center|right} (X resource: align)
Aligns the text of the menu entries to the left, center or
right. Defaults to left. (Short options -l, -c and -r may also
be used for left, center and right respectivelly.)
-b, --back PREVMENU
Run command PREVMENU when user goes back in the menu hierarchy.
Useful when using nested menus; it gives the user a way to back
out and return to the previous menu. Note that you can use this
option for other things too. The command specified by the
--back option is executed when the user hits one of the "back"
keys.
--background BGCOLOR (X resource: background)
Set the background color to BGCOLOR. By default, the background
color is black. BGCOLOR may be the name of any color accepted
by your X server.
-C, --class CLASSNAME
This option allows you to override ratmen's resource class.
Normally it is "ratmen", but it can be set to another class
such as "ratmenu" to override selected resources.
--debug Makes ratmen talk quite a lot on standard error.
-d, --delimiter DELIM
This changes the behaviour when parsing subsequent
menuitem/command pairs.
Normally the command line argumens are taken to be alternately
menu items and their related commands, thus requiring an even
number of arguments to be passed to ratmen. (If a command is
given as "" it is taken to be the same as the menu item.) This
behaviour can make it somewhat difficult to distinguish between
menu item arguments and command arguments in cases where the
menu grow quite big (e.g. in a script). Therefore an
alternative is provided...
If you specify a delimiter (using --delimiter) this behaviour
is changed and the menu item and command are both expected to
occur in the same argument, separated by whatever delimiter
you've specified. This makes the command line easier to read
(for a human) but is sometimes disadvantageous, especially in
autogenerated menus, since the delimiter in question cannot
occur in the menu item text. (See also "EXAMPLES" below.)
-D, --display DISPLAYNAME
Use the X display DISPLAYNAME, instead of the default display.
Normally you won't need to use this.
--foreground FGCOLOR (X resource: foreground)
Set the foreground color to FGCOLOR. By default, the foreground
color is black. FGCOLOR may be the name of any color accepted
by your X server.
-F, --font FONTNAME (X resource: font)
Use the font FONTNAME instead of the default font.
-h, --help
Output a brief help message.
--mouse (X resource: mouse)
--no-mouse
Enable/disable mouse support in ratmen. The mouse support is
quite limited (you can't scroll a large menu using the mouse)
and is only intended for those moments when you instinctively
want to click on something you see in order to select it. See
also "MOUSE SUPPORT".
Use "ratmen.mouse: false" (or `no' or `off') in your X resource
file to disable mouse support as a default, and "ratmen.mouse:
true" (or `yes' or `on) to enable it.
-i, --item POSITION
Pre-select menu item number POSITION, instead of the first menu
item, upon opening the menu. Menu items are numbered from 1.
This is sometimes useful in scripts.
If POSITION is 0, then no item is selected initially. Going up
one item will make the menu jump to the last item, going down
will jump to the first item. Pressing enter while no item is
selected is the same as aborting. There is no way to zero
entries, other than this, so if you move about you cannot
return to the state where no item is selected (but why should
you ever want that?).
The described behavior is useful when the initially selected
item denotes a `current' value (useful when called from a
script) and the absence of a selected item may be used to
indicate that there is no such `current' value.
-p, --print
Prints the COMMAND associated with the selected MENUITEM on
standard output instead of running it.
Using this option you can use a menu for all kinds of
selections, and not only for running a program. When using this
option COMMAND no longer need to be a valid command at all --
any string will work. See also "EXAMPLES" below.
-o, --scroll-offset ITEMS (X resource: scrollOffset)
If a menu is too large to fit in one window, it will become
scrollable. Ratmen will try to keep at least ITEMS number of
items between the current position and the top or bottom of the
menu. If you get closer than this, the menu will scroll. As you
get close to the top or bottom of the menu scrolling will
cease. (Default scroll offset is 3.)
Scroll offset may not be larger than half of the menu. If it is
it will be cut down to that value.
-S, --shell PROG
Use PROG as the shell to run commands, instead of /bin/sh. A
popular alternative shell is rc(1). If the shell cannot be
executed, ratmen will silently fall back to using /bin/sh.
-s, --style {snazzy|dreary} (X resource: style)
The default style is dreary, where the highlight bar moves up
and down the menu as it does on all conventional keyboard
controlled menus. In dreary mode, the highlight bar, which
shows the currently selected item, remains stationary while all
the menu items are rotated up or down when the cursor keys are
moved.
-t, --title NAME
Change the title of the menu window to NAME. The default title
is the last component of the path used to run ratmen,
typically, "ratmen".
--unfocus-exit (X resource: unfocusExit)
--no-unfocus-exit
FIXME: Currently a `BadWindow' error message is generated by X
when the current instance of ratmen dies of unfocus. Does
anyone know how to fix this?
--unfocus-exit causes ratmen to die (without any option being
selected) if its window loses focus (it's probably not a good
to use in combination with a window manager that automatically
focuses the window under your pointer).
--no-unfocus-exit makes ratmen survive unfocusing. This can be
confusing in some cases as it makes it possible to have start
several menus at once (normally the previous menu would die
from unfocus).
Use "ratmen.unfocusExit: false" (or `no' or `off') in your X
resource file to disable unfocus deaths as a default, and
"ratmen.unfocusExit: true" (or `yes' or `on) to enable it.
-V, --version
This option prints the version of ratmen on the standard
output, and then exits with an exit value of zero.
KEYSTROKES
The Up keystrokes move the selection to the next item up. The Down
keystrokes move the selection to the next item down. When the selection
reaches the top or bottom, it scrolls around to the other side on
pressing of the appropriate keystroke. The Select keystrokes execute
the command corresponding to the currently selected menu item, and exit
ratmen. The Back keystrokes does nothing unless the --back option was
used, in which case it will run the command specified by that option
and exit ratmen. The Exit keystrokes quit ratmen without doing
anything.
Up "k", Up_arrow, BackSpace, "-"
Down "j", Down_arrow, Space, Tab, "+"
Select "l", Right_arrow, Return
Back "h", Left_arrow
Exit "q", Escape
MOUSE SUPPORT
Ratmen implements limited support for the rodent, you may select an
item (left), go to any previous menu, given by --back, (right) or abort
the menu (any other; usually middle). The mouse cannot be used to
scroll the menu.
Your rodent won't interfere with the normal operation. If you place the
pointer on the menu by mistake, simply move it outside of the menu to
restore the selection. You may, however, use the keys to manipulate an
entry selected with the mouse, in this case the key based selection
sticks.
Actions are performed upon releasing a mouse butten. To cancel an
action after the button has been pressed, move it outside the menu
window and release the button (this goes for all the buttons).
EXAMPLES
How about creating a little remote shell menu? The ratmenuish approach
would be
ratmen--label Remotes xterm "" acme "rsh acme xterm" herman "rsh herman 9term" &
and to do it the 9menu way, type something like
ratmen--label Remotes -d: xterm "acme:rsh acme xterm" "herman:rsh herman 9term" &
to do the trick. You could also make a menu containing some nice X
programs to run. Like this:
ratmen--label "X progs" ghostview "" xdvi "" xeyes "" xneko "" &
Or like this:
ratmen--label -d: "X progs" ghostview xdvi xeyes xneko &
That last one is a bit easier on the eyes, don't you think? If you
want, you can use the --back to call an "earlier" menu, like this:
ratmen--back ~/bin/mypreviousmenu "X Eyes" xeyes &
If you'd like to use a menu from within a shell script (a similar
technique may of course be employed from any other programming
language, such as perl) you could use the following:
choice=`ratmen -pd: Abort Retry Ignore`
Now any of the options selected will be put into the environment
variable `$choice' (note, though, that this may also be empty if the
user cancelled the
menu). Here -p (or --print) option is used to print the selected
COMMAND to standard out instead of running it, and -d (or --delimiter)
is used simply to avoid having to fill out the command line with a lot
of ugly "" arguments. (You could, of course, replace the colon in the
command line with any character that you don't use in the menu.)
And here are some lines from my ~/.Xresources file, for those
interested:
! ratmen ratmen*foreground: yellow ratmen*font:
-adobe-courier-medium-r-normal-*-18-*-*-*-m-*-iso8859-1
ratmen*unfocusExit: true
This makes my menus easily distinguishable (since not much else is
yellow in my system configuration), easily readable (since I like
courier) and doesn't clutty my screen too much in case I happen to
forget about them and go about doing something else instead of choosing
and item from the menu.
SEE ALSO
/etc/X11/rgb.txt where you may find the names of appropriate colours to
use with the --background and --forground options and X resources.
AUTHORS
The initial idea for this program was by Arnold Robbins, after having
worked with John Mackin's GWM Blit emulation. Matty Farrow wrote a
version using libXg, from which some ideas were borrowed. This code was
written by David Hogan and Arnold Robbins. Rich Salz motivated the
-shell option. Jonathan Walther modified this code to play nicely with
the ratpoison window manager by removing handling of mouse events and
iconification.
Zrajm C Akfogh <ratmen-mail@klingonska.org> changed command line syntax
into the more standard getopts, added scrolling capacity if menu is to
large to fit all at once, added --delimiter, --item, --print,
--scroll-offset and --unfocus-exit options and X resource support (Yay!
No need to specify those longish font-thingies on the command line any
more!).
The name `ratmen' is both an abbreviation of `ratmenu' (from which this
program is heavily derived) and a reference to the fact that *I* don't
have any religious reasons for not using the rodent (I like the
keyboard, but I also like freedom of choice).
FUTURE
I have not activelly made any changes to this program for several
years, though it was originally my intention to write a program that
works both under X, and in the console.
I later wrote termmen, which much closer resembles my intentions for
ratmen, but unfortunately only works in the console or terminal (i.e.
does not pop up a window of its own under X). Both termmen and this
program is available from <http://zrajm.klingonska.org/programs/>.
This program is written in C, which is not my native language, while
Termmen is written as a zsh script. If anyone would like to continue
development of ratmen, or a have a patch they'd like applied. Please
feel free to send it to me at ratmen-mail@klingonska.org.
HISTORY
[2003-02-21, 12:47-16:18] Implemented `--item' for choosing initially
selected item. Menu item and command is now given in the same string,
separated with :, which makes for nicer error detection and lesser
errors since it is a bit easier to keep track of what does which on the
command line.
[2003-02-22, 15:38-16:43]
[2003-02-23, 02:19-02:36] Implemented `--delimiter' which now must be
used to get the "menuitem:command" (as opposed to "menuitem" "command")
behaviour. This, because I realised that when called from a script
using an on-the-fly generated menu it can be quite tedious to make sure
that the delimiter does not occur in the `menuitem' string (and thus
fuck up the menu). Of course in handwritten menus the delimiter
approach is easier to handle, hence I allow for both. Delimiter now
also may be more than one character long.
[2003-02-23, 19:08-20:30] Implemented --unfocus-exit which exits the
menu if it's window is unfocused.
[2003-02-23, 21:12-21:22]
[2003-02-24, 00:22-00:49]
[2003-02-24, 11:38-17:47] Now reads some options regulating appearance
and behaviour from X resources in addition to the command line.
[2003-02-25, 18:47-22:20] Wrote POD. At last found a really good name
for the product. The ratmen.
[2003-02-26, 01:38-09:15] Now reads command line option using getopt;
thusly supports both --long-options and short ones (and bundles of
short ones). Yay! Still haven't been able to get the --unfocus-exit to
work properly.
[2003-02-26, 13:27-14:34] Fixxed --unfocus-exit so that it now really
makes the menu die of unfocus. Unfortunately, however a `BadWindow'
message is generated by X when doing so, which looks quite ugly in
ratpoison (which faithfully reports the error). I simply haven't been
able to figure out what command is causing this, but my best guess is
that there's some unlucky X function still queued which tries to
manipulate the window after it has been closed.
[2003-03-03, 00:13-01:54] Added the --print option, which can be
extremely useful in scripts and other programs where you want to use a
menu for some kind of input, rather than for a platform from which to
fire off some program. Added "BUGS" section below. Added the --debug
option which (as of now) dumps some info on the events (key/mouse
clicks focusing etc.) intercepted from X.
[2003-03-08, 11:21-11:29] Added a declaration of the subroutine
`strcasecmp' and thus eliminating a compiler warning. Program worked
flawlessy even before (and still does) but with less annoyance for me..
=|:-) The declaration thingy was found on the 'net by googling for
"strcasetmp introduction". Made arguments to --align and --style case
insensetive.
[2003-03-08, 20:27-22:58] Found and killed a bug which made X resources
override the command line options.
[2003-03-09, 07:04-10:15] Totally fixed the bug mentioned in previous
comment. Added short options -l, -c and -r (for left, center and right
aligning of the menu text), and changed --label to --title. Also
changed the size of the menu window so that it will always be an even
number of text lines (looks pretty ogly when only half or a third of
the last item can be seen). Opening of window could be still more
optimal though (the problem still arises when X refuses to open the
window with the requested height, e.g. when one uses frames in
ratpoison).
[2003-03-10, 00:53-04:07] v2.0 - Optimized menu redrawing routine for
the non-scrolling case (used to flicker quite nastily when moving down
large menus fast). Also finally got around to add scrolling capacity
for menus too large to fit all at once. Added the related
--scroll-offset option and X resource as well.
[2003-03-10, 22:10-23:00] v2.0.1 - Begun fixxing window size bug
(interrupted by Buffy - The Vampire Slayer).
[2003-03-11, 00:31-04:25]
[2003-03-12, 00:13-01:14] v2.0.2 - Fixed weird update/redraw bug
thingy. Used to get a totally black empty menu sometimes. Bug probably
introduced in last session, and now deceased.
[2003-03-19, 10:48-12:38]
[2003-03-19, 14:17-20:18] v2.1 - Wrote better handling of X resources,
comlete with readable --debug output and all.
[2003-03-19, 22:40-09:05] v2.2 - Implemented mouse support. Made
--item=0 special. Bugfix: Now opens a window of the correct size by
telling X that it wants a window whose vertical size should be any
number of pixels evenly dividable by the font height. (Rxvt served as a
source of inspiration for this feature.) Also added keys Home/PgUp for
going to the first item in the menu and End/PgDn to go to the last.
--class now really works.
[2003-03-24, 15:41-16:32] v2.2.1 - Added options --mouse and --no-mouse
and the corresponding X resource ratmen.mouse -- mouse is enabled by
default. Removed the short options -u and -U (synonyms for
--unfocus-exit and --no-unfocus-exit) as to not encourage the useage of
those options on the command line (should be set using X resources).
[2003-03-28, 11:29-11:32] v2.2.2 - Killed bug which didn't allow spaces
to be used in font names (this little bugfix also makes it quite
necessary not to end your X resources in any extraneous spaces).
[2007-10-25, 11:23-14:13] v2.2.3 -- Bugfix. Changed a couple of latin-1
characters 173 (soft hyphens) to the minus signs the should have been
all the time. Added the "FUTURE" heading above. Rewrote the Makefile.
BUGS
o When no item is selected (i.e. on startup with -i0) and you hover
the menu with the pointer, and then remove the pointer, the first
item becomes selected.
o The snazzy mode. I'm probably going to remove it sometime in the
future. I don't use it and I don't see any reason why anybody else
should want to either... (Especially not now that we got scrollable
dreary mode..)
o Generates a `BadWindow' when dying of unfocus under the
--unfocus-exit option.
This should be curable by means of XSetErrorHandler(), at least if
it is not ratpoison causing these things.
o Memory leaks? There are probably several (me being totally new to
C) but since the execution time should never really accumulate I
haven't made it a priority to kill 'em. Please tell me if you find
any.
o When using --item=0 and --style=snazzy one must press arrow down
*twice* to select the first item on the menu. (I'll probably fix
this by removing the `snazzy' mode.)
TODO
These are the things a want to do next in approximate order of
priority:
o Parsing of standard input (so one may use ratmen as a magic number)
for interpreting menu files. If this is to work, maybe some special
command line argument parsing is needed? (I strongly suspect that
magic number arguments are not passed in the same fashion, as if
given on the command line..)
o Option for outputting number of selected menu item
(--print-number/-P maybe?).
o Change --print behaviour to include -d: or something automatically
(so that menu item text is default output).
o User-configurable keys for up/down choose etc.
o Menu shortcuts (defined in the menu) -- if autogenerated shortcuts
are good enough, this might not be needed.
o Automatically generated key shortcuts (E.g. numbers 0-9 for items
1-10, or letter 'a' letter to loop through all items begginning
with an 'a', or "/" and "?" to do incremental forward/backward
search...)
o Multiple selection mode (space=select; enter=finalize) (introduce
colors for marked entry and marked & selected entry).
o Incremental search in menu (using bottom item space for input).
o Replacing top/bottom item with arrow (or something) if scrollable
in that direction.
Zrajm C Akfohg 2015-12-24 ratmen(1)
