nawm - I can't believe it's not a window manager!

nawm [-e commands] [-f initfile]

nawm is not a window manager. Or at least, it used to not be a window manager. It's working its way there though.

nawm accepts a handful of command-line options:

-e commands

The commands are one or more semicolon-terminated nawm commands to execute.

-f initfile

Read commands and bindings from the named file (or standard input if initfile is -).

-i module

Load the named module. For more information about available nawm modules, see the nawmmod(3) man page. Modules can also be loaded using the include directive within a config file.

-o option

Set an option. The only currently supported option is nocapslock, which tells nawm to ignore the state of the Caps Lock key in key and mouse bindings. Options can also be set using the option directive within a config file.

-w windowmanager

Tells nawm what window manager you are using. Any string is accepted, but only two values currently cause non-default behavior:

nawm

Tells nawm that you aren't using any other window manager, so it should not try to look for and ignore window manager decorations (titlebars, etc).

vtwm.gamma

Tells nawm that you're using vtwm.gamma, so that nawm can compensate for a bug in vtwm.gamma's window moving and resizing code.

If no -w option is given, nawm will look at the final pathname component of the WINDOW_MANAGER environment variable.

If no options are specified, nawm will read commands and bindings from $HOME/.nawmrc. nawm has no default settings. You must give it a configuration either on the command line or in a .nawmrc file.

If one or more -e options are specified and no -f options are (or if the configuration file(s) don't specify any bindings) then nawm will exit after executing the given commands.

A .nawmrc is a series of declarations of the following types:

include "module";

Loads the named module, as with the -i command-line option.

option "option";

Sets the named option, as with the -o command-line option.

vartype name [, name ...];

Declares global variables. (See below for more information about data types.)

bindtype [data] { vardecls commands }

Declares a global binding. (See below for more information about bindings.)

command name [ arg [, arg ...]] { vardecls commands }

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.

function type name ( [ arg [, arg ...]] ) { vardecls commands }

Declares a global function.

mode name { bindings }

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 setmode command.

There are three primitive data types in nawm: int, string, and window, which represent the obvious kinds of data.

string values are implicitly converted to window values when necessary. (For example, the string "Emacs" will be converted to a window value corresponding to a window named "Emacs" if one exists.) Note also that an initial window 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.)

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

foo["Monday"] = 7;

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 del special form. (Not to be confused with the delete command, which sends delete messages to windows.)

You can find out the number of elements currently in an array with the expression arrayname.size.

Arrays and strings that become inaccessible are garbage collected.

There are several types of event bindings.

begin { commands }

The commands will be executed when you enter the mode the binding appears in. If multiple begin declarations appear, they will be executed in order. A global begin binding will be executed at startup time after all command-line arguments are parsed but before the main loop is entered.

end { commands }

The commands will be executed when leave the mode the binding appears in. A global end binding will be executed immediately before nawm exits normally.

key[press | release] keyname

Runs the associated commands when it gets a KeyPress or KeyRelease event for the named key with the given modifiers. key is an alias for keypress. keyname is a string, containing the X keysym name for the key, possibly preceded by one or more of the modifiers shift, control, meta, alt, super, hyper, modn for n from 1-5, or any. keyname 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".)

mouse[press | release] buttonname

As with key bindings, but for ButtonPress events. buttonname is a string which can contain a name (left, middle, or right) or a number, and can be preceded by modifiers as with key bindings.

motion

Runs the associated commands whenever it gets a MotionNotify event (ie, the mouse is moved).

enter [name]

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.

leave [name]

As with enter, but when the pointer leaves a window.

The .nawmrc configuration language is somewhat, but not entirely, unlike awk.

command [ expr [, expr...] ] ;
if ( expr ) command [ else command ]

for ( expr ; expr ; expr ) command

for ( var in arrayexpr ) command

while ( expr ) command

do command while ( expr ) ;

break ;

continue ;

del array [ subscript ]

{ commands }

The following operators all do basically what you'd expect.

