wimenu.man1 (6492B)
1 WIMENU 2 wmii-@VERSION@ 3 Oct, 2009 4 5 %!includeconf: header.t2t 6 7 = NAME = 8 9 wimenu - The wmii menu program 10 11 = SYNOPSIS = 12 13 wimenu [-i] [-h <history file>] [-n <history count>] [-p <prompt>] + 14 wimenu -v 15 16 = DESCRIPTION = 17 18 `wimenu` is `wmii`'s standard menu program. It's used 19 extensively by `wmii` and related programs to prompt the user 20 for input. The standard configuration uses it to launch 21 programs, select views, and perform standard actions. It 22 supports basic item completion and history searching. 23 24 = BASIC ARGUMENTS = 25 26 Normal use of `wimenu` shouldn't require any arguments other than the 27 following. More advanced options are documented below. 28 29 : -h <history file> 30 Causes `wimenu` to read its command history from 31 <history file> and to append its result to that file if 32 _-n_ is given. 33 : -i 34 Causes matching of completion items to be performed in a 35 case insensitive manner. 36 : -n <count> 37 Write at most <count> items back to the history file. 38 The file is never modified unless this option is 39 provided. Duplicates are filtered out within a 20 item 40 sliding window before this limit is imposed. 41 : -p <prompt> 42 The string <prompt> will be show before the input field 43 when the menu is opened. 44 : -r <rows> 45 Display completion items as a vertical list, one per 46 row, rather than a horizontal list, side-by-side. A 47 maximum of <rows> rows will be displayed. 48 : 49 50 = ADVANCED ARGUMENTS = 51 52 : -a 53 The address at which to connect to `wmii`. 54 : -K 55 Prevents `wimenu` from initializing its default key 56 bindings. WARNING: If you do this, be sure to bind a key 57 with the Accept or Reject action, or you will have no way 58 to exit `wimenu`. 59 : -k <key file> 60 Key bindings will be read from <key file>. Bindings 61 appear as: 62 63 <key> [action] [args] 64 65 where <key> is a key name, similar to the format used by 66 wmii. For action and args, please refer to the default 67 bindings, provided in the source distribution under 68 cmd/menu/keys.txt, or use strings(1) on the `wimenu` 69 executable (this level of customization is reserved for the 70 determined). 71 : -s <screen> 72 Suggests that the menu open on Xinerama screen <screen>. 73 : -S <command separator> 74 Causes each input item to be split at the first occurance of 75 <command sep>. The text to the left of the separator is displayed 76 as a menu option, and the text to the right is displayed when a 77 selection is made. 78 79 = KEY BINDINGS = 80 81 `wimenu`'s default key bindings are based largely on the 82 movement keys of vi and the standard UNIX shell input bindings. 83 84 : Return, C-j, C-m 85 Accept the input, and select the first matching 86 completion if the cursor is at the end of the input. 87 : S-Return, C-S-j, C-S-m 88 Accept the input literally. 89 : Esc, C-[ 90 Quit without returning any output, and exit with 91 non-zero status. 92 93 : A-p 94 Paste the PRIMARY selection. 95 96 : Left, C-b 97 Move backward one character. 98 : Right, C-f 99 Move forward one character. 100 101 : A-b 102 Move backward one word. 103 : A-f 104 Move forward one word. 105 106 : C-a 107 Move to the begining of the line. 108 : C-e 109 Move to the end of the line. 110 111 : C-p, Up 112 Move backward through the input history. 113 : C-n, Down 114 Move forward through the input history. 115 116 : Backspace, C-h 117 Delete the previous character. 118 : C-Backspace, C-w 119 Delete the previous word. 120 : C-u 121 Delete the previous portion of the line. 122 123 : Tab, C-i¸ A-l 124 Select the next completion. 125 : S-Tab, C-S-i, A-h 126 Select the previous completion. 127 : PageUp, A-k 128 Select the previous completion page. 129 : PageDown, A-j 130 Select the next completion page. 131 : Home, A-g 132 Select the first completion page. 133 : End, A-S-g 134 Select the last completion page. 135 : 136 = CUSTOM COMPLETION = 137 138 Custom, multipart completion data may be proveded by an 139 external application. When the standard input is not a TTY, 140 processing of a set of completions stops at every blank line. 141 After the first new line or EOF, `wimenu` displays the first 142 set of menu items, and waits for further input. The completion 143 items may be replaced by writing out a new set, again followed 144 by a new line. Every set following the first must begin with a 145 line containing a single decimal number specifying where the 146 new completion results are to be spliced into the input. When 147 an item is selected, text from this position to the position 148 of the caret is replaced. 149 150 == ARGUMENTS == 151 152 : -c 153 Prints the contents of the input buffer each time the 154 user inputs a character, as such: 155 156 <text before caret>\n<text after caret>\n 157 : 158 159 == EXAMPLE == 160 161 Let's assume that a script would like to provide a menu with 162 completions first for a command name, then for arguments 163 to that command. Given three commands and argument sets, 164 165 : foo 166 1, 2, 3 167 : bar 168 4, 5, 6 169 : baz 170 7, 8, 9 171 172 the following script provides the appropriate completions: 173 174 ``` 175 #!/bin/sh -f 176 177 rm fifo 178 mkfifo fifo 179 180 # Open wimenu with a fifo as its stdin 181 wimenu -c <fifo | awk ' 182 BEGIN { 183 # Define the completion results 184 cmds = "foo\nbar\nbaz\n" 185 cmd["foo"] = "1\n2\n3\n" 186 cmd["bar"] = "4\n5\n6\n" 187 cmd["baz"] = "7\n8\n9\n" 188 189 # Print the first set of completions to wimenu’s fifo 190 fifo = "fifo" 191 print cmds >fifo; fflush(fifo) 192 } 193 194 { print; fflush() } 195 196 # Push out a new set of completions 197 function update(str, opts) { 198 print length(str) >fifo # Print the length of the preceding string 199 print opts >fifo # and the options themself 200 fflush(fifo) 201 } 202 203 # Ensure correct argument count with trailing spaces 204 / $/ { $0 = $0 "#"; } 205 206 { # Process the input and provide the completions 207 if (NF == 1) 208 update("", cmds) # The first arg, command choices 209 else 210 update($1 " ", cmd[$1]) # The second arg, command arguments 211 # Skip the trailing part of the command 212 getline rest 213 } 214 ' | tail -1 215 ``` 216 217 In theory, this facility can be used for myriad purposes, 218 including hijacking the programmable completion facilities of 219 most shells. See also the provided examples[1]. 220 221 = ENVIRONMENT = 222 223 : $WMII_ADDRESS 224 The address at which to connect to wmii. 225 : $NAMESPACE 226 The namespace directory to use if no address is 227 provided. 228 : 229 = SEE ALSO = 230 wmii(1), wmiir(1), wistrug(1), wmii9menu(1), dmenu(1) 231 232 [1] http://www.suckless.org/wiki/wmii/tips/9p_tips + 233 [2] @EXAMPLES@