mirror of https://github.com/0intro/wmii
205 lines
5.1 KiB
Groff
205 lines
5.1 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.
|
||
|
||
|
||
.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 \fI[action]\fR \fI[args]\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 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)
|
||
}
|
||
|
||
# Store the last line we get and print it when done
|
||
{ last = $0 }
|
||
END { print last }
|
||
|
||
# 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
|
||
}
|
||
\&'
|
||
.fi
|
||
|
||
|
||
.P
|
||
In theory, this facility can be used for myriad purposes,
|
||
including hijacking the programmable completion facilities of
|
||
most shells.
|
||
|
||
.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
|
||
\fI[1]\fR http://www.suckless.org/wiki/wmii/tips/9p_tips
|
||
|
||
|
||
.\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net)
|
||
.\" cmdline: txt2tags -o- wimenu.man1
|
||
|