ahwmrc(5)

NAME
ahwmrc - configuration file for the AHWM window manager

SYNOPSIS

$HOME/.ahwmrc ahwmrc is the configuration file for the AHWM window manager. This manual is an in-depth explanation of the file's syntax and the semantics of the file's directives.

META MANUAL

The documentation for AHWM is available in three places:

1.  the AHWM manual page, installed automatically with AHWM

2.  the HTML form of the AHWM manual, the most up-to-date version of which is available at: http://people.cs.uchicago.edu/~ahiorean/ahwm/doc/

3.  the default AHWM configuration file, which is created when you start AHWM for the first time.

This manual is comprehensive. If you're low on time, you may want to try the default configuration file first.

SYNTAX

What follows is an informal specification of the file's syntax, followed by a discussion of the syntax, and then some examples illustrating some more difficult points about the syntax.

  SYNTAX EBNF

This is an informal specification in the EBNF metalanguage. If this doesn't make sense, please see the discussion and examples in the later sections.

config = line config
    | empty

line = option “;”
    | context
    | functiondef “;”
    | binding “;”
    | unbinding “;”

option = option-name “=” type
    | option-name “is!” type

option-name = “DisplayTitlebar”
    | “FocusPolicy”
    | ....

type = boolean
    | integer
    | string
    | enumeration

boolean = “True” | “False”

...

context = context-option context-name type “{” config “}”

context-option = “Not” | “TransientFor” | “HasTransient”

context-name = “IsShaped” | “WindowName” | ....

function-def = “Define” string “{” function-list “}”

function-list = function “;” function-list
    | function “;”

function = function-name “(” arglist “)”

function-name = “Launch” | “Quit” | “Invoke” | ....

arglist = arglist “,” type
    | type

binding = “BindKey” string function
    | “BindKeyRelease” string function
    | “BindButton” location string function
    | “BindDrag” location string function

unbinding = “UnBindKey” string
    | “UnBindKeyRelease” string
    | “UnBindButton” location string
    | “UnBindDrag” location string

location = “TitleBar” | “Frame”

  SYNTAX DISCUSSION

Each line is terminated with a semicolon (“;”) (contexts are not terminated with a semicolon). The syntax is not whitespace-sensitive, except that whitespace is used to separate tokens. The file's directives are not case-sensitive, but some elements of strings are case-sensitive (these elements will be noted as CASE SENSITIVE in this manual). Comments are introduced in three ways: as Bourne shell-like comments (anything after the hash symbol (“#”) to the end of the line), as C-style comments (anything between slash-star (“/*”) and star-slash (“*/”)), or as C++-style comments (anything after slash-slash (“//”) to the end of the line). C-style comments do not nest, as in C.

The file consists of a number of directives, including options. Options may be enclosed within a context, which makes those options apply only when the conditions specified in the context are true. Contexts are used to define different options for different windows. Some options (such as NumberOfWorkspaces) may only be defined globally (they may not appear in a context). The order of options within any given context is not important, except that if an option is specified more than once, only the last setting is used. However, the order of contexts is significant — when a window matches more than one context, all directives from all contexts will be applied to the window, but if a directive appears more than once in any of the matching contexts, the last seen directive will be used.

Most of AHWM's options are set by the user; however, some options may be set by the application. For instace, a popup menu may set a hint that the window shouldn't be decorated with a titlebar.

Application-set hints override normal user-set hints. However, instead of using “=” to set an option, you can use “is!”. When you use “is!”, the option cannot be changed by the application. This is useful in when you do not like the hints an application sets. All hint-definable behaviour is also user-definable.

Other directives are available for binding keystrokes and mouse clicks and for defining aggregations of actions for binding to keystrokes and mouse clicks.

  BINDING SYNTAX

In addition to the file's syntax, defined above, binding actions to keystrokes or mouse clicks requires a string argument. This string argument describes which keys and buttons along with which modifier keys are to be bound.

The binding grammar has tokens from three groups:

1.  A KeySym which is one of the symbols from the file <X11/keysym.h>, with the “XK_” prefix removed, except for the following symbols which are not tokens:
    Shift_L
    Shift_R
    Control_L
    Control_R
    Meta_L
    Meta_R
    Alt_L
    Alt_R
    Super_L
    Super_R
    Hyper_L
    Hyper_R
    Caps_Lock
    Shift_Lock

    All of the symbols in this group are CASE-SENSITIVE.

2.  A Modifier, which is one of the following symbols:
    Shift, ShiftMask
    Control, ControlMask
    Mod1, Mod1Mask
    Mod2, Mod2Mask
    Mod3, Mod3Mask
    Mod4, Mod4Mask
    Mod5, Mod5Mask
    Alt, AltMask
    Meta, MetaMask
    Hyper, HyperMask
    Super, SuperMask

    All of the symbols in this group are case-insensitive.

