\chapter{The Standard GWM Packages}

\sloppy

This chapter describes the {\WOOL} packages available on the standard GWM
distribution. The name of the involved files are listed in the title of each
package.

{\GWM} does not try to enforce any policy in writing profiles, but for the
sake of simplicity and maintainability, all the {\WOOL} packages delivered
with {\GWM} will try to be compliant with a set of rules described in
section~\ref{standard-styleguide}, page~\pageref{standard-styleguide}, which
should assure the compatibility between them.

{\bf Note:} Distributed code is normally indented under emacs by Alan M.
Caroll's \verb|amc-lisp.el| emacs-lisp package, which is now included in the
{\GWM} distribution in the \verb|contrib/lisp-modes/| subdirectory.

You can have a look at my personal profile in the file
\verb|data/profile-colas.gwm| if you are looking for actual examples.

\section{The Standard Profile\hfill{\tt .profile.gwm}}
\label{standard-profile}

The standard profile can be customized to your taste by creating a
\verb".profile.gwm" file in your home directory, or by copying the one in
the {\GWM} distribution directory in your home directory and editing 
it.\footnote{The standard profile is the default one, which you get if you do
not have a \verb".gwmrc.gwm" file in your home directory. It is a
real-estate overlapping environment. It is defined in the \verb".gwmrc.gwm"
file in the {\GWM} distribution directory.}

\subsection{mouse buttons}

The default behavior for clicking of the mouse buttons is, in a window
decoration or an icon:

\begin{description}

\item[left button] Moves the window. Releasing the button actually moves the
window, pressing another one while still holding down the left button
cancels the move operation

\item[middle button in a window] Resizes the window. The size of the window
will be displayed in the upper-left corner of the screen. Releasing the
button actually resizes the window, pressing another one while still holding
down the middle button cancels the resize operation

\item[middle button in an icon] de-iconifies the icon

\item[right button] brings up a pop-up menu for additional functions, such
as iconification and destruction

\end{description} 

These functions are enabled only in the {\GWM}-added decoration around the
window, or anywhere in the window if the {\bf alternate} (or {\bf meta} or
{\bf left} key on some keyboards) modifier key is depressed when clicking,
in the \verb"uwm" style of interaction.

Moreover, if you click in the icon in the upper left of the frame around the
xterm windows with the left or right button, the window will be iconified,
and with the middle button, it will be iconified and the icon moved just
underneath the pointer. You can still move the icon elsewhere by
dragging it while the middle button is down.

Whether you want the window to be raised on top of others when performing a
move, resize, or (de-)iconify operation can be toggled by setting to \verb|t|
or \verb|()| the global values \verb|raise-on-move|, \verb|raise-on-resize|,
and \verb|raise-on-iconify|.\label{raise-on-move}

\subsection{customization}

Customization is achieved by creating a \verb".profile.gwm" file in
your home directory (or anywhere in your \verb"GWMPATH"). In this file
you can set the variables to modify the standard profile to suit your
taste. Note that you must set variables used in decorations {\bf
before} loading this decoration by a \verb"set-window" or
\verb"set-icon-window" call.

Your \verb".profile.gwm" will be loaded once for each screen
managed, and since pixmaps, colors, cursors and menus are screen-dependent
objects, try to define them as \verb"names" in the \verb"screen." namespace
(\seep{namespace-make}).

\subsubsection{Mouse bindings}

The standard mouse button bindings can be redefined by re-defining the default
{\bf states} (\seep{state-make}) for a click in a window decoration, an icon
and the root window, which are respectively the global variables {\bf
window-behavior}, {\bf icon-behavior}, {\bf root-behavior}. These states will
be used to build the {\bf fsms} of the windows, icons and root window. The
state {\bf standard-behavior} is included in both window and icon behaviors,
so that you can add transitions to it if you want to have them in both
contexts. You may then need to redefine the events grabbed by {\GWM}, in the
{\bf grabs} variables; all events in these lists are ``stolen'' from the
application and redirected to {\GWM}.  There are three grabs variables: {\tt
root-grabs}, {\tt window-grabs}, and {\tt icon-grabs}, pointing to the lists
of event to be ``grabbed'' from all applications, only from windows, and only
for icons.  That is why you can move a window by clicking anywhere in it with
the left button while depressing the {\tt Alt} key: the standard grabs
consists of the list:

{\exemplefont\begin{verbatim}
        (list (button any with-alt)
              (button select-button (together with-shift with-alt)))
\end{verbatim}}

If you only want to change button bindings, change the value of {\tt
select-button}, {\tt action-button}, and {\tt menu-button}, which are
initially bound to 1, 2, and 3 respectively.

You need to call the {\tt reparse-standard-behaviors} function after modifying
any of these states to take your changes into account. For instance, to add
iconification on the ``F1'' function key only on windows, you would write in
your .profile.gwm file:

{\exemplefont\begin{verbatim}
        (setq window-behavior
            (state-make
               (on (keyrelease "F1" alone) (iconify-window))
               standard-behavior))           ; include previous actions

        (reparse-standard-behaviors)         ; commit changes
        (setq window-grabs                   ; grab F1 from clients
            (+ window-grabs (list (keyrelease "F1" alone))))
\end{verbatim}}


\subsubsection{global switches}

The following global variables (which are names in the \verb"screen."
namespace for all pixmaps, colors, cursor and menus) controlling the way the
standard profile operates can be set in your \verb".profile.gwm" file:

\begin{description}

\itemtt{cursor} to the cursor displayed in any decoration or icon
\itemtt{root-cursor} to the cursor displayed on the root window. The
available cursors in the distribution are:
\begin{description} 
\itemtt{arrow} a big arrow
\itemtt{arrowhole} same with a hole inside
\itemtt{arrow3d} a 3d-looking triangular shape. Especially nice on a clear
background.
\end{description}
For instance, to use the ``{\tt arrow3d}'' cursor, just say:
{\exemplefont\begin{verbatim}
        (setq root-cursor (cursor-make "arrow3d"))
\end{verbatim}}

\itemtt{screen-tile} to the pixmap used to tile the root window with.
Provided bitmaps are \verb"back.xbm" (default) and \verb"grainy.xbm"

\itemtt{autoraise} if set to \verb"t", (defaults to \verb"()"), {\GWM} will
raise on top of others the window which has the input focus

\itemtt{xterm-list} the list of machines the user wants to launch a remote
xterm on (via the \verb"rxterm"\footnote{{\tt rxterm}, {\tt rxload}
and {\tt rx} are Bourne shell scripts used to start remote xterms,
xloads or any other X command. The rxterm script is included in the
distribution, in the {\tt gwm} subdirectory, install it and make rx
and rxload as links to it} command)

\itemtt{xload-list} the list of machines the user wants to launch a remote
xload on (via the \verb"rxload" command) 

\itemtt{icon-pixmap} the pixmap to be displayed in the upper left
corner of window to iconify it 

\itemtt{to-be-done-after-setup} the list (\verb"progn"-prefixed) of things
to be executed after all windows already present have been decorated.  

\itemtt{look-3d} to \verb"t" to specify that window decoration packages that
support it should adopt a tridimensional look. The default for this variable
is \verb"()" on monochrome displays and \verb"t" on color and grayscale ones.

\end{description}

\subsubsection{Window and icon decoration}

Moreover, you can decide to change the decoration (look and feel)
of a client or an associated icon by using the following functions.

For most following functions, when a \verb|window-description| is expected, it
means a X resource specification of the form:
\begin{verbatim}
client-class.client.name.window-name.machine-name
\end{verbatim}
where *-notation, or ``any'' to means any value for a field is accepted. Note
that all fields are optional, except for client-class.
Thus, you can say that you want all xterm icons to be xterm-icons, except for
the one named Console, on machine avahi, for which you want to use
a simple icon by:
{\exemplefont\begin{verbatim}
        (set-icon-window XTerm xterm-icon)
        (set-icon-window XTerm*Console.avahi simple-icon)
\end{verbatim}}

