mirror of
https://github.com/0intro/wmii
synced 2024-11-25 07:09:38 +03:00
175 lines
4.8 KiB
Plaintext
175 lines
4.8 KiB
Plaintext
WIMENU
|
||
wmii-@VERSION@
|
||
Oct, 2009
|
||
|
||
%!includeconf: header.t2t
|
||
|
||
= NAME =
|
||
|
||
wimenu - The wmii menu program
|
||
|
||
= SYNOPSIS =
|
||
|
||
wimenu [-i] [-h <history file>] [-n <history count>] [-p <prompt>] +
|
||
wimenu -v
|
||
|
||
= DESCRIPTION =
|
||
|
||
`wimenu` is `wmii`'s standard menu program. It's used
|
||
extensively by `wmii` 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.
|
||
|
||
= BASIC ARGUMENTS =
|
||
|
||
Normal use of `wimenu` shouldn't require any arguments other than the
|
||
following. More advanced options are documented below.
|
||
|
||
: -h <history file>
|
||
Causes `wimenu` to read its command history from
|
||
<history file> and to append its result to that file if
|
||
_-n_ is given.
|
||
: -i
|
||
Causes matching of completion items to be performed in a
|
||
case insensitive manner.
|
||
: -n <count>
|
||
Write at most <count> 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.
|
||
: -p <prompt>
|
||
The string <prompt> will be show before the input field
|
||
when the menu is opened.
|
||
:
|
||
|
||
= ADVANCED ARGUMENTS =
|
||
|
||
: -a
|
||
The address at which to connect to `wmii`.
|
||
: -K
|
||
Prevents `wimenu` 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 `wimenu`.
|
||
: -k <key file>
|
||
Key bindings will be read from <key file>. Bindings
|
||
appear as:
|
||
|
||
<key> [action] [args]
|
||
|
||
where <key> 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 `wimenu`
|
||
executable (this level of customization is reserved for the
|
||
determined).
|
||
: -s <screen>
|
||
Suggests that the menu open on Xinerama screen <screen>.
|
||
: -S <command separator>
|
||
Causes each input item to be split at the first occurance of
|
||
<command sep>. 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.
|
||
|
||
= CUSTOM COMPLETION =
|
||
|
||
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, `wimenu` 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.
|
||
|
||
== ARGUMENTS ==
|
||
|
||
: -c
|
||
Prints the contents of the input buffer each time the
|
||
user inputs a character, as such:
|
||
|
||
<text before caret>\n<text after caret>\n
|
||
:
|
||
|
||
== EXAMPLE ==
|
||
|
||
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,
|
||
|
||
: foo
|
||
1, 2, 3
|
||
: bar
|
||
4, 5, 6
|
||
: baz
|
||
7, 8, 9
|
||
|
||
the following script provides the appropriate completions:
|
||
|
||
```
|
||
#!/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\nbar\nbaz\n"
|
||
cmd["foo"] = "1\n2\n3\n"
|
||
cmd["bar"] = "4\n5\n6\n"
|
||
cmd["baz"] = "7\n8\n9\n"
|
||
|
||
# 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[$1]) # The second arg, command arguments
|
||
# Skip the trailing part of the command
|
||
getline rest
|
||
}
|
||
'
|
||
```
|
||
|
||
In theory, this facility can be used for myriad purposes,
|
||
including hijacking the programmable completion facilities of
|
||
most shells.
|
||
|
||
= ENVIRONMENT =
|
||
|
||
: $WMII_ADDRESS
|
||
The address at which to connect to wmii.
|
||
: $NAMESPACE
|
||
The namespace directory to use if no address is
|
||
provided.
|
||
:
|
||
= SEE ALSO =
|
||
wmii(1), wmiir(1), wmii9menu(1), dmenu(1)
|
||
|
||
[1] http://www.suckless.org/wiki/wmii/tips/9p_tips
|
||
|