3.  A Button, which is one of the following symbols:
    Button1
    Button2
    Button3
    Button4
    Button5

    All of the symbols in this group are case-insensitive.

You can see what keysyms your keystrokes generate by launching the X program xev(1) and typing into the window. See also xmodmap(1) for more information. The buttons are usually interpreted as follows:
Button1 is the left mouse button.
Button2 is the middle mouse button.
Button3 is the right mouse button.
Button4 is mouse wheel down.
Button5 is mouse wheel up.

The informal grammar for binding to keystrokes is:

string = modlist* keysym

modlist = modifier “|”

modifier = <one of the above symbols from group 2>

keysym = <one of the above symbols from group 1>

The grammar to binding to mouse events is equivalent to that for binding to keystrokes except that buttons are used instead of KeySyms.

  SYNTAX EXAMPLES

Bindings look like this:

BindKey "Control | Shift | Meta | t" Launch("xterm");
BindButton Titlebar "Mod1 | Button3" Maximize();
BindDrag Titlebar "Button1" MoveInteractively();

Options can be set as follows:

NumberOfWorkspace = 13;
FocusPolicy = ClickToFocus;

Function aggregations (user-defined functions) may be defined and bound as follows:

Define "My Goto Workspace 2 Function" {
    Launch("xsetroot -solid \"#2F4F4F\"");
    GotoWorkspace(2);
}
BindKey "Alt | 2" Invoke("My Goto Workspace 2 Function");

The rest of this section describes how to use contexts to set different options on different windows.

To have titlebars on shaped windows, but to remove titlebars from windows whose TRANSIENT_FOR hint points to a shaped window (regardless of whether or not the transient window is shaped):

IsShaped True {
    DisplayTitlebar = True;
}
TransientFor IsShaped True {
    DisplayTitlebar = False;
}

Note that order matters, and the following will put titlebars on all shaped windows (even those that are transient for another shaped window):

TransientFor IsShaped True { DisplayTitlebar = False; }
IsShaped True { DisplayTitlebar = True; }

To have titlebars on all shaped windows except those named “oclock”:

IsShaped True {
    DisplayTitlebar = True;
    WindowName "oclock" {
        DisplayTitlebar = False;
    }
}

Note that this can be done in more than one way, such as:

IsShaped True { DisplayTitlebar = True; }
WindowName "oclock" { DisplayTitlebar = False; }

Both of the above ways are equally efficient. Not that the following is not equivalent to the above two:

WindowName "oclock" { DisplayTitlebar = False; }
IsShaped True { DisplayTitlebar = True; }

This will make “oclock” have a titlebar since it is a shaped window and the contents are evaluated in order whenever a window is created.

To give another example of how order matters, consider the following:

DisplayTitlebar = True;
InWorkspace 7 {
    DisplayTitlebar = False;
    WindowClass "Xterm" {
        DisplayTitlebar = True;
    }
}
WindowClass "Xterm" {
    DisplayTitlebar = False;
}

Do xterms in workspace 7 have titlebars? The answer is no: all xterms (including those in workspace 7) will not have titlebars since the second “WindowClass” context overrides the previous options, even those nested deep within some other context.

TYPES

Both options and functions have types, and this section describes the available types.

Boolean
    One of the symbols “True” or “False”.

String
    A string with C-like syntax. Most ANSI C escape sequences are permitted; please refer to a C manual for the exact syntax.

    Examples: "foo \\ \" ", "HTTP 200 OK\r\n"

Integer
    An integer in decimal notation.

Enumeration
    One of a small number of symbols. All enumerations are described as in this manual as follows: {Fixed, NoOverlap, Contiguous} which would indicate that one of the three symbols “Fixed”, “NoOverlap” or “Contiguous” would be legal.

DESCRIPTION

    The remaining sections of this document describe how to select windows for setting options, what options you can set and what functions you can bind to keystrokes. This section describes various concepts which don't belong in the shorter descriptions of the following sections.

    This section also explains the rationale behind some of AHWM's design decisions. These decisions were made based on experimentation and interpretation of currently-accepted human interface guidelines.

