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