{\bf Note:} for all functions, to set defaults for a screen type or a client
class, use the \verb"any" keyword.

{\bf Note:} Since version {\bf 1.7}, the values affected to \verb|set-window|
et al.\ functions are evaluated at {\bf decoration time}, not while reading the
profile as it was the case before.

\begin{description}

\itemtt{(set-window [screen-type] window-description decoration)}
\label{set-window} will tell {\GWM} to use the decoration described in {\tt
decoration} for all clients of client description {\tt window-description} in the
current screen of type \verb"screen-type". {\tt decoration} can be either:

\begin{itemize} 
\item a real decoration made with a {\tt window-make} call
\item a function returning a decoration when called without parameters 
\item the file name (as a string or atom) of one of the standard decorations 
as listed in the section \ref{standard-decorations}. The file will be loaded
and should set the {\tt decoration} atom to either a real decoration or a
function returning a decoration 
\end{itemize}

For instance, these declarations say that xterms on this screen, if it is a
monochrome one will be decorated by the \verb"simple-ed-win" style, but if
the screen is a color or grayscale one, will use the \verb"simple-win"
decoration, and will use the ``no-decoration'' style for windows not otherwise
describe (The {\tt no-decoration} window description adds no visible
decoration to a window).

{\exemplefont\begin{verbatim}
        (set-window mono XTerm simple-ed-win)
        (set-window any XTerm simple-win)
        (set-window any no-decoration)
\end{verbatim}}

To choose decorations on other criteria than just class, define a function
that will return a {\WOOL} expression which will give the good decoration when
evaluated. For instance, to put a \verb"simple-ed-win" decoration on all
XTerms, except those less than 200 pixels wide, use this in your .profile.gwm:

{\exemplefont\begin{verbatim}
        (defun decide-which-xterm-deco ()
            '(if (< window-width 200) (no-frame)
                 (simple-ed-win)))
        (set-window any XTerm decide-which-xterm-deco)
\end{verbatim}}

For an example of an alternative choosing function, see
\seep{match-windowspec}.

\itemtt{(set-icon [screen-type] window-description bitmap-file)} \label{set-icon}
will associate to a client a simple icon made of the the X11 bitmap stored
in \verb"bitmap-file" (with the current value of \verb"foreground" and
\verb"background" at the time of the call to \verb"set-icon") and the name
of the icon underneath it. 

If a list is given as the last argument, it is evaluated and the pixmap is
taken as the result of the evaluation.

Suppose that you designed a picture of a mailbox named ``mail-icon.xbm'',
saved it somewhere in your GWMPATH, and want to use it for the icon of the
client \verb"xmh". You would add in your \verb".profile.gwm" one of the two
forms:

{\exemplefont\begin{verbatim}
        (set-icon XMh mail-icon.xbm)
        (set-icon XMh (pixmap-make black "mail-icon.xbm" white))
\end{verbatim}}

The icon can also be a color pixmap in the XPM format, loaded then with the
``pixmap-load'' function. In this case, gwm supports the non-rectangular shape
that may be specified in the icon file (the transparent colors of XPM),
allowing for a great flexibility in icon design.

{\bf Note:} the icon bitmap can only be set for icon decorations
supporting it, such as the (default) \verb"simple-icon" decoration style.

\itemtt{(set-icon-window [screen-type] window-description icon-file)}\label{set-icon-window} This
call will associate more complex icons to a given client, such as those
listed in section~\ref{standard-icons}, p~\pageref{standard-icons}. For
instance to have \verb"xterm" icons look like a mini computer display, add
in your \verb".profile.gwm":

{\exemplefont\begin{verbatim}
        (set-icon-window XTerm term-icon)
\end{verbatim}}

The \verb"term-icon" argument can be either a client window decoration, a
function returning a decoration or a file name, as for the \see{set-window}
function. On startup, {\GWM} does a:

{\exemplefont\begin{verbatim}
        (set-icon-window any any simple-icon)
\end{verbatim}}

\end{description}

\subsubsection{Desktop space management\hfil{\tt placements.gwm}}

\label{set-placement}
The standard profile supports functions to automatically place your windows
or icons on the screen. These functions manage only some type of clients (or
all of them if affected to the \verb"any" client), and they are called
with one argument set to {\bf t} on opening the window, and to {\bf ()} on
closing (destruction) it. They are associated to clients by the calls:

\begin{description}

\itemtt{(set-placement [screen-type] window-description function-name)} for the
main windows of a client. 

\itemtt{(set-icon-placement [screen-type] window-description function-name)} for
its associated icons.

\end{description}

The currently pre-defined placement functions are:

\begin{description}

\itemtt{()} does nothing, the window just maps where it was created
by the client (this is the default value)

\itemtt{user-positioning} asks the user to place it interactively

\itemtt{rows.XXX.placement} automatically aligns the windows or icons on the
sides of the screen. Replace {\tt XXX} by one of the eight names in the 
following figure:

\centerline{\texpsfig{places1.id}{261}{117}}

You can set the space where the {\tt XXX} row lives by issuing calls to the
control function \verb"rows.limits" with the syntax:

\begin{verbatim}
        (rows.limits rows.XXX [key value] ...)
\end{verbatim}

where {\tt key} is an atom setting a value (in pixels). Key can be either {\tt
start}, {\tt end}, {\tt offset}, and {\tt separator} as shown in the following
figure for {\tt XXX = top-left}:

\centerline{\texpsfig{places2.id}{195}{90}}