Workspaces

    AHWM supports workspaces. Each workspace contains a number of windows and each window is belongs to one workspace. Only the windows in the current workspace are visible; thus, you can use workspaces to organize windows for easier access.

    Unlike some other window managers, workspaces are indivisible — AHWM does not support "viewports" into workspaces and a window may not occupy part of one workspace and part of another. Workspaces are numbered using the natural numbers; thus, the available workspaces are 1, 2, ..., NumberOfWorkspaces. A workspace has no "name" other than its number. There is no geometric relationship between workspaces, but, if you wish, you may think of the workspaces as arranged on a horizontal line, from left to right according to the workspace number.

    The number of workspaces is fixed once AHWM has started and can be set using the NumberOfWorkspaces option. The SendToWorkspace function can change a window's workspace, and the GoToWorkspace can change the current workspace.

    Windows which are omnipresent (eg, those for which the Omnipresent option is set to True) are visible in all workspaces. You can think of omnipresent windows as windows whose workspace is always the current workspace.

Moving and Resizing

    Since moving and resizing windows is the responsibility of the window manager, the way AHWM deals with this is documented here.

    You can use the MoveResize function for a non-interactive move or resize. This allows you, for instance, to bind an action to a titlebar click which immediately moves the window to the top of the screen or resizes the window to half of the screen width.

    You can use the MoveInteractively and the ResizeInteractively functions to interactively move or resize windows. You can move or resize windows using both the keyboard and the mouse.

    While moving or resizing a window, the window's titlebar indicates the window's size and position. All movement is opaque — the window contents are shown while moving, rather than a box indicating the windows position. All sizing is boxed — a box representing the windows size is drawn and the window contents remain in their original position until the end of the resize action.

    Some window managers use boxed movement because opaque movement requires more resources. After experimentation on older computers in stressed environments, it was determined that virtually all computers today can handle opaque movement, so AHWM implements only opaque movement.

    Some window managers use opaque resizing as it gives better feedback as to a window's new size. While moving a window, only the window manager and the X server do any work, but when a window is resized, the application also needs to resize the window's internal structure (it must move and resize its own widgets). After experimentation on the latest and most powerful hardware, it was determined that most X11 toolkits are not able to redisplay themselves quickly enough to support opaque resizing, so AHWM supports only boxed resizing.

    Moving a window against the edge of the screen is resisted — you have to move “more” to move part of a window off the edge of the screen. This allows you to more easily position a window precisely at the edge of the screen.

    Other window managers support edge attraction rather than edge resistance, where moving a window near the edge of the screen warps the window to the edge of the screen. AHWM implements edge resistance rather than edge attraction for two reasons: (1) edge attraction is very unintuitive for most users and (2) it is more common to wish to have a window near the edge of the screen (but still within the screen) than it is to wish to have a window just off the edge of the screen.

    While you are moving a window, the following keystrokes are available:

Left Arrow, h, a
    Move one unit left.

