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)