{\tt key} can also be {\tt sort}, in which case the icon in this row will
always be kept sorted by the function given in argument. This function will
take two windows as argument, and must return -1, 1, or 0 if the first window
must be before, after, or if they have the same precedence. As an example, a
{\tt sort-icons} function is provided; if you set it as a row sorting
function, it will sort windows according to their weight as set in the
property list {\tt icon-order} indexed on the class of the
application\footnote{for instance, the default order is set by {\tt (setq
icon-order '(Xmh 10 XPostit 5 XRn 20 XClock 2 XBiff 1 XLoad 20))}}. Windows
having the same weight are sorted by window name. If an application is not
found in this list, the value of the variable {\tt icon-order-default} is used
(default 100). Of course, you are free to redesign other sort functions.

\end{description}

For instance you can manage your \verb"xterm" windows by:

{\exemplefont\begin{verbatim}
        (set-placement XTerm user-positioning)
        (set-icon-placement any XTerm rows.right-top.placement)
        (rows.limits rows.right-top 'start 100 'separator 2)
        (rows.limits rows.top-left 'sort sort-icons)
\end{verbatim}}

You can define your own window placement functions and use them by the
\verb"set-placement" call. They will be called with one argument, {\bf t}
when the window (or icon) is first created, and {\bf ()} when the window is
destroyed. This is why we needed an interpretive extension language! An example
of another placement routine is given in the user-contributed package
\seeref{near-mouse.gwm}.

{\exemplefont\begin{verbatim}
        (defun do-what-I-mean (flag) ...great code...)
        (set-icon-placement any any do-what-I-mean)
\end{verbatim}}

\subsubsection{Menus}

The displayed menus can be redefined by setting the following global
variables to menus made with the chosen menu package. The default package
is the \seeref{std-popups} package.

\begin{description}
\itemtt{window-pop} for the menu triggered in windows
\itemtt{icon-pop} for the menu triggered in icons
\itemtt{root-pop} for the menu triggered in the root window
\end{description}

You can look at their standard implementation in the \verb"def-menus.gwm"
distribution file.

\section{Jay Berkenbilt's Virtual Screen\hfill{\tt vscreen.gwm}}
\label{vscreen}

This little ``virtual screen'' package, made by Emanuel Jay Berkenbilt, MIT
\verb|<qjb@ATHENA.MIT.EDU>| provides a way to use the physical screen of your
workstation as a viewport on a larger root window. You move the screen by keys
(default is {\sc Ctrl-Alt} arrows), can ask for a map of the screen to be
displayed (item \verb|VS Show| in root menu), and to move back to origin (item
\verb|VS Restore| in root menu). This quick-and-dirty package doesn't pretend
to compete with {\sc Vtwm}, but it is a good start.

The current upper left of the screen is shown a cross in the map. Clicking in
the map will make it disappear, and the map is a snapshot of the current
situation which is not automatically updated.

You can customize it by setting the following variables:

\begin{description}
\itemtt{vscreen.menupos} position of the \verb|VS Show/Restore| entry in root 
menu, to draw a map of the screen and to move back the screen to origin.
\itemtt{vscreen.windowmenupos} position of the \verb|VS UnNail/Nail| Entry in
window menu to make window move along the virtual screen.
\itemtt{vscreen.modifiers} modifiers to press with arrow keys to move the
screen around
\itemtt{vscreen.no-bindings} set to \verb|t| if you do not want to bind arrow
keys to \verb|vscreen.move-windows| functions.
\itemtt{vscreen.right-left} amount the virtual screen is moved by on a
horizontal key stroke. Defaults to half a screen.
\itemtt{vscreen.down-up} amount the virtual screen is moved by on a
vertical key stroke. Defaults to half a screen.
\itemtt{vscreen.nailed-windows} a list of windows to be carried along with the
screen. This list is a list of windowspecs (property lists)
\seesnp{match-windowspec}.
\end{description}

\section{Anders Holst's Virtual Screen\hfill{\tt virtual.gwm}}
\label{virtual}

This virtual screen package consists of the files {\tt virtual.gwm},
{\tt virtual-door.gwm}, {\tt virtual-pan.gwm}, and {\tt
load-virtual}. It is essentially built upon Jay Berkenbilt's virtual
screen package, {\tt vscreen.gwm}, described above. The main
differences are: 

\begin{itemize} 
\item The map looks neater, and you can specify different colors for 
    different kinds of windows.
\item It is updated automatically when the window configuration changes.
\item The map obeys some mouse events: You can move the real screen by
    clicking the left button on the map, or move specific windows by
    dragging them on the map with the middle button. Just in case the
    map would not get updated automatically in some obscure situation,
    you can update it by clicking the right button.
\item The file ``virtual-door.gwm'' provides doors to places on the virtual
    screen.
\item The file ``virtual-pan.gwm'' provides either autopanning or ``pan on
    click'', dependent of the value of the variable `pan-on-click'. 
\item This package {\em does\/} pretend to compete with {\sc Vtwm}.
\end{itemize}

To use this package, load {\tt load-virtual.gwm} somewhere at the end of
your ``*rc.gwm'' or ``.profile.gwm''. It will load the other three files
mentioned above and set up necessary environment. Check the files {\tt
virtual.gwm}, {\tt virtual-door.gwm}, and {\tt virtual-pan.gwm}
individually for customization variables.

\section{Adaptation of virtual.gwm\hfill{\tt std-virtual.gwm}}
\label{std-virtual}

To use {\tt virtual.gwm} in a standard profile, load {\tt std-virtual.gwm}
which implements a simple rooms style on top of virtual.gwm. before this you
can set up a list of room names (strings) that can be lists of room name,
color of the background, and optional context variables to customize the door
buttons (see {\tt virtual-door.gwm}). For instance:
\begin{verbatim}
(setq std-virtual.doors '(
    ("Home" screen-background)
    ("Comp" "LightBlue3")
    ("Mail" 
      (pixmap-make (color-make "seagreen3") "grainy" 
        (color-make "seagreen2"))
      background (color-make "seagreen3"))    
    ("WWW" lightgrey door-icon (pixmap-load "netscape-small.xpm"))
    ("Text" "LightYellow3")
    ("Games" grey)
))

(load "std-virtual.gwm")
\end{verbatim}

Icons then are visible in every room, and de-iconifying it via the middle
button moves you to the de-iconified window room, or you can by menu
de-iconify in the current room. Among them are the standard attributes such as
background, foreground, font, tile, and some specific ones such as {\tt
door-icon} for an icon pixmap to be displayed, and {\tt door-action} for wool
code to be executed when entering the room.

\section{Duane Voth's rooms\hfill{\tt dvrooms.gwm}}
\label{dvroom}

{\bf Duane Voth} (\verb"duanev@mcc.com") made a mini {\em rooms\/} 
package to manage groups of windows. To use it, put in your .profile.gwm
the line
\begin{verbatim}
        (load "dvrooms")
\end{verbatim}
before any calls to any \verb"(set-..." call.
Then, with the standard profile, you can add new rooms by the root pop-up menu,
or by explicitly calling the \verb"new-dvroom-manager" function in your
profile, with the name of the room as arguments.
{\exemplefont\begin{verbatim}
        (new-dvroom-manager "mail")
        (new-dvroom-manager "dbx")
\end{verbatim}}
The name of the room itself is the same editable plug as the one used for
the \verb"simple-ed-win" window decoration, so that you can edit it
by double-clicking or control-alt clicking with the left button.

Only one room is ``open'' (non-iconified) at a time (unless
\verb|dvroom.icon-box| is non-nil), and calling the
functions \verb"add-to-dvroom" or \verb"remove-from-dvroom" (from the
window menu or from {\WOOL}) on a window will add or remove it from the group
of windows that will be iconified or de-iconified along with the room manager.
Opening a room will close the previously open one, iconifying all its managed
windows. New rooms start as icons.

This package will recognize as a room manager any window with the name 
\verb"rmgr". You can then create new rooms by other Unix processes.
An X property GWM\_ROOM is maintained on windows added to rooms containing the
name of the room manager, so that rooms are not lost on restarting {\GWM}.

Context used:
\begin{description}
\itemtt{dvroom.font} font of the name of the room
\itemtt{dvroom.background} background color
\itemtt{dvroom.foreground} color of the text of the name
\itemtt{dvroom.borderwidth} borderwidth of the room
\itemtt{dvroom.x, dvroom.y} initial position of the room
\itemtt{dvroom.name} string used to build the name of the room. Defaults
to \verb|"Room #"| (a number will be concatenated to it).
\itemtt{edit-keys.return, edit-keys.backspace, edit-keys.delete} keys used
for editing, see \verb"simple-ed-win", p~\pageref{simple-ed-win}
\itemtt{dvroom.auto-add} if set to \verb|t| (default \verb|()|), new windows
are automatically added to the current active dvroom, if there is one.
\itemtt{dvroom.icon-box} if set to \verb|t|, dvrooms are no more exclusive
(i.e., opening one do not close the others anymore).
\end{description}

Dwight Shih \verb|<dwight@s1.gov>| added the functions:
\begin{description}
\itemtt{roll-rooms-up, roll-rooms-down}, to sequentially open the next room.
This is very handy to bind to a function key for instance.
\itemtt{magic-dvroom-attach}, which look for all the window with name in the
form \verb|<Room>::<Name>| and incorporates them into the dvroom
\verb|<Room>|, if any exists.
\itemtt{dvroom-remapping} unmap all windows belonging to a dvroom.
\end{description}

\section{Group Iconification\hfill{\tt icon-groups.gwm}}
\label{icon-groups}

Loading the {\tt icon-groups} package redefines the {\tt iconify-window}
function to use only one icon for all windows of the same group. Iconifying
the group leader will iconify all the windows in the group, whereas
iconifying a non-leader member of the group will only unmap it and map the
common icon if it is not already present.

You can specify which groups you do not want iconified this way by setting
their class in the list \verb|icon-groups.exclude|. For instance, if you want
to iconify your XPostits this way, but not you emacs or xmh windows, add this
in your .profile.gwm:

{\exemplefont\begin{verbatim}
        (load "icon-groups")
        (setq icon-groups.exclude '(Xmh Emacs))
\end{verbatim}}

It will also add two more items in the menu:
\begin{description}
\itemtt{Iconify Group} to iconify all the windows belonging to the group of the
current window.
\itemtt{Iconify Others} to iconify all the windows belonging to the group of 
the current window, but not the current window.
\end{description}

\section{Opaque move\hfill{\tt move-opaque.gwm}}
\label{move-opaque}

Loading the {\tt move-opaque} package redefines the {\tt move-window} function
to move the whole window, not just an outline of it. You can control which
windows will be moved this way by setting two context variables:

\begin{description}
\itemtt{move-opaque.condition} will be evaluated, and if the result is
non-nil, the window will be moved in an ``opaque'' way, otherwise the standard
outline dragging will be used. Default is to move only the windows whose pixel
area is less than the \verb"move-opaque.cutoff-area" value, which could be
specified by:
{\exemplefont\begin{verbatim}
        (setq move-opaque.condition
            '(< (* window-width window-height) 
                move-opaque.cutoff-area)
\end{verbatim}}
\itemtt{move-opaque.cutoff-area} which defaults to 250000, used when
discriminating windows by size.
\end{description}       

\section{Delta\hfill{\tt deltabutton.gwm}}
\label{deltabutton}

The \verb|deltabutton| function is used to perform two different action on the
press of a button, depending on whether the user release the button without
moving the mouse more than \verb|deltabutton.delta| pixels (defaults to 4) in
any direction. To use deltabutton, you must have loaded the
\verb|deltabutton.gwm| file, and in a transition of a fsm triggered by a
buttonpress event, this function will wait for the button to be released, and
return \verb|t| if the pointer has moved more than \verb|deltabutton.delta|
pixels, or \verb|()| if not.

For instance, to raise a window if you click on it, and to move it only if you
move the mouse more than 4 pixels, declare in your .profile.gwm:

{\exemplefont\begin{verbatim}
        (load 'deltabutton)
        (setq standard-behavior
           (state-make
              (on (buttonpress select-button alone) 
                  (if (deltabutton)
                      (progn (raise-window)(move-window))
                    (raise-window)))
              standard-behavior))
        (reparse-standard-behaviors)
\end{verbatim}}

\section{Floating windows\hfill{\tt float.gwm}}
\label{float}

Rod Whitby \verb|<rwhitby@adl.austek.oz.au>| made this package to
interactively make some windows ``float'' always on top of others, or always
``sink'' to the back of the screen.  Loading this package will add a multiple
menu item to the window menu to make the current window float Up, Down, or to
make it a normal window back again (item ``No'').

\section{Unconfined-move\hfill{\tt unconf-move.gwm}}
\label{unconf-move}

Rod Whitby \verb|<rwhitby@adl.austek.oz.au>| made this package to
be able to still move and resize windows out of screen boundaries even when
you confined them by \seensp{confine-windows}. With this package loaded,
unconfined move is obtained by moving/resizing with Control-Alt mouse buttons,
while Alt mouse buttons keep moving/resizing in confined mode.

\section{Suntools-keys\hfill{\tt suntools-keys.gwm}}
\label{suntools-keys}

Rod Whitby \verb|<rwhitby@adl.austek.oz.au>| made this package to
provide some suntools-like keyboard shortcuts to window management functions:

\begin{description}
\itemtt{L5 or F5} raise window to top, or lower it if it is already on top.
\itemtt{L7 or F7} iconify/ de-iconify window.
\end{description}

\section{Mike Newton's Keys\hfill{\tt mon-keys.gwm}}
\label{mon-keys}

Mike Newton \verb|<newton@gumby.cs.caltech.edu>| has contributed another
package to add keyboard shortcuts to window management functions.

\begin{description}
\itemtt{Button 1 (alone or w/ Alt)} raise or move
\itemtt{Button 3 (w/ Alt-Control)} iconify or raise
\itemtt{F1 (alone)} choose next window
\itemtt{F2 (alone)} choose previous
\itemtt{F1 (w/ alt)} circulate down (no focus change)
\itemtt{F2 (w/ alt)} circulate up (no focus change)
\itemtt{F3 (alone)} open / close
\itemtt{F4 (various)} change window sizes (not Emacs!)
\itemtt{F5 (alone)} raise 
\itemtt{F11 or F9 (alone, in root)} emergency -- map everything
\itemtt{F12 or F10 (alone)} exec cut buffer, printing results
\end{description}       

\section{Standard pop-up menus\hfill{\tt std-popups.gwm}}
\label{std-popups}

This package implements a very simple pop-up menu package. The variables
\verb"window-pop-items", \verb"icon-pop-items", and \verb"root-pop-items"
contains a list of menu item which be used after reading user
\verb".profile.gwm" to build the actual menus\footnote{the actual menu will be
build by loading the package whose name is defined by the value of the
variable \verb"menu.builder", thus alternative menu packages are thus free to
redefine this value.},
which will be named \verb"window-pop", \verb"icon-pop", and
\verb"root-pop"\footnote{if the user defines any of this variables in his
profile, it overrides the building of the corresponding menu from the lists.}.

You can then insert or delete items in this list at will. Nil entries in this
list will just be skipped by the actual menu creation routine. You may want to
use the function \seeref{insert-at}. Dvrooms and vscreen are example of
packages adding menu items in the standard menus.

Menu items can be created with the help of the following functions:

\begin{description}

\itemtt{\verb"(pop-label-make <Label>)"} 
to create an inactive label on top of the menu, 
where \verb"Label" is the string to be displayed as the title of the menu.

\itemtt{\verb|(item-make <Label> <Expr>)|} 
to create a label triggering a {\WOOL} function call where \verb"Label" is the
string to be displayed as the item of the menu, and \verb"Expr" is {\WOOL}
code which will be evaluated when releasing the button in the item.

\itemtt{\verb|(multi-item-make <item-desc>)|} where \verb"item-desc" can be of
the form:
\begin{description}
\item[\verb|<Label>|] creates an insensitive label with this \verb|<Label>| as
text.
\item[\verb|(<Label> <Expr>)|] creates a button with text
\verb|Label| triggering the evaluation of the wool expression \verb|Expr|.
\item[()] leaves an extensible space.
\end{description}

\end{description}

{\bf Note:} in fact, in the preceding functions, any \verb|<Label>| can be in
fact either a string, an already built pixmap which will be used as-is, or
{\WOOL} code that will be evaluated and must return a pixmap which will be
used to build the menu item.

For instance, the default window menu is the list:

{\exemplefont\begin{verbatim}
        '((item-make "iconify" (iconify-window))
            (item-make "Exec cut" 
                       (execute-string (+ "(? " cut-buffer ")")))
            (item-make "client info" (print-window-info))
            (item-make "redecorate" (re-decorate-window))
            (item-make "kill" (if (not (delete-window))
                                  (kill-window)))
            ))
\end{verbatim}}

Moreover, you can control the appearance of the label and the items of the 
menu by the following variables:

\begin{description}
\itemtt{pop-item.font} font of the items
\itemtt{pop-item.foreground} color of their text
\itemtt{pop-item.background} color of their background. Due to the simple menu
item  highlighting code in this package, all items must have the same colors
\itemtt{pop-label.font} font of the labels on top of menus
\itemtt{pop-label.foreground} color of their text
\itemtt{pop-label.background} color of their background
\end{description}

\subsubsection{Default action}

Menus can have a default action, i.e.\ wool code which is triggered if the user
lets go the mouse button before the menu appears. Default actions should be as
harmless as possible, of course. They can be set by 

\begin{verbatim}
(menu-default-action <Menu> <Expr>)
\end{verbatim}
where \verb|<Menu>| is the menu (\verb"window-pop", \verb"icon-pop", or
\verb"root-pop"), and \verb|<Expr>| is the code to be executed.

\begin{verbatim}
(menu-default-item <Menu> number)
\end{verbatim}
sets the item in which the mouse cursor is when popping up the menu (defaults
to first item).

\section{FrameMaker support\hfill{\tt framemaker.gwm}}
\label{framemaker}

This file, that you can copy in your private gwm directory and modify, attempts
to provide some support for framemaker (v3.0) windows, i.e:

\begin{itemize}
\item allow clean de-iconification of dialog boxes by framemaker (such as
paragraph format). \seesnp{map-on-raise}
\item fixes framemaker window placement to make them appear near the mouse
\item provide relevant icon names for framemaker dialogs (they had none)
\item redefine windows title colors
\end{itemize}

\section{Gosling Emacs mouse support\hfill{\tt emacs-mouse.gwm}}
\label{emacs-mouse}

This package implements a way to use the mouse with the {\bf Gosling} emacs,
sold by {\bf Interpress}. You will need to load the emacs macros contained
in the {\tt gwm.ml} file included in the distribution in your emacs. Then,
in a window decorated with the {\tt simple-ed-win} package, pressing
{\bf Control} and:

\begin{description}
\item[left mouse button] will set the emacs text cursor under the mouse
pointer
\item[middle mouse button] will set the mark under the mouse pointer
\item[right mouse button] will pop a menu of commonly-used emacs functions
(execute macro, cut, copy, paste, go to a C function definition, re-do last
search)
\end{description}

Clicking in the mode lines will do a full screen recursive edit on the
buffer if not in a target and in the targets:

\begin{description}
\item[{\tt [EXIT]}] will delete the window if it is not the only one on
the screen, or do an {\tt exit-emacs}
\item[{\tt [DOWN]}] will scroll one page down the file
\item[{\tt [ UP ]}] will scroll one page up the file
\end{description}

This package is included rather as an example of things that can be done
to work with old non-windowed applications than as a recommended way of
developing code.

\section{The customize function}
\label{customize}

{\usagefont\begin{verbatim}
(customize deco screen window-description
           variable1 value1 variable2 value2...)
\end{verbatim}}\usageupspace

Most following sample window and icon decorations can be  tailored in a
global way by setting global variables in your \verb|.profile.gwm| before
using the decoration, but these variable can be set individually to
decorations by use of the customize function. For instance, since the
simple-icon documentation tells you that title is added to icons according to
the value of the \verb|simple-icon.legend| global variable, you can say that
you do not want legends under your icons, except for xclocks by:

{\exemplefont\begin{verbatim}
        (set-icon-window XClock simple-icon)
        (setq simple-icon.legend ())
        (customize simple-icon any XClock 
                   legend t)
\end{verbatim}}

Customize works by defining the customization items in the environnement of
the decoration. Thus, 
{\exemplefont\begin{verbatim}
        (customize simple-win any XClock tile t)
\end{verbatim}}
will set the background tile of decoration items to t (transparent), which in
the case of simple-window will only leave the label apparent.

{\bf Note:} In current version, only \verb|simple-win|, \verb|simple-icon|,
and \verb|term-icon| decorations support the \verb|customize| function.

The customization arguments can be given as a single list argument. In other
words, both following calls are equivalent:

{\exemplefont\begin{verbatim}
        (customize simple-icon any XClock legend t 
                   background (color-make "green"))
        (customize simple-icon any XClock 
                   (legend t 
                    background (color-make "green")))
                    
\end{verbatim}}

{\bf Note:} Moreover, customization values can be also given to decorations
which support the customize protocol as arguments (do not forget to quote the
variable names, the decoration functions evaluate their arguments). Thus we
can define a new decoration \verb"clock-deco", and use it afterwards just as
another decoration with the same results as the preceding examples:

{\exemplefont\begin{verbatim}
        (require 'simple-icon)     ; simple-icon must be defined
        (setq clock-deco 
              (simple-icon legend t 
                           background (color-make "green")))
        (set-icon-window XClock clock-deco)                 
\end{verbatim}}

{\bf Warning:} consecutive calls to \verb|customize| on the same
window descriptions
overrides descriptions, but do not append to them. In the following case:
{\exemplefont\begin{verbatim}
        (customize simple-win any XClock background (color-make "green"))
        (customize simple-win any XClock legend "bottom")
\end{verbatim}}
the second line will make the system forget the first line.

\section{Customization via menus\hfill{\tt custom-menu.gwm}}
\label{custom-menu}

This package, written by Anders Holst, is an attempt to
make it possible to change most customizable variables in {\GWM} via
menus instead of by editing a text file. The root menu alternative
{\bf Customize} will lead into a menu (or ``dialogue'') hierarchy, in which
each loaded package will be represented by a submenu, containing
editable slots for all customizable variables in the package. Changing
a variable should in most cases show an effect immediately in the
environment. The changes will also be saved in a file \verb".customize.gwm"
between {\GWM} sessions. 

To use this in the standard profile, load the file
\verb"custom-install.gwm" at the very beginning of your \verb".profile.gwm". In
the FVWM profile customization menus are already included, and in the
VTWM profile they can be included by editing \verb"vtwm.gwm" so that
\verb"custom-install" is loaded just before the heading ``User Profile'' (the
relevant line is already there, just uncomment it).

Certainly, customization menus work best with packages that are
adapted to them. With a call to \verb'custom-install-symbols' a {\GWM} package
can declare which variables are customizable, and with a call to
\verb'custom-install-hook' a piece of {\WOOL} code can be given that is run
whenever any variable in the package is changed (to give immediate
feedback of the change in the environment). However, since most {\GWM}
packages are currently not adapted to customization menus in this way,
some tricks are done by \verb"custom-install.gwm". It is assumed that all
variables declared with \verb'defaults-to' are supposed to be
customizable. It also knows about some packages, for which it adds
hooks to call when variables change. The packages that are most
adapted to customization menus are the FVWM windows, icons, and
menus. The virtual screen package, the icon manager, and the VTWM
windows, icons, and menus, also work fairly well. On the other hand,
windows that are instead customized by the \verb'customize' function
described above are not affected at all by these customization menus,
and changes to window decorations that cache their descriptions (like
\verb"simple-win") may not take effect until {\GWM} is restarted.

There are some further details that must be considered to use
customization menus. Many packages store fonts and colors as their raw
X IDs in the variables, rather than the names of those fonts or
colors. But a raw ID is of course not convenient for the user to
provide, and meaningless between sessions. Therefore a special
construct must be used when specifying fonts, colors, and similar
objects, in the customization menus. If the first character in the
value field of a variable is a comma (\verb|,|) the rest of the value is
interpreted as {\WOOL} code to run to get the real value. Thus all
colors should be input in the menus as \verb',(color-make "yellow")', and
fonts as \verb',(font-make "fixed")'. 


\section{Pick a window with the mouse\hfill{\tt pick.gwm}}

This file provides a quite handy way for the user to select a window
with the mouse. The main function is {\tt (with-picked EXPR)} which first
lets the user select a window, and then runs EXPR on the selected
window. This can be used from eg.\ a root menu, to implement the style
of first selecting in the menu what to do, and then what window to do
it to. 

You can also use the more basic function {\tt (pick-window)} which
returns the wob number of the picked window. This function considers
the variable {\tt cursor}, as the cursor to show during picking.

\section{Sample window decorations\hfill{\tt *-win.gwm}}
\label{standard-decorations}

These are standard window decorations which can be used via the
\verb"set-window" function of the standard profile. They can be found in
files whose names end in {\tt -win.gwm} in the distribution directory of
{\GWM}.

\subsection{Simple window\hfill{\tt simple-win.gwm}}
\label{simple-win}

\centerline{\texpsfig{simple-win.id}{144}{77}}

This is a really simple window decoration with only a title bar on top of
the window. The name of the window is centered in the bar. The title bar and
the name of the window can change appearance when they become ``active'' (i.e.\ 
have the keyboard focus).

This style is customizable by setting the following variables at the top
of your .profile, before any call to \verb"set-window":

\begin{description}
\itemtt{simple-win.font simple-win.active.font} 
fonts used for printing the title
\itemtt{simple-win.label.borderwidth simple-win.active.label.borderwidth} 
borderwidth of the title plug in the bar
\itemtt{simple-win.background simple-win.active.background} 
background color of the title bar
\itemtt{simple-win.label.background simple-win.active.label.background} 
background color of the title plug
\itemtt{simple-win.label.foreground simple-win.active.label.foreground} 
pen color to draw window name in the title plug
\itemtt{simple-win.label.border simple-win.active.label.border} 
color of the border of the title plug in the bar
\itemtt{simple-win.label}
a lambda of one argument, the title of the window, that should return the
title to use in the label
\itemtt{simple-win.legend} a string to know where to put the window title. Can
be "top", "left", "right", "bottom", top being the default.
\itemtt{simple-win.lpad simple-win.rpad}
lpad (left padding) and rpad (right padding) are two numbers specifing the
number of elastic spaces to put before and after the label. The default is 1
and 1, centering the label.
\end{description}

As you can see, each variable comes in pair, one for ``inactive'' state, the
other for ``active'' state. For each of them, the ``active'' one can bet set
to \verb|()|, which means just use the same value as the ``inactive'' value.

Since this decoration supports the \verb|customize| function, all the above
values can also be set via the customize function, or as arguments to the
function \verb|simple-win| itself. In these cases, not that you must use the
name of the variables without the \verb|simple-win.| prefix, e.g.\ you could
have all simple-win windows with title font written in black, except for
XClock by the calls:

{\exemplefont\begin{verbatim}
        (setq simple-win.active.label.foreground black)
        (customize simple-icon any XClock
                   active.label.foreground (color-make "green"))
\end{verbatim}}

Or we can remove the Netscape: prefix on netscape titles by:
{\exemplefont\begin{verbatim}
        (customize simple-win any Netscape
            label (lambdaq (s) (match "Netscape: \\(.*\\)$" s 1)))
\end{verbatim}}

\subsection{Simple editable window\hfill{\tt simple-ed-win.gwm}}
\label{simple-ed-win}

\centerline{\texpsfig{simple-ed-win.id}{221}{101}}

This decoration has a titlebar on top of it, including an iconification
plug and an editable name plug. Moreover the whole border changes color to
track input focus changes.The look of this
frame can be altered by setting the following variables:

\begin{description}
\itemtt{icon-pixmap} to a pixmap used as an iconification button.
\itemtt{simple-ed-win.borderwidth} to the width in pixels of the 
sensitive border of the window
\itemtt{simple-ed-win.font} to the font used for printing the title.
\itemtt{simple-ed-win.active} to the color of the top bar and border
 for the window having the keyboard focus (defaults to darkgrey).
\itemtt{simple-ed-win.inactive} to the color of the top bar and border
when the window do not have the keyboard focus (defaults to grey).
\itemtt{simple-ed-win.label.background} background color of the name.
\itemtt{simple-ed-win.label.foreground} color of text of the name.
\end{description}

When you click in the icon button at the left of the titlebar (whose pixmap
can be redefined by setting the global variable \verb"icon-pixmap" to a
pixmap) with the left button, the window is iconified. If you click with the
middle button, you will be able to drag the outline of the icon and release
it where you want it to be placed.

If you double-click a mouse button, or do a click with the {\bf control} and
{\bf alternate} keys depressed, in the editable name plug at the right of
the titlebar, you will be able to edit the name of the window (and the
associated icon name) by a simple keyboard-driven text editor whose keys
are are given as strings in the following variables:

\begin{description}
\itemtt{edit-keys.return} to end edition (defaults to \verb|"Return"|).
\itemtt{edit-keys.delete} to wipe off all the text (defaults to 
\verb|"Delete"|).
\itemtt{edit-keys.backspace} to erase last character (defaults to 
\verb|"Backspace"|).
\itemtt{{\em any key}} to be appended to the text.
\end{description}

The plug will invert itself during the time where it is editable. You quit
editing by pressing {\bf Return}, double-clicking in the plug or exiting the
window.

This decoration style also supports the \verb"emacs-mouse" package.

\subsection{Frame\hfill{\tt frame-win.gwm}}
\label{frame-win}

\centerline{\texpsfig{frame-win.id}{154}{75}}

This decoration consists in a frame around the window. The look of this
frame can be altered by setting the following variables:

\begin{description}
\itemtt{look-3d} to {\tt t} to have a ``3D-looking'' frame (left figure) 
instead of the 2d-looking one (right figure).
\itemtt{frame.top-text} to an object which will be evaluated to yield the
text to be put on top of the frame
\itemtt{frame.bottom-text} to an object which will be evaluated to yield the
text to be put on the bottom of the frame, for instance:
{\exemplefont\begin{verbatim}
        (setq frame.bottom-text '(machine-name))
\end{verbatim}}
\itemtt{frame.pixmap-file} to the prefix of the 8 bitmaps (or pixmaps) files
used to build the frame. The suffixes will be {\tt .tl .t .tr .r .br .b .bl
.l}, clockwise from upper left corner.
\itemtt{frame.pixmap-format} to the format of the files: \verb"'bitmap"
(default) or \verb"'pixmap"
\itemtt{frame.bar-width} to the width of the four bars (should match the
pixmap files)
\itemtt{frame.inner-border-width} to the inner border width
\end{description}

\subsection{timeout-win\hfill{\tt timeout-win.gwm}}
\label{timeout-win}

{\tt timeout-win} allows you to specify a command to be applied to a window
{\tt N} seconds after its creation. Very useful to get rid of unwanted pop-ups
such as XMH mime requesters each time I go into a mail error message...

It is implemented as a decoration modifier. It will add the timeout
functionality to any existing window decoration.  

{\bf IMPORTANT:} the UNIX command {\tt gwmsend} must be installed in your
PATH. Its source can be found in the directory {\tt contrib/gwmsend} in the
{\GWM} distribution.

{\bf USAGE:} {\tt (timeout-win <decoration> options...) }\\
where options are:
\begin{description}
\item[{\tt delay}] specifies the delay in seconds before the action takes
                 place. defaults to 3 seconds. 0 means that the command
                 is run immediately, so gwmsend is not needed
\item[{\tt command}] a wool function name that will be executed without
                 arguments in the context of the window if it is still 
                 there. defaults to {\tt delete-window}
\end{description}

NOTE: you must quote the delay and command keywords, e.g.:
{\exemplefont\begin{verbatim}
(require 'timeout-win)                  ; load it if wasnt there
                                        ; mime popups from xmh
(set-window Xmh.confirm 
  (timeout-win simple-win 'delay (if (= window-size '(370 70)) 0 10)))
\end{verbatim}}

In the above I discriminate the popup to put away immediately by its
size. Popups whos size is 370x70 will be removed immediately, 
the other have a 10s timeout. Another example is to iconify Xrn Information 
window after 2 seconds:
{\exemplefont\begin{verbatim}
(set-window XRn.Information
  (timeout-win simple-win 'delay 2 'command "iconify-window"))
\end{verbatim}}

This pseudo-decoration obeys the {\bf customize} protocol under the class name
{\tt TimeoutWin} and name {\tt timeout-win}, so that you can say 
{\exemplefont\begin{verbatim}
(customize simple-win any Xmh.confirm 'font fixed)
(customize timeout-win any Xmh.confirm 'command "lower-window")
\end{verbatim}}

If you want to be able to set a command to save a window from its coming 
death, you can make a button or menu item executing 
{\tt (timeout-win.remove-exec)} in the context of the window.
The timeout is implemented by forking a shell command consisting of a {\tt
sleep N} command followed by a call to {\tt gwmsend} sending back to {\GWM}
the order in {\WOOL} to destroy the window (or perform the command).


\section{Sample icons\hfill{\tt *-icon.gwm}}
\label{standard-icons}

These are standard icon windows descriptions which can be used via the
\verb"set-icon-window" function of the standard profile. They can be found in
files whose names end in {\tt -icon.gwm} in the distribution directory of
{\GWM}.

\subsection{Simple icon\hfill{\tt simple-icon.gwm}}
\label{simple-icon}

This icon consists in an (optional) image and the icon-name of the
window below it. The image is by priority order:

\begin{description}
\item[the user pixmap] set by the \seeref{set-icon} call
\item[the window] the client has set in its hints to the window manager to
use as an icon
\item[the pixmap] the client has set in its hints to the window manager to
use for its icon
\end{description}

Used context variables:

\begin{description}
\itemtt{simple-icon.font} for the font used to display the icon name.
\itemtt{simple-icon.legend} boolean flag telling to add the icon name under
the icon for the application. Defaults to \verb"()". Can be be "top" "bottom"
"right" "left" according to which side you want it. \verb|t| is a shortcut for
"bottom".
\itemtt{simple-icon.foreground} pen color of the icon name
\itemtt{simple-icon.background} background color of the icon
\itemtt{simple-icon.borderwidth} borderwidths used
\itemtt{simple-icon.borderpixel} color of the borders
\itemtt{stretch} allows the legend to expand past the icon graphic itself
without being clipped by it. \verb|stretch| can have the value \verb|t| for
centered, "top" "bottom" "right" "left" for the direction to extend to.
\itemtt{simple-icon.label}
a lambda of one argument, the name of the icon, that should return the
title to use in the label. See simple-win for examples.
\end{description}

This decoration supports the \seeref{customize} function.

\subsection{Terminal display icon\hfill{\tt term-icon.gwm}}
\label{term-icon}

\centerline{\texpsfig{term-icons.id}{151}{26}}

This icon looks like a small computer display with the window name inside
it. Note that the icon resizes itself to adjust to the dimensions of the
displayed name.

Used context variables:

\begin{description}
\itemtt{term-icon.font} for the font used to display the icon-name.
\itemtt{term-icon.foreground} for the color of text and decorations (defaults
to black)
\itemtt{term-icon.background} for the background color (defaults
to white)
\itemtt{term-icon.borderwidth} defaults to 0
\itemtt{term-icon.borderpixel} defaults to black
\end{description}

This decoration supports the \seeref{customize} function.

\section{Utilities\hfill{\tt utils.gwm}}
\label{utils}

This package implements some useful functions for the {\WOOL} programmer. It
is automatically loaded by the standard profile.  List this file to see the
current ones.

\subsection{Standalone Buttons: {\tt place-3d-button}}
\label{place-3d-button}

{\usagefont\begin{verbatim}
(place-3d-button text pencolor maincolor wool-expression)
(place-button text pencolor ulb normal pressed lrb 
              wool-expression)
\end{verbatim}}\usageupspace

Will create and place as an independent window (of client class \verb|Gwm|,
client name \verb|button|, and window name \verb|text|) a 3d-looking window
with visual feedback when pressed, which will execute the
\verb|wool-expression| when pressing any button in it. \verb|pencolor| is the
color of the text, and \verb|maincolor| must be one of the shaded colors in
the \verb|/usr/lib/X11/rgb.txt| file\footnote{for instance, \verb|pink| is
such a color, since the color table contains the entries \verb|pink1|,
\verb|pink2|, \verb|pink3|, and \verb|pink4| in clear-to-dark order. The full
list of such colors is in the \verb|shaded-colors| list.}.

If you want to tailor colors yourself, use the \verb|place-button| form, where
you must choose the upper-left and lower-right border colors as well as the
background colors of the button when normal and depressed.
\verb|place-3d-button| calls in fact {\tt (place-button text pencolor
maincolor1 maincolor2 maincolor3 maincolor4 wool-expression)}

To have a demo of this feature, you can execute the \verb|(demo-button)|
function, which will make a button cycling through all the colors in the
\verb|shaded-colors| list.

You can implement different behaviors depending on button pressed and modifier
by looking at the value of \verb|(current-event-modifier)| and
\verb|(current-event-code)| in the \verb|wool-expression| body. Look at the
end of the file \verb|profile-colas.gwm| for examples.

The following code will create a button that will toggle iconification of all
the big postits on my screen, the button being in the thistle range of colors.

{\exemplefont\begin{verbatim}
      (place-3d-button "Post Big"
        black 'thistle
        '(for window (list-of-windows) 
          (if (= window-name 'PostItNoteBig)
            (if window-is-mapped (iconify-window)
              (progn (map-window)(raise-window))
      ))))
\end{verbatim}}
 
\centerline{\texpsfig{PostBig.id}{356}{82}}

\subsection{Matching windows by regular expressions: {\tt match-windowspec}}
\label{match-windowspec}

{\usagefont\begin{verbatim}
(match-windowspec windowspec)
\end{verbatim}}\usageupspace

Where \verb|windowspec| is a property list with \verb|'client-class|,
\verb|'client-name|,  and \verb|'window-name| as possible tags. Windowspecs 
can themselves contain regular expressions.

{\exemplefont\begin{verbatim}
        ((list 'client-class "XTerm" 'window-name ".*build"))
\end{verbatim}}
will match (return \verb|t|) all xterms whose window name ends in \verb|build|.

This code was provided by Jay Berkenbilt \verb|<qjb@ATHENA.MIT.EDU>|.

\subsection{insert-at}
\label{insert-at}

{\usagefont\begin{verbatim}
(insert-at element list position)
\end{verbatim}}\usageupspace

Utility function to insert an element \verb"element" in a list \verb"list" at
position \verb"position". The  list is physically modified in place. Useful to
insert items in menu lists.

\section{User-contributed utilities}
\label{user-contrib-utils}

Some user-provided useful little hacks or programming helps have been
included too.

\subsection{Near-mouse\hfill{\tt near-mouse.gwm}}
\label{near-mouse.gwm}

This placement function was provided by Eyvind Ness \verb|<eyvind@hrp.no>|.
Saying:
{\exemplefont\begin{verbatim}
        (require 'near-mouse)
        (set-placement XPostit near-mouse)
\end{verbatim}}
will make all newly created XPostit windows pop up near the mouse.

\section{Programming Styleguide for the standard distribution}
\label{standard-styleguide}

The styleguide to write decorations is to be written. Until then, look at
existing files such as {\tt .gwmrc.gwm, .profile.gwm, simple-ed-win.gwm} to
see what is the current style. We will appreciate all feedback to these
conventions, which are not settled yet.

The main idea is that a decoration package \verb"foo" should, when loaded,
define a \verb"foo" function which, once executed will return the appropriate
decoration, using the pre-defined behaviors.

All persistent variables of the packages should be prefixed by the package
name, as in \verb"foo.bar".

Do not forget to define in fact one decoration per screen or be cautious not
to mix colors, pop-ups, pixmaps and cursors from screen to screen. Use 
\verb"defname screen." to declare screen-specific variables.

The user should be allowed to customize the decoration by setting global
variables in its \verb".profile.gwm" file, which will be interpreted during
the loading of your package.

The fsm you make for your package should be constructed from the behaviors
defined in \verb".gwmrc.gwm", such as standard-behavior,
standard-title-behavior, window-behavior, icon-behavior, root-behavior, or
already built fsms such as fsm, window-fsm, icon-fsm, root-fsm.

All values you want to attach to windows or wobs should be put as properties
in the property-list of the wobs, by calls to 
\verb"(## 'key wob value)"

The main idea is, if you must modify {\tt .gwmrc.gwm} to code your window
decoration, mail us your desiderata and/or enhancements, so that we should
be able to keep the same .gwmrc for all decorations.
I maintain mailing lists for people to exchange ideas about {\GWM}. Mail me
a request if you are interested at \verb"gwm@mirsa.inria.fr".

\subsection{The {\tt simple-win} example}

In the distribution, you can look at the \verb|simple-win.gwm| file to see how
to define a proper decoration. In this file you will see how to define a
decoration that supports multiple screens, and some user customization via the
\verb|customize| function. The trick is not to forget to put at build time all
necessary information (in the \verb|property| field of the window) for using
later during normal operation, where all code is triggered by the decoration
\verb|fsm|s.

\section{Other profiles}

Other nice profiles have also been developed in parallel to the standard
profile, but they have not been integrated yet, i.e.\ they need their own
{\tt .gwmrc.gwm}.

\subsection{The MWM emulation package\hfill{\tt mwm.gwm}}

\centerline{\texpsfig{mwm-wins.sid}{350}{89}}

{\bf Frederic Charton} made this profile emulating the {\bf M}otif
{\bf W}indow {\bf M}anager. To use it, you must give the command line 
option {\bf -f mwm} to {\GWM}.

You can customize it by copying in your
\verb"gwm" directory (in you GWMPATH) the files:

\begin{description}
\itemtt{mwmrc.gwm} all the resources settable in ``.mwmrc'' for {\sc Mwm}
are also settable here, except for the menus.
\itemtt{mwm-menusrc.gwm} description of the menus.
\itemtt{mwmprofile.gwm} miscellaneous wool customizations (needs {\WOOL}
knowledge)
\end{description}

and editing it. You may want to get the {\sc Mwm} manual for the description
of all the available functions. For instance, to set the input focus management
from ``click to type'' (default) to ``real estate'' (input focus is always
to the window underneath the pointer), edit \verb"mwmrc.gwm" and change
the line \verb"(: keyboardFocusPolicy 'explicit)" to 
\verb"(: keyboardFocusPolicy 'pointer)".

{\bf Warning:} This profile is still mono-screen, i.e.\ to manage 2 screens
on your machine, you must run 2 gwms, for instance by:
{\exemplefont\begin{verbatim}
        gwm -1 -f mwm unix:0.0 &
        gwm -1 -f mwm unix:0.1 &
\end{verbatim}}

\subsection{The TWM emulation package\hfill{\tt twm.gwm}}

\centerline{\texpsfig{twm-wins.sid}{273}{155}}

{\bf Arup Mukherjee} (\verb"arup@grasp.cis.upenn.edu") made a {\sc
Twm} emulator. To use it, you must give the command line 
option {\bf -f twm} to {\GWM}.

{\bf Note:} This package seems to be made obsolete by the {\tt vtwm} package
by {\bf Anders Holst} (\verb"aho@nada.kth.se"), see below.

You can customize it by copying in your \verb"gwm"
directory (in you GWMPATH) and editing the files:

\begin{description}

\itemtt{twmrc.gwm} Contains numerous options (mainly colors) that can be
set from here. The file is well commented, and most of the color
variables have self-explanatory names. You can also specify from here
whether or not the icon manager code is to be loaded.
It also contains definitions for the three variables
\verb"emacs-list", \verb"xterm-list", and \verb"xload-list". 
The specified hostnames are
used to build menus from which you can have gwm execute the respective
command on a host via the ``rsh'' mechanism (note that your .rhosts
files must be set up correctly for this to work). Note that unlike
with the standard profile, the rxterm and rxload scripts are {\bf NOT}
used.

\itemtt{twm-menus.gwm} The contents of all the menus are specified
here. To change more than the xterm, xload, or emacs lists, you should
modify this file.

\itemtt{twm.gwm} The only things that one might wish to customize here are the
behaviors (which specify the action of a given button on a given
portion of the screen)
\end{description}

\subsection{The VTWM emulation package\hfill{\tt vtwm.gwm}}

This profile, written by {\bf Anders Holst} (\verb"aho@nada.kth.se"),
is a thorough extension and revision of the TWM profile. It tries to
provide most of the look and options you have in the the real {\sc
Vtwm} and {\sc Tvtwm} window managers. To use it, give the command
line option {\bf -f vtwm}.

All user customization is done in the file {\tt vtwmrc.gwm}. This
includes colors and general appearance, menus, and behaviors. Copy
{\tt vtwmrc.gwm} to your home directory and make the appropriate
changes. The file is thoroughly commented, and should be
self-explaining.

This profile uses the virtual screen package {\tt virtual.gwm} (see
section~\ref{virtual}). You can move around on the virtual screen by
clicking in the map, in the ``doors'', on the pan lists in the edges
of the screen, or by the arrows together with some suitable modifiers
({\sc Alt} is default). 

The profile also provides one or multiple icon managers, optionally
together with normal icons. See the examples in {\tt vtwmrc.gwm} to
see how multiple icon managers are set up. (These icon managers can be
used in other profiles as well, by loading the file {\tt
load-icon-mgr.gwm}. Look in this file for details.)

The VTWM profile honors the use of the standard functions {\tt
set-window}, {\tt set-icon}, {\tt set-icon-window}, {\tt
set-placement} and {\tt set-icon-placement}. Also, the VTWM windows
and icons are compatible with, and can thus be used in, the standard
profile. 

\subsection{The FVWM emulation package\hfill{\tt fvwm.gwm}}

The FVWM profile is mainly just the VTWM profile with windows, icons,
and menus looking as in the {\sc Fvwm} window manager. The virtual
screen package (\verb"virtual.gwm", section~\ref{virtual}) is used,
and can be made to pan in a way similar to that in the real {\sc
Fvwm}. However, the characteristic ``Good Stuff'' panel of {\sc Fvwm}
is currently not included. To use the FVWM profile, give the command
line option {\bf -f fvwm}. 

This profile uses the \verb"custom-menu" package
(section~\ref{custom-menu}) for its customization. Select {\bf Customize}
in the root menu to enter the customization menu hierarchy. 

The FVWM profile honors the use of the standard functions {\tt
set-window}, {\tt set-icon}, {\tt set-icon-window}, {\tt
set-placement} and {\tt set-icon-placement}. Also, the FVWM windows
and icons can be used separately from this profile in for example the
standard profile. 

\subsection{The fast profile\hfill{\tt fast.gwm}}
\label{fast}

This is a minimal profile, without any window titles, comparable to the
obsolete window manager {\bf uwm}. Useful for quickly restarting a simple
window manager while debugging, or for just browsing the code as an example.

\section{Troubleshooting}

To debug a {\WOOL} program, you can:

\begin{itemize}

\item use the \verb"trace" function to trace code execution or evaluate an
expression at each expression evaluation.

\item read, execute, and print {\WOOL} code by selecting it and using
the {\bf Exec cut} (for execute cut buffer) menu function.

\item use the \verb"-s" command line option to synchronize X calls, if you want
to know where you issue a non-legal X call.

\item compile {\GWM} with the -DDEBUG compile option, which will turn on many
checks (stack overflow, malloc checks, etc \ldots ) in case you manage to make
{\GWM} crash.  

\item If gwm appears to freeze, it might be because of a bus
error. Running gwm under a debugger such as \verb|gdb| or \verb|dbx| to see
where it crashes.

\end{itemize}