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 beginning 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] /usr/share/doc/wmii/examples