gsmenu-3.0: gsmenu.1

.TH GSMENU 1 gsmenu\-4.0
.SH NAME
gsmenu \- grid menu
.SH SYNOPSIS
.nh
gsmenu
[Sindre options...]
.SH DESCRIPTION
.SS Overview
gsmenu is a generic grid menu for X11, originally a port of the
GridSelect contrib for XMonad.  Now it is a program built on
Sindre. It displays elements as a grid of rectangular cells.  gsmenu
always uses the display indicated in the DISPLAY environment variable.
.SS Options
No options are accepted apart from those provided by
.IR sindre (1).
.SH USAGE
gsmenu reads a list of newline-separated elements from standard input
and presents them in a grid.  Each element has a foreground and a
background colour, as well as a name (what will be visible on the
screen) and a list of tags that are used only for filtering.
.SS INPUT FORMAT
The standard Sindre key-value format is used.  Each line takes the
form of key-value pairs, with the key being a sequence of
alphanumerics, followed by an equals sign, followed by a value in
double quotes (double-quotes can be embedded by doubling
them).  For example, an element might be

.nf
name="foo" bg="red"
.fi

And a list-value can be given by simply writing more double-quoted
strings (this also showcases double quote-escaping):

.nf
name="quote ""this"" please" tags="bar" "baz" bg="red"
.fi

The following keys are defined:
.TP
.B name
The string that will be displayed in the grid.  The value can also be
a list, in which case each part of the list will be printed as a line
by itself (note that there will probably not be room for more than two
lines).  Also, only the first line will count as the "name" as far as
selection output is concerned.
.TP
.B fg
The foreground (text) colour of the element (#RGB, #RRGGBB, and color
names are supported).
.TP
.B bg
The background colour of the element (#RGB, #RRGGBB, and color
names are supported).
.TP
.B tags
A list of tags of the element, used when filtering.
.TP
.B value
Instead of the name, print the value of this key when the element is
selected.  If a list, a newline is printed after every element but the
last.
.SS INTERACTION
When the user moves focus to an element and presses Return, that
element is selected and is printed to standard output and gsmenu
terminates.  Elements can also be selected by clicking on them with
the mouse.  Additionally, the following keyboard commands are
recognised:
.TP
.B Any printable character
Appends the character to the text in the input field.  This works as a filter:
only items containing this text (possibly in a tag) will be displayed.
.TP
.B Backspace
Remove the last character in the input field, or if empty, open the
topmost filter for editing.
.TP
.B Left/Right/Up/Down (CTRL\-b/CTRL-f/CTRL\-p/CTRL\-n)
Move focus in the grid.
.TP
.B CTRL\-a
Set focus to the leftmost element in the row.
.TP
.B CTRL\-e
Set focus to the rightmost element in the row.
.TP
.B CTRL\-s
Focus on the next element following a spiral path from the center.
.TP
.B CTRL\-r
Focus on the previous element following a spiral path from the center.
.TP
.B CTRL\-w
Remove the topmost filter, if any.
.TP
.B Escape, CTRL\-c, CTRL\-g
Cancel selection and exit gsmenu.
.SH EXIT STATUS
gsmenu returns a
.B 0
exit status on success,
.B 1
if there was an internal problem, and
.B 2
if the user cancelled.
.SH SEE ALSO
.IR sindre (1),
.IR dmenu (1),
.IR xmonad (1)