File: nawm.1

package info (click to toggle)
nawm 0.0.20030130-2
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 360 kB
  • ctags: 496
  • sloc: ansic: 3,158; sh: 1,582; yacc: 408; lex: 406; makefile: 153
file content (448 lines) | stat: -rw-r--r-- 14,696 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
.TH nawm 1
.SH NAME
nawm \- I can't believe it's not a window manager!
.SH SYNOPSIS
\fBnawm\fP [-e \fIcommands\fP] [-f \fIinitfile\fP]
.SH DESCRIPTION
\fBnawm\fP is not a window manager. Or at least, it used to not be a
window manager. It's working its way there though.
.SH OPTIONS
\fBnawm\fP accepts a handful of command-line options:
.PP
.RS
.TP 3
.B \-e \fIcommands\fP
The commands are one or more semicolon-terminated nawm commands to
execute.
.TP
.B \-f \fIinitfile\fP
Read commands and bindings from the named file (or standard input if
\fIinitfile\fP is \fI-\fP).
.TP
.B \-i \fImodule\fP
Load the named module. For more information about available nawm
modules, see the
.BR nawmmod (3)
man page. Modules can also be loaded using the
.B include
directive within a config file.
.TP
.B \-o \fIoption\fP
Set an option. The only currently supported option is
.B nocapslock\fP,
which tells nawm to ignore the state of the Caps Lock key in key and
mouse bindings. Options can also be set using the
.B option
directive within a config file.
.TP
.B \-w \fIwindowmanager\fP
Tells nawm what window manager you are using. Any string is accepted,
but only two values currently cause non-default behavior:
.PP
.RS 7
.TP
.B nawm
Tells \fBnawm\fP that you aren't using any other window manager, so it
should not try to look for and ignore window manager decorations
(titlebars, etc).
.TP
.B vtwm.gamma
Tells \fBnawm\fP that you're using vtwm.gamma, so that nawm can
compensate for a bug in vtwm.gamma's window moving and resizing code.
.RE
.PP
.RS 3
If no \fB-w\fP option is given, \fBnawm\fP will look at the final
pathname component of the \fBWINDOW_MANAGER\fP environment variable.
.RE
.PP
If no options are specified, \fBnawm\fP will read commands and
bindings from \fB$HOME/.nawmrc\fP. \fBnawm\fP has no default settings.
You must give it a configuration either on the command line or in
a \fB.nawmrc\fP file.
.PP
If one or more \fB-e\fP options are specified and no \fB-f\fP options
are (or if the configuration file(s) don't specify any bindings) then
\fBnawm\fP will exit after executing the given commands.
.SH CONFIGURATION
A \fB.nawmrc\fP is a series of declarations of the following types:
.PP
.TP 8
\fBinclude\fP "\fImodule\fP";
Loads the named module, as with the
.B \-i
command-line option.
.TP 8
\fBoption\fP "\fIoption\fP";
Sets the named option, as with the
.B \-o
command-line option.
.TP 8
\fIvartype name\fP [\fB,\fP \fIname\fP ...]\fB;\fP
Declares global variables. (See below for more information about
data types.)
.TP 8
\fIbindtype\fP [\fIdata\fP] \fB{\fP \fIvardecls commands\fP \fB}\fP
Declares a global binding. (See below for more information about
bindings.)
.TP 8
\fBcommand\fP \fIname\fP [ \fIarg\fP [\fB,\fP \fIarg\fP ...]] \fB{\fP \fIvardecls commands\fP \fB}\fP
Declares a global command. If you declare arguments to the function,
you must include variable declarations for those arguments in the
function body (in order, as the first variable declarations in the
body) so that nawm knows their types. The declaration of the command
is visible within the function itself, allowing recursive calls.
.TP 8
\fBfunction\fP \fItype name\fP \fB(\fP [ \fIarg\fP [\fB,\fP \fIarg\fP ...]] \fB) {\fP \fIvardecls commands\fP \fB}\fP
Declares a global function.
.TP 8
.B mode "\fIname\fP" { \fIbindings\fP }
Declares a mode, which can have local (static) variables, bindings,
commands, and functions (declared as with global ones above). You can
switch modes with the \fBsetmode\fP command.
.PP
.SH TYPES
There are three primitive data types in nawm: \fBint\fP, \fBstring\fP,
and \fBwindow\fP, which represent the obvious kinds of data.
.PP
\fBstring\fP values are implicitly converted to \fBwindow\fP values
when necessary. (For example, the string \fB"Emacs"\fP will be
converted to a \fBwindow\fP value corresponding to a window named
"Emacs" if one exists.) Note also that an initial \fBwindow\fP
argument to a command or function can be omitted, and the `current
window' will be substituted in. (The current window defaults to the
window that the pointer is in when a binding is invoked.)
.PP
nawm also has arrays, which can be indexed by any primitive type.
(e.g., "int[string] foo" declares foo to be an array of integers,
indexed by strings. You could then say things like
.PP
.RS
foo["Monday"] = 7;
.RE
.PP
whatever that means. Multiple subscripts work as in C:
string[int][int][int], for example. Arrays are dynamically sized.
Looking up the value of an array element that you haven't set is
undefined. You can unset an array element with the \fBdel\fP special
form. (Not to be confused with the \fBdelete\fP command, which sends
delete messages to windows.)
.PP
You can find out the number of elements currently in an array with the
expression \fIarrayname\fP.\fBsize\fP.
.PP
Arrays and strings that become inaccessible are garbage collected.
.SH BINDINGS
There are several types of event bindings.
.TP 8
.B begin { \fIcommands\fP }
The commands will be executed when you enter the mode the binding
appears in. If multiple \fBbegin\fP declarations appear, they will be
executed in order. A global \fBbegin\fP binding will be executed at
startup time after all command-line arguments are parsed but before
the main loop is entered.
.TP 8
.B end { \fIcommands\fP }
The commands will be executed when leave the mode the binding appears
in. A global \fBend\fP binding will be executed immediately before
nawm exits normally.
.TP 8
\fBkey\fP[\fBpress | release\fP] \fIkeyname\fP
Runs the associated commands when it gets a KeyPress or KeyRelease
event for the named key with the given modifiers. \fBkey\fP is an
alias for \fBkeypress\fP. \fIkeyname\fP is a string, containing the X
keysym name for the key, possibly preceded by one or more of the
modifiers \fBshift\fP, \fBcontrol\fP, \fBmeta\fP, \fBalt\fP,
\fBsuper\fP, \fBhyper\fP, \fBmod\fP\fIn\fP for \fIn\fP from
\fB1\fP-\fB5\fP, or \fBany\fP. \fIkeyname\fP can also have multiple
vertical-bar-separated keysym names so you can have similar bindings
on slightly different keyboards. (For example, binding something to
"KP_F2 | KP_Divide".)
.TP 8
\fBmouse\fP[\fBpress | release\fP] \fIbuttonname\fP
As with \fBkey\fP bindings, but for ButtonPress events. \fIbuttonname\fP
is a string which can contain a name (\fBleft\fP, \fBmiddle\fP, or
\fBright\fP) or a number, and can be preceded by modifiers as with
\fBkey\fP bindings.
.TP 8
\fBmotion\fP
.br
Runs the associated commands whenever it gets a MotionNotify event
(ie, the mouse is moved).
.TP 8
\fBenter\fP [\fIname\fP]
Runs the associated commands whenever the pointer enters the named
window. If no name is given, the binding is run whenever the pointer
enters any window.
.TP 8
\fBleave\fP [\fIname\fP]
As with \fBenter\fP, but when the pointer leaves a window.
.SH LANGUAGE
The .nawmrc configuration language is somewhat, but not entirely,
unlike awk.
.PP
.nf
\fIcommand\fP [ \fIexpr\fP [\fB,\fP \fIexpr...\fP] ] \fB;\fP
\fBif (\fP \fIexpr\fP \fB)\fP \fIcommand\fP [ \fBelse\fP \fIcommand\fP ]
.B
for ( \fIexpr\fP ; \fIexpr\fP ; \fIexpr\fP ) \fIcommand\fP
.B
for ( \fIvar\fP in \fIarrayexpr\fP ) \fIcommand\fP
.B
while ( \fIexpr\fP ) \fIcommand\fP
.B
do \fIcommand\fP while ( \fIexpr\fP ) ;
.B
break ;
.B
continue ;
.B
del \fIarray\fP [ \fIsubscript\fP ]
.B
{ \fIcommands\fP }
.B
.fi
\fIexpr\fP ;
.SH EXPRESSIONS
The following operators all do basically what you'd expect.
.br
.B
= && || < <= > >= == != + - * / % ! in
.PP
.B +
is both addition and string concatenation. Equality and relational
operators can be used on objects of any type. (A window is "greater
than" the windows it is above on the screen.). \fBin\fP tests if an
element is in an array. Parentheses can be used to change precedence.
.PP
Minimal expressions are numbers, strings (which are converted to
\fBwindow\fPs in some contexts), variables, and function calls.
.SH BUILTINS
Built-in commands:
.TP 8
.B beep
.br
beep!
.TP 8
.B cut \fIstring\fP
copy the string to the X cut buffer. (Not yet implemented.)
.TP 8
.B delete \fIwindow\fP
send a WM_DELETE message to the indicated window.
.TP 8
.B destroy \fIwindow\fP
send a WM_DESTROY message to the indicated window.
.TP 8
.B dsize \fIwindow\fP, \fIdwidth\fP, \fIdheight\fP
discretely resize the window by the given deltas.
.TP 8
.B dsizeto \fIwindow\fP, \fIwidth\fP, \fIheight\fP
discretely resize the window to the given width and height. For
example, \fBdsizeto "xterm", 132, 48\fP would resize an xterm to 132
columns by 48 rows, as opposed to \fBsizeto "xterm", 132, 48\fP, which
would size it to 132 by 48 pixels.
.TP 8
.B exec \fIstring\fP
parse and execute the given string of nawmrc commands. This can be
used to add modes and bindings as well. (Not yet implemented.)
.TP 8
.B exit
.br
exit nawm (after running the global \fBend\fP binding, if any).
.TP 8
.B find \fIwindow\fP
set \fIwindow\fP to be the current window. (This is equivalent to
\fBcurrentwindow = \fIwindow\fP\fP).
.TP 8
.B grab
.br
grabs the X server. Prevents other programs from interfering with nawm.
You probably want to call \fBungrab\fP not too long after calling
this.
.TP 8
.B lower \fIwindow\fP
lowers the window to the bottom of the stack
.TP 8
.B map \fIwindow\fP
maps the window
.TP 8
.B mouseclick \fIbutton\fP, \fIx\fP, \fIy\fP
clicks the indicated mouse button (given as a string, as with
\fBbutton\fP event bindings) at the given x and y coordinates.
(Negative coordinates measure from the right or bottom of the screen.)
\fIbutton\fP can include modifiers, in which case those modifier keys
will be held down while nawm is clicking.
.TP 8
.B move \fIwindow\fP, \fIdx\fP, \fIdy\fP
moves the window by the given deltas
.TP 8
.B moveto \fIwindow\fP, \fIx\fP, \fIy\fP
moves the window to the specified absolute position on the screen.
\fIx\fP and \fIy\fP are treated like coordinates in X geometries:
negative values measure from the right or bottom of the screen.
.TP 8
.B put \fIstring\fP
writes the string to stdout
.TP 8
.B raise \fIwindow\fP
raises the window to the top of the stack
.TP 8
.B refresh
.br
redraws all windows
.TP 8
.B restart
.br
restarts nawm and rereads the configuration file(s). The global
\fBbegin\fP binding will be rerun, although the global \fBend\fP
binding won't. This behavior might change in the future if I decide
it's a bug.
.TP 8
.B setled \fInumber\fP, \fIstate\fP
set the indicated keyboard LED to the given state (0 for off, 1 for
on). The mapping from numbers to LEDs is entirely OS-specific, and on
some OSes, this doesn't actually have any effect.
.TP 8
.B setrepeat \fIkey\fP, \fIstate\fP
set the autorepeat state for the given key (0 for off, 1 for on).
.TP 8
.B size \fIwindow\fP, \fIdwidth\fP, \fIdheight\fP
resize the window by the given deltas.
.TP 8
.B sizeto \fIwindow\fP, \fIwidth\fP, \fIheight\fP
resize the window to the given absolute width and height.
.TP 8
.B sync
.br
wait for the X server to catch up with any queued requests before
continuing. You may need to use this if a binding changes something
on the screen and then tries to act on the effects of those changes
later on.
.TP 8
.B system \fIcommands\fP
pass the commands (a string) to a shell to execute.
.TP 8
.B type \fIstring\fP
types the string into the current window.
.TP 8
.B typekey \fIkeyname\fP
types the given keyname (like with key bindings) into the current
window.
.TP 8
.B unfocus
.br
break any explicitly-declared pointer focus. If you are running
another windowmanager, it may grab it back, but this can be useful in
recovering from poorly-behaved applications.
.TP 8
.B ungrab
.br
Un-grab the X server.
.TP 8
.B unmap \fIwindow\fP
unmap the window
.TP 8
.B warp \fIdx\fP, \fIdy\fP
move the cursor the given delta x and delta y
.TP 8
.B warpto \fIx\fP, \fIy\fP
move the cursor to the given absolute coordinates (negative
coordinates are treated as with moveto).
.TP 8
.B warptowindow \fIwindow\fP
move the cursor to the center of the given window and make it the
current window.
.PP
Built-in functions:
.TP 8
.B at(\fIx\fP, \fIy\fP)
returns the window located at the given point
.TP 8
.B atoi(\fIstr\fP)
converts a string representation of a number into an integer value
.TP 8
.B dheight(\fIwindow\fP)
returns the discrete height of the window
.TP 8
.B dwidth(\fIwindow\fP)
returns the discrete width of the window
.TP 8
.B env(\fIstr\fP)
looks up \fIstr\fP in the environment and returns a string
corresponding to its value.
.TP 8
.B focuswindow()
returns the window that currently has the keyboard focus
.TP 8
.B getled(\fInumber\fP)
returns the status of the numbered keyboard LED (0 for off, 1 for on).
If the operating system does not support changing the LED states in
software, then this merely returns the state as allegedly set by
setled.
.TP
.B getrepeat(\fIkey\fP)
returns whether or not the named key autorepeats.
.TP 8
.B hasname(\fIwindow\fP, \fIstr\fP)
returns 1 if the given window has the given string as either its name
or one of its class names. "hasname(win, x)" is a more robust version
of "name(win) == x".
.TP 8
.B height(\fIwindow\fP)
returns the height of the window
.TP 8
.B mapped(\fIwindow\fP)
returns whether or not the window is currently mapped
.TP 8
.B name(\fIwindow\fP)
returns the name of the given window
.TP 8
.B pick()
allows the user to select a window, and returns that window. Also sets
currentwindow.
.TP 8
.B pointerwindow()
returns the window that the pointer is currently in
.TP 8
.B px(), py()
return the x and y coordinates of the current pointer location.
.TP 8
.B width(\fIwindow\fP)
returns the width of the window
.TP 8
.B win(\fIname\fP)
returns the window with the given name: for use when you need to
explicitly convert a string to a window. (e.g, if you are testing
if ("Xterm" < "Emacs"), you'd need to use \fBwin\fP to convert one of
the two to a window to prevent them from being compared as strings.)
.TP 8
.B windows()
returns an array (window[int]) of current windows.
.TP 8
.B xloc(\fIwindow\fP), \fByloc(\fIwindow\fP)
returns the x and y coordinates of the top, left corner of the window
.PP
Built-in variables:
.TP 8
.B currentwindow
the window that is used by default when no window is specified in a
command or function. (This variable is reset whenever a binding is
run--usually to \fBpointerwindow\fP, except in the case of "leave"
events, where it's set to the window that the pointer has left, not
the window it's in currently.)
.TP 8
.B root
.br
the root window
.TP 8
.B screenheight\fP, \fBscreenwidth
the height/width of the screen.
.SH EXAMPLES
See http://www.mit.edu/~nawm/samples/
.SH BUGS
Some
.SH AUTHOR
Dan Winship (danw@mit.edu)
.br
based on the original nawm by Ken Duda and Chee Chew, with later
modifications by George Madrid and Greg Stark.