= && || < <= > >= == != + - * / % ! in

+ 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.). in tests if an element is in an array. Parentheses can be used to change precedence.

Minimal expressions are numbers, strings (which are converted to windows in some contexts), variables, and function calls.

Built-in commands:

beep

beep!

cut string

copy the string to the X cut buffer. (Not yet implemented.)

delete window

send a WM_DELETE message to the indicated window.

destroy window

send a WM_DESTROY message to the indicated window.

dsize window, dwidth, dheight

discretely resize the window by the given deltas.

dsizeto window, width, height

discretely resize the window to the given width and height. For example, dsizeto "xterm", 132, 48 would resize an xterm to 132 columns by 48 rows, as opposed to sizeto "xterm", 132, 48, which would size it to 132 by 48 pixels.

exec string

parse and execute the given string of nawmrc commands. This can be used to add modes and bindings as well. (Not yet implemented.)

exit

exit nawm (after running the global end binding, if any).

find window

set window to be the current window. (This is equivalent to currentwindow = window).

grab

grabs the X server. Prevents other programs from interfering with nawm. You probably want to call ungrab not too long after calling this.

lower window

lowers the window to the bottom of the stack

map window

maps the window

mouseclick button, x, y

clicks the indicated mouse button (given as a string, as with button event bindings) at the given x and y coordinates. (Negative coordinates measure from the right or bottom of the screen.) button can include modifiers, in which case those modifier keys will be held down while nawm is clicking.

move window, dx, dy

moves the window by the given deltas

moveto window, x, y

moves the window to the specified absolute position on the screen. x and y are treated like coordinates in X geometries: negative values measure from the right or bottom of the screen.

put string

writes the string to stdout

raise window

raises the window to the top of the stack

refresh

redraws all windows

restart

restarts nawm and rereads the configuration file(s). The global begin binding will be rerun, although the global end binding won't. This behavior might change in the future if I decide it's a bug.

setled number, state

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.

setrepeat key, state

set the autorepeat state for the given key (0 for off, 1 for on).

size window, dwidth, dheight

resize the window by the given deltas.

sizeto window, width, height

resize the window to the given absolute width and height.

sync

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.

system commands

pass the commands (a string) to a shell to execute.

type string

types the string into the current window.

typekey keyname

types the given keyname (like with key bindings) into the current window.

unfocus

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.

ungrab

Un-grab the X server.

unmap window

unmap the window

warp dx, dy

move the cursor the given delta x and delta y

warpto x, y

move the cursor to the given absolute coordinates (negative coordinates are treated as with moveto).

warptowindow window

move the cursor to the center of the given window and make it the current window.

Built-in functions:

at(x, y)

returns the window located at the given point

atoi(str)

converts a string representation of a number into an integer value

dheight(window)

returns the discrete height of the window

dwidth(window)

returns the discrete width of the window

env(str)

looks up str in the environment and returns a string corresponding to its value.

focuswindow()

returns the window that currently has the keyboard focus

getled(number)

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.

getrepeat(key)

returns whether or not the named key autorepeats.

hasname(window, str)

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".

height(window)

returns the height of the window

mapped(window)

returns whether or not the window is currently mapped

name(window)

returns the name of the given window

pick()

allows the user to select a window, and returns that window. Also sets currentwindow.

pointerwindow()

returns the window that the pointer is currently in

px(), py()

return the x and y coordinates of the current pointer location.

width(window)

returns the width of the window

win(name)

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 win to convert one of the two to a window to prevent them from being compared as strings.)

windows()

returns an array (window[int]) of current windows.

xloc(window), yloc(window)

returns the x and y coordinates of the top, left corner of the window

Built-in variables:

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 pointerwindow, 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.)

root

the root window

screenheight, screenwidth the height/width of the screen.

See http://www.mit.edu/~nawm/samples/

Some

Dan Winship (danw@mit.edu)

based on the original nawm by Ken Duda and Chee Chew, with later modifications by George Madrid and Greg Stark.