Right Arrow, l, d
    Move one unit right (that's an “ell” and not a “one”).

Down Arrow, j, s
    Move one unit down.

Up Arrow, k, w
    Move one unit up.

Shift and any of the above movement keys
    Shifting a movement keystroke moves to the extreme edge of the screen.

Escape
    End moving and return the window to the position before starting the move.

Enter
    End moving and accept the window's current position.

Control
    End moving, accept changes and begin a resize action.

    When resizing a window, two out of the four edges of a window may be moved. When a resize action is started using the mouse, the quadrant of the window which received the click determines which two edges are movable. When a resize action is initiated via a keystroke, the lower-right corner of the window is initially movable.

    Some window managers allow a resize action to begin with moving only one edge of the window instead of two. Again, the edge or edges to be made movable are determined by the position of the click. Generally, the targets for initiating a single-edge resize are much larger than the targets for initiating a double-edge resize. The most common case is that a user wishes to resize a window both horizontally and vertically, so this design causes a number of mis-clicks and forces greater precision in placing the initial click. With AHWM, you can hold down a modifier and drag out a size very quickly without precisely positioning the mouse. If you want to precisely control the window's size, you can use the keyboard, as the keyboard is a much more precise device for such actions.

    AHWM also provides a keystroke to change which edges are movable during a resize. You can use this key (the space bar) if you wish to constrain a mouse-based movement to only one direction. When a resize action is initiated with the keyboard, this changes the corner which is movable in the following order: Down+Right -> Up+Right -> Up+Left -> Down+Left -> Down+Right -> .... When a resize action is initiated with the mouse, this keystroke can be used to constrain which edges are movable as follows: Horizontal and Vertical -> Vertical only -> Horizontal only -> Horizontal and Vertical -> ....

    Whereas moving windows always happens in increments of one pixel, some windows may not function correctly at arbitrary sizes. For instance, xterm cannot fully use arbitrary size windows, but rather can only fully use windows sized in increments of its font size. These constraints are taken into account and affect the maximum and minimum size of a window as well as the units for resizing.

    When resizing a window, the following keystrokes are available:

Left Arrow, h, a
    Resize one unit left.

Right Arrow, l, d
    Resize one unit right (that's an “ell” and not a “one”).

Down Arrow, j, s
    Resize one unit down.

Up Arrow, k, w
    Resize one unit up.

Shift and any of the above movement keys
    Shifting a movement keystroke resizes ten units instead of one.

Escape
    End resizing and return the window to the position before starting the resize.

Enter
    End resizing and accept the window's current position.

Control
    End resizing, accept changes and begin a move action.

Space
    Change which edges are movable during the resize. See above for a description how this works.

Focus Policies

    X11 has a notion of the currently focused window (hereafter the focus window). The focus window is the window which accepts keyboard input. The way in which you change the focus window using the mouse is called the focus policy.

    X11 also has a notion of the topmost window, or the window which is on top of all other windows. Note that the two notions (focus and topmost) are separate.

    AHWM supports two focus policies: click-to-focus and sloppy focus. You can change the focus policy on a per-window or per-workspace basis setting the FocusPolicy option.

    Proprietary non-unix operating systems usually only support click-to-focus. With click-to-focus, you click on window to make it the focus window and to make it the topmost window. The mouse click used to focus a window may or may not be passed to the application, depending on the setting of PassFocusClick. The default value of PassFocusClick is true, which is the same behaviour as most proprietary non-unix operating systems.

    With sloppy focus, you change the focus window by positioning the mouse over a window — you do not have to click on the window. The root window (the desktop window) is never focused, as it usually doesn't do anything useful when it receives keyboard input. Other window managers support focus-follows-mouse which allows the root window to become focused, but this is unintuitive behaviour (and most people find it annoying), so AHWM does not support focus-follows-mouse.

    When a window becomes the focus window through sloppy focus, it will become the topmost window after a set period of time. You can change this period of time by setting the RaiseDelay option, which expresses time in milliseconds.

    For a discussion of the motivation for the raise delay and of how other window managers incorrectly implement sloppy focus, please see the following document:

    http://people.cs.uchicago.edu/~ahiorean/ahwm/sloppy-focus.html

Window Cycling

    While the focus policy determines how one can change the focus window using the mouse, window cycling allows one to change the focus window using the keyboard.

    All the windows in a workspace are maintained on a stack. A stack is a first-in-last-out list — the first element put on the stack (the bottom element) is the last element removed from the stack and the last element put on the stack (the top element) is the first element removed from the stack.

    Window cycling allows one to walk up and down a stack. You always start at the focus window (the top of the stack). The CycleNext function moves down the stack, while the CyclePrevious function moves up the stack. Moving past the top or bottom of the stack wraps around to the other end of the stack.

    After you've selected a window for focusing, that window is moved to the top of the stack.

    Other window managers implement window cycling using a simple circular list instead of a stack. Neither the stack nor the circular list methods are immediately intuitive; however, the stack method has one distinct advantage. With the circular list method, one must always examine which window has been cycled to before ending the cycle action. On the other hand, with the stack-based method, sometimes the user does not need to examine which window is being cycled to before ending the cycle action. This is because the stack-based method moves the most frequently-used windows to the top of the stack. When a user has seven windows on the screen but is only using two of them currently, the “other” window is always available with only one keystroke. With the stack-based implementation switching back and forth from one window to the other requires only two keystrokes while the circular list implementation requires seven keystrokes.

    A cycling action begins when one types the CycleNext or CyclePrevious keystroke and it ends when one has let go of all the modifiers which are involved in the CycleNext and CyclePrevious keystrokes. One can cycle up and down the stack, but the focus window is not moved to the top of the stack until the cycle action ends.

    During a cycle action, windows will always be focused immediately, but they may or may not be raised, according to the setting of the CycleBehaviour option.

    The rationale for this is that immediately raising the window will munge the stacking order of the windows, while not raising the window provides little feedback as to where one is on the focus stack. The ideal solution would be to display a list of icons and window names during the cycle and to raise the focus window only upon the end of the cycle action. The reasons for AHWM not implementing icons are many and varied (and difficulty is not one of those reasons) and providing a list of window names without icons provides textual, but not visual feedback.

    Windows can also be excluded from the cycle stack by setting the CycleBehaviour option to SkipCycle. Windows which do not accept keyboard input are automatically excluded from the focus stack; however, some windows claim they accept keyboard input, but then ignore all keyboard input. The SkipCycle setting is intended to allow you to deal with those windows.

Quoting

    Sometimes you may wish to send an application a keystroke but you've bound that keystroke to an AHWM action. Quoting allows you to bypass AHWM and pass the keystroke or mouse click through to the application.

    One of the functions you can bind to a keystroke or mouse click is the Quote function. The Quote function invokes quote mode. When you are in quote mode, AHWM will behave normally except that the next keystroke or mouse action that AHWM would intercept will instead be passed to the window that would normally receive it (ie, the focus window for a keystroke, the window under the mouse pointer for a mouse click). AHWM will then exit quote mode.

    If you change your mind about quoting an action, you can exit quote mode by invoking the Quote function again.

    The root background will be changed to white when in quote mode to remind you that AHWM is behaving differently.

    Quoting does not always work correctly. In order to understand why, a note about the implementation of quote mode is required.

    When in quote mode, AHWM needs to know when you've typed a keystroke that would normally be intercepted in order to exit quote mode after the keystroke has been received by the application. Therefore, AHWM needs to “listen” for these keystroke events, even while in quote mode. The first problem is that X11 does not allow more than one application to “listen” for these keystrokes, so these keystrokes will only be passed to AHWM, and not the application window. Thus, AHWM needs to “manufacture” or “fake” a keystroke event to pass to the application window upon receiving a bound keystroke. The second problem is that X11 allows an application to determine which keystroke events are “real” and “manufactured”. Some applications will ignore “manufactured” keystroke events. This applies to mouse clicks as well.

    It is important to note that both problems mentioned in the above paragraph are AHWM's problems, and not problems with the X11 system. X11 has very good reasons for both these design decisions, but they make implementing a completely correct quote mode impossible.

    Thus, quote mode will not work with an application if the application ignores “manufactured” events. One such application is recent versions of XFree86's xterm(1) program. In order to make quote mode work with xterm, you need to add the following line to your “~/.Xdefaults” file:

    xterm.VT100.allowSendEvents: true

    And after adding this line, either restart your X session or run xrdb(1) in the appropriate fashion.

    Note that adding this line to your “~/.Xdefaults” creates an IMMENSE GAPING SECURITY HOLE. On the other hand, quote mode is quite nice — it's your call.

Function Aggregations

    AHWM supports function aggregations or user-defined functions. A function aggregation allows you to bind more than one action to a keystroke or mouse click.

    You can define a function aggregation using the Define keyword. Use the Invoke keyword to bind an aggregation to a keystroke or mouse click.

    Function aggregations don't take arguments and the AHWM configuration language does not support any programming constructs, so function aggregations are not really user-definable functions. The names of function aggregations are CASE-SENSITIVE.

    You may define recursive function aggregations, but this is not recommended. For example, given the following configuration:

    Define "Recursive Function" { Invoke("Recursive Function"); };
    BindKey "Alt | c" Invoke("Recursive Function");

    AHWM will crash when you type “Alt | c”. Specifically, AHWM will continue invoking the recursive function until it runs out of stack space. AHWM never attempts to second-guess you.

    NB: if you are looking for an easier way to crash AHWM, the Crash function may be of interest. See also kill(1) .

CONTEXTS

This section defines the selectors available to define contexts.

IsShaped (boolean)
    If this selector is true, windows which are shaped (using the XShape extension) will match. Applications will generally use the XShape extension so they can display a non-rectangular top-level window. The standard X program xclock(1) is an example of such an application.

InWorkspace (integer)
    If a window is located in the same workspace as specifed in this selector, the context selector will match the window. The number “0” (zero) is not a valid argument for this selector. Windows which are omnipresent will match only when the current workspace is the same as the workspace specified in the argument to InWorkspace.

WindowName (string)
    This will match based on a window's name. This does exact string matching, so you must specify the window's entire name. If you give an argument of “*”, this will match any window. The window name oftentimes will change, so you may be better off matching based on WindowInstance or WindowClass. The window's name is the string which is displayed in the window's titlebar. You may also find the window's name by using the standard X program xprop(1) and looking for the “WM_NAME” property.

WindowClass (string)
    This will match based on a window's “Class”. This does exact string matching. Windows with the same “Class” are somehow related, perhaps by belonging to the same application. You can find a window's class by using the xprop(1) program and looking for the second value of the “WM_CLASS” property.

WindowInstance (string)
    This will match based on a window's “Instance”. This does exact string matching. Windows with the same “Instance” are different invocations of the same window. You can find a window's instance by using the xprop(1) program and looking for the first value of the “WM_CLASS” property.

HasTransient (context)
    This context selector is placed in front of another context selector. The resulting context will then match window A if window A has a transient window B, and window B matches the selector after the HasTransient selector. Transient windows are generally short-lived dialog boxes.

TransientFor (context)
    This context selector is placed in front of another context selector. The resulting context will then match window A if window A is a transient of window B, and window B matches the selector after the TransientFor selector.

Not (context)
    This context selector is placed in front of another context selector. The resulting context will then match window A if window A does not match the selector after the Not selector.

    Example: The following two are equivalent:

    IsShaped True { ... }
    Not IsShaped False { ... }

OPTIONS

This section describes all the available options — an option changes the way AHWM behaves. Each option has a type, which is indicated after the option name. Options may be defined globally, or may be enclosed within a context. Options may be set by the user or application; the application's setting normally overrides the user's setting (except for options set using “is!” which cannot be overridden by any application). Each function below mentions whether or not it can be set by an application using a hint. Each option has a default value, which is the value taken if not specifed in the configuration file. Note that when you start AHWM for the first time, a configuration file is created, which specifies a number of options; therefore, the default values may not apply when you start AHWM for the first time.

AlwaysOnBottom (boolean)
    If true, this window will remain below all other windows. Default: False. Application-settable.

AlwaysOnTop (boolean)
    If true, this window will remain on top of all other windows. Default: False. Application-settable.

ColorTitlebar (string)
    This option determines the background color of the titlebar when the window is not focused.

    This value of this option must be a valid X color specification. For the full details of X color specifications, please see the “Color Strings” entry in the Xlib manual (available at http://tronche.com/gui/x/xlib/color/strings/).

    Examples of valid color strings:

    “red”, “darkslategray”

    “#FF0000”, “#2F4F4F”

    “rgb:F/0/0”, “rgb:2f/4f/4f”

    The default background color of non-focused windows is black. Not application-settable.

ColorTitlebarFocused (string)
    This option determines the background color of the titlebar when the window is focused.

    This value of this option must be a valid X color specification. See ColorTitlebar for the syntax of X color specifications.

    The default background color of focused windows is white. Not application-settable.

ColorTitlebarText (string)
    This option determines the color of the titlebar title text when the window is not focused.

    This value of this option must be a valid X color specification. See ColorTitlebar for the syntax of X color specifications.

    The default color of the window titles of non-focused windows is white. Not application-settable.

ColorTitlebarTextFocused (string)
    This option determines the color of the titlebar title text when the window is focused.

    This value of this option must be a valid X color specification. See ColorTitlebar for the syntax of X color specifications.

    The default color of the window title of focused windows is black. Not application-settable.

CycleBehaviour ({SkipCycle, RaiseImmediately, RaiseOnCycleFinish, DontRaise})
    This option determines the behaviour of the CycleNext and CyclePrevious functions.

    When a window has CycleBehaviour set to SkipCycle, it will not be included in the cycle list.

    With RaiseImmediately, the window will be raised immediately upon cycling. If CycleNext is bound to “Alt | Tab”, this means that the window will be raised when you hit “Tab” with “Alt” held down.

    With RaiseOnCycleFinish, the window will not be raised when it is cycled; rather, it will be raised if it is the focused window when the cycle action ends. If CycleNext is bound to “Alt | Tab”, this means the window will be raised when you let go of “Alt”.

    With DontRaise, the window will not be raised at all.

    See also the section entitled Window Cycling.

    The default value of CycleBehaviour is RaiseImmediately. Application-settable: an application may request not to be included on the focus stack.

DefaultWorkspace (integer)
    Specifies the workspace for new windows. Use zero to map windows into the current workspace. See also the section entitled Workspaces. Default: zero. Application-settable.

DisplayTitleBar (boolean)
    Specifies whether the window will have a titlebar. Default: True. Application-settable.

DontBindMouse (boolean)
    If true, AHWM will not bind mouse actions on the specified window.

    Note that you can pass a bound mouse click to an application window using the Quote function.

    Default: False. Not application-settable.

DontBindKeys (boolean)
    If true, AHWM will not bind keystrokes on the specified window.

    Note that you can pass a bound keystroke to an application window using the Quote function. Also note that you will not be able to use your keyboard to change the focus or the workspace when a window with DontBindKeys set to True is focused.

    The default value of DontBindKeys is false. Not application-settable.

FocusPolicy ({ClickToFocus, SloppyFocus, DontFocus})
    The focus policy states how a window may be focused using the mouse. The currently focused window is the window which receives keyboard input.

    With the SloppyFocus policy, a window is focused if you move the pointer into the window. Note that the focus will only be changed when you move the pointer; the focus will not be changed when a window is unmapped or when a window resizes itself to be under the pointer. This behaviour is somewhat different from the sloppy focus policies of other window managers. The window will be raised according to RaiseDelay.

    With the ClickToFocus policy, a window is focused and raised if you click on it. This is what users of propietary non-unix operating systems expect. The focusing click may or may not be passed to the window, depending on the value of PassFocusClick.

    With the DontFocus policy, the window is never focused. A window with the focus policy set to DontFocus will be exluded from the focus-cycle list (so this focus policy implies CycleBehaviour is SkipCycle).

    See also the section entitled Focus Policies.

    The default value of FocusPolicy is ClickToFocus. Application-settable: an application may indicate that it does not accept keyboard input, in which case the application will have a FocusPolicy of DontFocus.

KeepTransientsOnTop (boolean)
    When true, AHWM will attempt to keep this window's transient windows on top of it. In practice, this means that AHWM will attempt to keep a application's temporary dialog boxes stacked on top of the application.

    The default value of KeepTransientsOnTop is True. Not application-settable.

NumberOfWorkspaces (integer)
    This option determines the number of workspaces available.

    The number of workspaces cannot be changed once AHWM has started.

    NB: this option must be applied globally. If you specify this option in a non-global context, it will be silently ignored.

    See also the section entitled Workspaces.

    The default value of NumberOfWorkspaces is “7” (seven). Not application-settable.

Omnipresent (boolean)
    If true, the window will be visible on all workspaces. See also the section entitled Workspaces. Default: False. Application-settable.

PassFocusClick (boolean)
    This option does nothing unless the FocusPolicy is ClickToFocus. If the FocusPolicy is ClickToFocus and PassFocusClick is true, the window will receive the focusing click. See also the section entitled Focus Policies. Default: True. Not application-settable.

RaiseDelay (integer)
    This option does nothing unless the FocusPolicy is SloppyFocus. If the FocusPolicy is SloppyFocus, RaiseDelay specifies an amount of time, in milliseconds, to wait before raising a window when the window is focused using the mouse. Use a value of zero to raise immediately. See also the section entitled Focus Policies. Default: zero. Not application-settable.

Sticky (boolean)
    When true, the window will not respond to move or resize requests. Default: False. Application-settable.

TitlebarFont (string)
    This option determines the font to use for titlebars.

    NB: this option must be applied globally. If you specify this option in a non-global context, it will be silently ignored.

    The height of the titlebar is also determined by this option.

    The value of this option must be a valid X font name. For the full syntax of X font names, please see the document “X Logical Font Description Conventions”, available in PDF format here: http://www.x-docs.org/XLFD/xlfd.pdf.

    You can also find a suitable font name by using the standard X program xfontsel(1) .

    The default value of TitlebarFont depends on the available fonts. Not application-settable.

TitlePosition ({DisplayLeft, DisplayRight, DisplayCentered, DontDisplay})
    This option determines where on the titlebar the window title will be displayed. For DisplayLeft, DisplayRight, and DislpayCentered, the title will be displayed on the left, right, or center of the titlebar, respectively. For DontDisplay, the window title will not be displayed.

    The default value of TitlePosition is DisplayLeft. Not application-settable.

FUNCTIONS

This section describes all the available functions — a function is an action which one can bind to a mouse click or a keystroke. A function may have zero or more parameters, each with a given type. If a function takes no parameters, its type will be specified as void in this section. Most functions operate on a window, called the current window in this section. If a function is bound to a keystroke, the current window is the window with the input focus; if a function is bound to a mouse click, the current window is the window which received the mouse click.

Crash (void)
    Cause AHWM to crash. Specifically, this will cause AHWM to dereference a NULL pointer, which will raise a segmentation fault.

    The point of this function is to make it easy to test that AHWM's crash-handler is working correctly. The function is documented for completeness, and this is a good place to mention that AHWM will attempt to handle crashes to the best of its ability.

    You probably don't want to use this function. Then again, that's your choice, not mine.

    It is unfortunate that this is alphabetically the first function. The rest of the functions are actually useful.

CycleNext (void)
    Cycle to the next window on the focus stack. For a complete discussion, please see the subsection entitled Window Cycling.

CyclePrevious (void)
    Cycle to the previous window on the focus stack. For a complete discussion, please see the subsection entitled Window Cycling.

Focus (void)
    Make the current window the focus window. Binding this function to a keystroke is pointless, as the current window is the focus window for functions bound to keystrokes. This function is meant to be bound to a mouse click.

GoToWorkspace (integer)
    Changes the workspace to the specified workspace. Going from the current workspace to the same workspace is allowed and this has a similar effect to the standard X program xrefresh(1) . See also the section entitled Workspaces.

Invoke (void)
    Invoke a function aggregation (aka, a user-defined function). Please see the section entitled Function Aggregations.

KillNicely (void)
    Ask the current window to close itself.

    Specifically, it will use the “WM_DELETE_WINDOW” protocol, if the window supports this protocol. If the window does not support this protocol, the window will immediately be closed as with KillWithExtremePrejudice.

    If an application supports the “WM_DELETE_WINDOW” protocol and is “hung”, it will probably not close itself, and AHWM will not attempt to ascertain whether or not the window is “hung”. Therefore, the when using this function, the window may not close itself; if that happens, use KillWithExtremePrejudice.

KillWithExtremePrejudice (void)
    Immediately close the current window, no questions asked.

    Specifically, this function will use XKillClient(3) . This is guaranteed to close the window, but the application will not receive any notice that anything has happened until its next X request fails because it has been disconnected from the X server. In most cases, this will cause the application to exit ungracefully. In some poorly-written applications, this may cause you to lose your work.

    If the application is truly completely “hung”, it will not process X events, so it will not receive X errors. This means that although the application's window is gone, the application is still alive and taking up resources such as memory and CPU time. Netscape Navigator 4.x has a tendency to do exactly this. The best recourse in such a situation is to open a terminal window and use kill(1) . Since X is a network-transparent system, the application may be running on a different machine than AHWM; therefore, AHWM cannot kill the application for you.

    In order to ameliorate this situation, the Extended Window Manager Hints document defines a protocol for (1) determining if an application might be “hung”, (2) determining an application's PID, if the application is running on a unix-like system, and (3) determining the host the application is running on if the application's X session is running over TCP/IP or on the local host. AHWM does not yet implement this protocol, as it is still extremely experimental. In addition, client applications must implement this protocol, so this will not solve the Netscape Navigator problem.

Launch (string)
    This will take the string argument and pass it to a Bourne shell. You can use this function to launch programs and do useful work.

Maximize (void)
    Toggle the maximization state of the window. When a window is maximized, it will take up as much of the screen as possible. Whenever a maximized window is moved or resized, it will no longer be considered maximized.

MaximizeHorizontally (void)
    Toggle the horizontal maximization state of the window. This function is similar to Maximize, except that it only maximizes horizontally.

MaximizeVertically (void)
    Toggle the vertical maximization state of the window. This function is similar to Maximize, except that it only maximizes vertically.

MoveInteractively (void)
    Move a window interactively, either with the mouse or keyboard. See the section entitled Moving and Resizing for details.

MoveResize (string)
    Move and/or resize a window non-interactively.

    The string argument is in the form accepted by XParseGeometry(3) . This allows you to specify any or all components of a size and position. NB: when you move or resize a window interactively, the size units displayed may not be pixels (for instance, the size units for xterm are defined by the font height and width). The size units for this function are always pixels.

    Examples:

    MoveResize("100x200")
    This resizes the window to one hundred by two hundred pixels and does not change the window's position.

    MoveResize("+300+400")
    This moves the window to three hundred pixels below the top of the screen and four hundred units from the left side of the screen. The window is not resized.

    MoveResize("100x200+300+400")
    This has the effect of combining the above two examples; the window is both moved and resized.

Nop (void)
    Do nothing. You can bind this function to a keystroke, and then the keystroke will be “eaten” by AHWM.

Quit (void)
    Exit AHWM with zero (successful) status. This will most likely end your X session.

Quote (void)
    Enter or exit quote mode. You can use quote mode to pass an application a keystroke or mouse click that would normally be used by AHWM. See the subsection entitled Quoting for details.

Raise (void)
    Raise the current window. The focus window is usually also the raised window, so binding this to a keystroke may not be very useful.

ResizeInteractively (void)
    Resize a window interactively, either with the mouse or keyboard. See the section entitled Moving and Resizing for details.

Restart (void)
    Restart AHWM. When AHWM stops and then starts again, it should return to the exact same state. AHWM reads the file “~/.ahwmrc” when it starts, so you can simply use this function when you change your “~/.ahwmrc” file to apply the changes without logging out of your X session.

SendToWorkspace (integer)
    Move the current window to the specified workspace. NB that this does not change the current workspace. If you wish to both send a window to a workspace and change the current workspace with one action, you can define a function aggregation. See also the section entitled Workspaces.

SEE ALSO

X(1) , xprop(1) , xrdb(1) , xmodmap(1) , xev(1) , kill(1) , xfontsel(1) , twm(1) , xterm(1) , xclock(1) , xrefresh(1) , XKillClient(3) , XParseGeometry(3) , Inter-Client Communication Conventions Manual, Version 2.0, Extended Window Manager Hints, Version 1.1

LICENSE

AHWM is Copyright (C) Alex Hioreanu, 2002.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

AUTHOR

Written by Alex Hioreanu, hioreanu+ahwm@uchicago.edu.