mirror of https://github.com/0intro/wmii
298 lines
6.4 KiB
Groff
298 lines
6.4 KiB
Groff
.TH "WIMENU" 1 "Oct, 2009" "wmii-@VERSION@"
|
||
|
||
|
||
.SH NAME
|
||
|
||
.P
|
||
wimenu \- The wmii menu program
|
||
|
||
.SH SYNOPSIS
|
||
|
||
.P
|
||
wimenu [\fI\-i\fR] [\fI\-h \fI<history file>\fR\fR] [\fI\-n \fI<history count>\fR\fR] [\fI\-p \fI<prompt>\fR\fR]
|
||
.P
|
||
wimenu \-v
|
||
|
||
.SH DESCRIPTION
|
||
|
||
.P
|
||
\fBwimenu\fR is \fBwmii\fR's standard menu program. It's used
|
||
extensively by \fBwmii\fR and related programs to prompt the user
|
||
for input. The standard configuration uses it to launch
|
||
programs, select views, and perform standard actions. It
|
||
supports basic item completion and history searching.
|
||
|
||
.SH BASIC ARGUMENTS
|
||
|
||
.P
|
||
Normal use of \fBwimenu\fR shouldn't require any arguments other than the
|
||
following. More advanced options are documented below.
|
||
|
||
.TP
|
||
\-h \fI<history file>\fR
|
||
Causes \fBwimenu\fR to read its command history from
|
||
\fI<history file>\fR and to append its result to that file if
|
||
\fI\-n\fR is given.
|
||
.TP
|
||
\-i
|
||
Causes matching of completion items to be performed in a
|
||
case insensitive manner.
|
||
.TP
|
||
\-n \fI<count>\fR
|
||
Write at most \fI<count>\fR items back to the history file.
|
||
The file is never modified unless this option is
|
||
provided. Duplicates are filtered out within a 20 item
|
||
sliding window before this limit is imposed.
|
||
.TP
|
||
\-p \fI<prompt>\fR
|
||
The string \fI<prompt>\fR will be show before the input field
|
||
when the menu is opened.
|
||
.TP
|
||
\-r \fI<rows>\fR
|
||
Display completion items as a vertical list, one per
|
||
row, rather than a horizontal list, side\-by\-side. A
|
||
maximum of \fI<rows>\fR rows will be displayed.
|
||
|
||
.SH ADVANCED ARGUMENTS
|
||
|
||
.TP
|
||
\-a
|
||
The address at which to connect to \fBwmii\fR.
|
||
.TP
|
||
\-K
|
||
Prevents \fBwimenu\fR from initializing its default key
|
||
bindings. WARNING: If you do this, be sure to bind a key
|
||
with the Accept or Reject action, or you will have no way
|
||
to exit \fBwimenu\fR.
|
||
.TP
|
||
\-k \fI<key file>\fR
|
||
Key bindings will be read from \fI<key file>\fR. Bindings
|
||
appear as:
|
||
|
||
\fI<key>\fR [\fIaction\fR] [\fIargs\fR]
|
||
|
||
where \fI<key>\fR is a key name, similar to the format used by
|
||
wmii. For action and args, please refer to the default
|
||
bindings, provided in the source distribution under
|
||
cmd/menu/keys.txt, or use strings(1) on the \fBwimenu\fR
|
||
executable (this level of customization is reserved for the
|
||
determined).
|
||
.TP
|
||
\-s \fI<screen>\fR
|
||
Suggests that the menu open on Xinerama screen \fI<screen>\fR.
|
||
.TP
|
||
\-S \fI<command separator>\fR
|
||
|
||
.RS
|
||
Causes each input item to be split at the first occurance of
|
||
\fI<command sep>\fR. The text to the left of the separator is displayed
|
||
as a menu option, and the text to the right is displayed when a
|
||
selection is made.
|
||
.RE
|
||
|
||
.SH KEY BINDINGS
|
||
|
||
.P
|
||
\fBwimenu\fR's default key bindings are based largely on the
|
||
movement keys of vi and the standard UNIX shell input bindings.
|
||
|
||
.TP
|
||
Return, C\-j, C\-m
|
||
Accept the input, and select the first matching
|
||
completion if the cursor is at the end of the input.
|
||
.TP
|
||
S\-Return, C\-S\-j, C\-S\-m
|
||
Accept the input literally.
|
||
.TP
|
||
Esc, C\-[
|
||
Quit without returning any output, and exit with
|
||
non\-zero status.
|
||
|
||
.TP
|
||
A\-p
|
||
Paste the PRIMARY selection.
|
||
|
||
.TP
|
||
Left, C\-b
|
||
Move backward one character.
|
||
.TP
|
||
Right, C\-f
|
||
Move forward one character.
|
||
|
||
.TP
|
||
A\-b
|
||
Move backward one word.
|
||
.TP
|
||
A\-f
|
||
Move forward one word.
|
||
|
||
.TP
|
||
C\-a
|
||
Move to the beginning of the line.
|
||
.TP
|
||
C\-e
|
||
Move to the end of the line.
|
||
|
||
.TP
|
||
C\-p, Up
|
||
Move backward through the input history.
|
||
.TP
|
||
C\-n, Down
|
||
Move forward through the input history.
|
||
|
||
.TP
|
||
Backspace, C\-h
|
||
Delete the previous character.
|
||
.TP
|
||
C\-Backspace, C\-w
|
||
Delete the previous word.
|
||
.TP
|
||
C\-u
|
||
Delete the previous portion of the line.
|
||
|
||
.TP
|
||
Tab, C\-i¸ A\-l
|
||
Select the next completion.
|
||
.TP
|
||
S\-Tab, C\-S\-i, A\-h
|
||
Select the previous completion.
|
||
.TP
|
||
PageUp, A\-k
|
||
Select the previous completion page.
|
||
.TP
|
||
PageDown, A\-j
|
||
Select the next completion page.
|
||
.TP
|
||
Home, A\-g
|
||
Select the first completion page.
|
||
.TP
|
||
End, A\-S\-g
|
||
Select the last completion page.
|
||
|
||
.SH CUSTOM COMPLETION
|
||
|
||
.P
|
||
Custom, multipart completion data may be proveded by an
|
||
external application. When the standard input is not a TTY,
|
||
processing of a set of completions stops at every blank line.
|
||
After the first new line or EOF, \fBwimenu\fR displays the first
|
||
set of menu items, and waits for further input. The completion
|
||
items may be replaced by writing out a new set, again followed
|
||
by a new line. Every set following the first must begin with a
|
||
line containing a single decimal number specifying where the
|
||
new completion results are to be spliced into the input. When
|
||
an item is selected, text from this position to the position
|
||
of the caret is replaced.
|
||
|
||
.SS ARGUMENTS
|
||
|
||
.TP
|
||
\-c
|
||
Prints the contents of the input buffer each time the
|
||
user inputs a character, as such:
|
||
|
||
\fI<text before caret>\fR\en\fI<text after caret>\fR\en
|
||
|
||
.SS EXAMPLE
|
||
|
||
.P
|
||
Let's assume that a script would like to provide a menu with
|
||
completions first for a command name, then for arguments
|
||
to that command. Given three commands and argument sets,
|
||
|
||
.TP
|
||
foo
|
||
|
||
.RS
|
||
1, 2, 3
|
||
.RE
|
||
|
||
.TP
|
||
bar
|
||
|
||
.RS
|
||
4, 5, 6
|
||
.RE
|
||
|
||
.TP
|
||
baz
|
||
|
||
.RS
|
||
7, 8, 9
|
||
.RE
|
||
|
||
.P
|
||
the following script provides the appropriate completions:
|
||
|
||
.nf
|
||
#!/bin/sh -f
|
||
|
||
rm fifo
|
||
mkfifo fifo
|
||
|
||
# Open wimenu with a fifo as its stdin
|
||
wimenu -c <fifo | awk '
|
||
BEGIN {
|
||
# Define the completion results
|
||
cmds = "foo\enbar\enbaz\en"
|
||
cmd[\fI"foo"\fR] = "1\en2\en3\en"
|
||
cmd[\fI"bar"\fR] = "4\en5\en6\en"
|
||
cmd[\fI"baz"\fR] = "7\en8\en9\en"
|
||
|
||
# Print the first set of completions to wimenu’s fifo
|
||
fifo = "fifo"
|
||
print cmds >fifo; fflush(fifo)
|
||
}
|
||
|
||
{ print; fflush() }
|
||
|
||
# Push out a new set of completions
|
||
function update(str, opts) {
|
||
print length(str) >fifo # Print the length of the preceding string
|
||
print opts >fifo # and the options themself
|
||
fflush(fifo)
|
||
}
|
||
|
||
# Ensure correct argument count with trailing spaces
|
||
/ $/ { $0 = $0 "#"; }
|
||
|
||
{ # Process the input and provide the completions
|
||
if (NF == 1)
|
||
update("", cmds) # The first arg, command choices
|
||
else
|
||
update($1 " ", cmd[\fI$1\fR]) # The second arg, command arguments
|
||
# Skip the trailing part of the command
|
||
getline rest
|
||
}
|
||
\&' | tail -1
|
||
.fi
|
||
|
||
|
||
.P
|
||
In theory, this facility can be used for myriad purposes,
|
||
including hijacking the programmable completion facilities of
|
||
most shells. See also the provided examples[\fI1\fR].
|
||
|
||
.SH ENVIRONMENT
|
||
|
||
.TP
|
||
\fB$WMII_ADDRESS\fR
|
||
The address at which to connect to wmii.
|
||
.TP
|
||
\fB$NAMESPACE\fR
|
||
The namespace directory to use if no address is
|
||
provided.
|
||
|
||
.SH SEE ALSO
|
||
|
||
.P
|
||
wmii(1), wmiir(1), wistrug(1), wmii9menu(1), dmenu(1)
|
||
|
||
.P
|
||
[\fI1\fR] http://www.suckless.org/wiki/wmii/tips/9p_tips
|
||
.P
|
||
[\fI2\fR] @EXAMPLES@
|
||
|
||
.\" man code generated by txt2tags 2.6 (http://txt2tags.org)
|
||
.\" cmdline: txt2tags -o- wimenu.man1
|