NAME

SYNOPSIS

ratmen [OPTION]... {-d##|--delimiter ##} MENUITEM##COMMAND ...

DESCRIPTION

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

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

    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

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

    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

AUTHORS

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

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.