ahwm

ahwmrc(5)                            AHWM                            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.



The AHWM Window Manager          January 2002                        ahwmrc(5)