mirror of
https://github.com/0intro/wmii
synced 2024-11-24 22:59:45 +03:00
234 lines
6.3 KiB
Plaintext
234 lines
6.3 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.
|
||
: -r <rows>
|
||
Display completion items as a vertical list, one per
|
||
row, rather than a horizontal list, side-by-side. A
|
||
maximum of <rows> rows will be displayed.
|
||
:
|
||
|
||
= 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.
|
||
|
||
= KEY BINDINGS =
|
||
|
||
`wimenu`'s default key bindings are based largely on the
|
||
movement keys of vi and the standard UNIX shell input bindings.
|
||
|
||
: Return, C-j, C-m
|
||
Accept the input, and select the first matching
|
||
completion if the cursor is at the end of the input.
|
||
: S-Return, C-S-j, C-S-m
|
||
Accept the input literally.
|
||
: Esc, C-[
|
||
Quit without returning any output, and exit with
|
||
non-zero status.
|
||
|
||
: A-p
|
||
Paste the PRIMARY selection.
|
||
|
||
: Left, C-b
|
||
Move backward one character.
|
||
: Right, C-f
|
||
Move forward one character.
|
||
|
||
: A-b
|
||
Move backward one word.
|
||
: A-f
|
||
Move forward one word.
|
||
|
||
: C-a
|
||
Move to the begining of the line.
|
||
: C-e
|
||
Move to the end of the line.
|
||
|
||
: C-p, Up
|
||
Move backward through the input history.
|
||
: C-n, Down
|
||
Move forward through the input history.
|
||
|
||
: Backspace, C-h
|
||
Delete the previous character.
|
||
: C-Backspace, C-w
|
||
Delete the previous word.
|
||
: C-u
|
||
Delete the previous portion of the line.
|
||
|
||
: Tab, C-i¸ A-l
|
||
Select the next completion.
|
||
: S-Tab, C-S-i, A-h
|
||
Select the previous completion.
|
||
: PageUp, A-k
|
||
Select the previous completion page.
|
||
: PageDown, A-j
|
||
Select the next completion page.
|
||
: Home, A-g
|
||
Select the first completion page.
|
||
: End, A-S-g
|
||
Select the last completion page.
|
||
:
|
||
= 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)
|
||
}
|
||
|
||
{ 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[$1]) # The second arg, command arguments
|
||
# Skip the trailing part of the command
|
||
getline rest
|
||
}
|
||
' | tail -1
|
||
```
|
||
|
||
In theory, this facility can be used for myriad purposes,
|
||
including hijacking the programmable completion facilities of
|
||
most shells. See also the provided examples[1].
|
||
|
||
= 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), wistrug(1), wmii9menu(1), dmenu(1)
|
||
|
||
[1] http://www.suckless.org/wiki/wmii/tips/9p_tips +
|
||
[2] @EXAMPLES@
|