WOOL Reference manual

; any text up to the end of line

Comments in WOOL begin with a semicolon and end at the end of the line.

(! command arguments...)

Executes (forks) the command given in string with its given arguments, and does not wait for termination (So you don't need to add a final ``&''). For instance, to open a new ``xterm'' window on the machine where GWM is running, execute (! "xterm"). This is an interface to the execvp call: the command is searched for in the PATH variable, and executed via /bin/sh if it is a command file, directly executed otherwise.

        (! "xterm")                       ; machine-executable code
        (! "rxterm" "foobar")             ; or shell script
        (! "xterm" "-display" "bar:0.1")  ; with arguments
        (! "/bin/sh" "-c" "for i in a b c;do xclock -display $i:0;done")
                                          ; needs a shell for commands

(# n list [object])
(# atom list [object])

Gets (or sets to object if present) the n-th element of the list list (starting with 0). Increases the list size if needed (with nils). When the first argument is an atom, this references the element just after the atom in the list, thus providing the ability to maintain classical Lisp ``property lists''.

Note that this function does not do a physical replacement, and constructs a new list with the list argument. (see replace-nth)

        (# 2 '(a b c d))                ==>     c
        (# 2 '(a b c d) 'foo)           ==>     (a b foo d)
        (# 'x '(x 4 y 6))               ==>     4
        (# 'y '(x 4 y 6) 8)             ==>     (x 4 y 8)
        (# 'z '(x 4 y 6) 10)            ==>     (x 4 y 6 z 10)
        (# 6 '(a b c d) 'foo)           ==>     (a b c d () () foo)

In fact the index can be any Lisp object, but as the list is scanned to find the same object (EQ predicate), using atoms is the safest way.

        (# "foo" '("foo" 1))            ==>     ()
        (progn (setq name "foo")
                (# name (list name 1))) ==>     1

Note: The second argument can also be a:

• wob in which case the contents of the wob-property is taken as the list.

• symbol which must evaluate to a list, which is then used by the function.

##
replace-nth   ---   physically replaces an element of a list	EXPERT

(## n list object)
(## atom list object)

This function physically replaces an element of the list, which is located as with the # function. It returns the modified list.

This provides a way to implement variable-sized lists, such as linked lists, which are the real lists in the Lisp world, but should be used with care, as you are able to create circular references with it. To allow the WOOL garbage collector to handle correctly circular lists, you should always explicitly set to () the fields of a circular cell before disposing of it.

Example: a circular list with cells of the form (car cdr)

        (setq elt2 '(b ()))             ; second cell of list
        (setq elt1 (list a elt2))       ; first one pointing to second
        (## 1 elt2 elt1)                ; we make a circular list

        (## 1 elt2 ())

Note: The second argument can also be a:

• wob in which case the contents of the wob-property is taken as the list.

• symbol which must evaluate to a list, which is then used by the function.

        (setq l '(a 1))
        (setq l-bis l)                  ; l and l-bis points to the same list
        (## 'b 'l 2)                    ; only l is modified in place
        l                               ==> (a 1 b 2)
        l-bis                           ==> (a 1)

(elt1 elt2 ... eltN)

This notation is used to describe a list of N elements, as in other Lisp languages. Note that WOOL is not a true Lisp dialect since lists are represented internally as arrays, allowing for a greater speed and a smaller memory usage in the kind of programs used in a window manager. If you are a die-hard Lisp addict, you can still use CONS, CAR and CDR if you want by defining them as:

        (defun cons (e l) (+ (list e) l))
        (defun car (l) (# 0 l))
        (defun cdr (l) (sublist 1 (length l) l))

Note: The WOOL parser ignores extraneous closing parentheses, allowing you to close top-level expressions in a file by a handful of closing parentheses, such as:

        (defun cons (e l) (+ (list e) l)))))))))))))
        (setq x 1))))))))

()

The nil value, backbone of every Lisp implementation. In Lisp an object is said to be true if it is not nil.

"string"

Strings are surrounded by double quotes. C-style escape sequences are allowed, that is:

Moreover, you can ignore end of lines in strings by prefixing them with \, as in:

        (print "This is a very \
        long string")            ==> This is a very long string

'object
(quote object)

Returns the object without evaluating it. The form 'foo is not expanded into (quote foo) during parsing, but in a ``quoted-expression'' WOOL type for efficiency.

(% n1 n2)
(* n1 n2)
(/ n1 n2)

Returns respectively the modulo, product, and quotient of the integer arguments as a integer.

(+ n1 n2 ... nN)
(+ string1 string2 ... stringN)
(+ list1 list2 ... listN)

Numerically add numbers, concatenate strings or, concatenate lists. Determines the type of the result as being the type of the first argument (() is a list, "" is a string, 0 is a number).

(- n)
(- n1 n2 ...)

Returns the arithmetic opposition or difference of numbers. (- n1 n2 n3 n4) is equivalent to (- n1 (+ n2 n3 n4)).

(= obj1 obj2)
(equal obj1 obj2)

Returns obj1 if obj1 is the same as obj2, nil otherwise. This is the traditional equal predicate of Lisp.

Equality of lists is tested by testing the equality of all their elements.

(< n1 n2)
(< string1 string2)

Compares two numbers or two strings and returns t if argument 1 is inferior and not equal to argument 2 and nil otherwise. Strings are compared alphabetically.

(> n1 n2)
(> string1 string2)

Compares two numbers or two strings and returns t if argument 1 is superior and not equal to argument 2 and nil otherwise. Strings are compared alphabetically.

(? obj1 obj2 ... objN)

Prints the objects, without adding spaces or newlines. Output is flushed at the end of every call to this function. For now, output goes to the stdout stream.

(active-label-make label [font])

Creates a label with string label drawn in the font font. The text will be redrawn on each expose (The active label can also be used to paint a string on a pixmap, see pixmap-make).

Context used:

(allow-event-processing)

When you set passive grabs on ``replayable'' events (see replayable-event), when such event is caught in a fsm, the grab is activated and the server is frozen, in such a way that pointer motions or button states is not tracked anymore. To be able to use a function such as current-mouse-position you must then allow the processing of events by calling this function.

After the call, you will not be able to use ungrab-server-and-replay-event for the event.

Constant

Specifies that no modifier is pressed for a button or key event for use in event descriptions.

(and obj1 obj2 ... objN)

Returns () as soon as an argument is false (nil), t otherwise.

Constant

Matches any modifier or button or key in events. It can be also used in many other functions with appropriate semantics.

(atoi string)

Returns the integer described by string (in base 10).

        (atoi "123")                    ==>     123

(atom string)

Returns the atom of name string. Useful to create atoms with special embedded characters, such as ' or blanks. The inverse function is not necessary since every WOOL function expecting strings in arguments can accept atoms instead, and will take the string of their name.

This should be used when accessing property lists via the # function. For instance if you store properties on machine names (which are strings), you would use the following call to retrieve the color of a xterm for a machine:

        (# (atom machine-name) '(Maalea "Green" Honolua "Blue"))

Numeric variable --- screen-relative      (color)

The value of this global variable is used by many functions as the color of the background. It is a pixel value, such as returned by color-make, and is initially set to the pixel of the color White. Note that a non-nil tile context value overrides the background value.

(bar-make plug/bar1 plug/bar2 ... plug/barN)

Creates a bar of transversal width¹¹ bounded by the current value of bar-min-width and bar-max-width, and containing the N plugs or bars, which are centered in the bar. If a plug is (), it is considered extensible space, which is expanded when the bar stretches to its actual dimensions. The plugs are clipped on the right if necessary.

Context used:

Note that the plugs are evaluated a second time when the bar is physically created, allowing you to give expressions for plugs (quoted to evade the first evaluation of arguments of the bar-make function itself) will evaluate to a plug on the realization of the wob.

For instance, to have the window name in a plug, the bar can be made by:

        (bar-make '(plug-make (label-make window-name)))

For each recursive level of sub-bars, the direction of the bar switches between horizontal and vertical. This means that to make a horizontal sub-bar inside a likewise horizontal parent bar, you need a construct like (bar-make (bar-make ...)).

(bar-make ()) means an explicitly adjustable length bar, which may actually in some situations adjust its width too (see below). For example, left and right bars that have in this sense explicitly adjustable size are broadened to prevent truncation of the title or bottom bars.

1. A bar has explicitly adjustable length if it contains at least one () or an "adjustable width" bar.

2. A bar has "adjustable width" if it contains only (and at least one of) () and explicitly adjustable length bars.

Extra space will be equally divided between all ()s and sub-bars with adjustable width. In case of too little space, truncation will also start equally divided between all () and adjustable sub-bars. First when they have disappeared completely, truncation begins to the right as usual. This means that the (bar-make (bar-make ...)) construct can be used to encapsulate things that are to be truncated together. Actually, provided a borderwidth of zero, this construct has no other physical effect than grouping things in this sense.

If a plug is shaped, this will make a hole trough the whole bar (as opposed to seeing the bar background behind the plug). Currently the only way to create shaped plugs is with pixmap-load.

It is possible to have arbitrary shaped background tilings of a bar, with the value of the global variable tile being a shaped pixmap. The other way is to make a completely transparent background "tiling". This is achieved with the special construct of setting tile to t when constructing the bar (perhaps unintuitive, but...)

{Examples: A icon with a label undeneath can be designed as:

        (with (tile t                 ;; transparent tiling
            borderwidth 0
            inner-borderwidth 2)
          (window-make ()
                  (bar-make ())  ;; bar with adjustable width
                  (bar-make ())
                  (bar-make () label-plug ())
                  center-plug))

Numeric variable      (number)

The values of these global variables are used by the constructors of bars to limit their transversal width, clipping the plugs if necessary. bar-min-width defaults to 1 and bar-max-width defaults to 1000.

Numeric variable      (number)

The value of this global variable is used by the constructors of menus to yield the number of pixels separating two contiguous bars. Default is 4 pixels. Used in menu-make function.

(bell [percent])

Rings the bell on the keyboard, with volume set by the percent numeric argument, which can take values ranging from -100 to 100 (defaults to 0). -100 means lowest volume, 0 means base volume, 100 means full volume.

(bitwise-op n1 n2 ... nN)

Returns the result of the bitwise operator on the N arguments.

        (bitwise-or 1 4)                ==>     5
        (bitwise-and 3 5)               ==>     1
        (bitwise-xor 3 5)               ==>     6

Numeric variable      (number)

Normally, if GWM tries to decorate a non-rectangular (shaped) window, it automatically removes any border on the main window as it is almost always the intended look. But this variable when set overrides this behavior for the rare case where it could be needed.

Numeric variable --- screen relative      (color)

The value of this global variable is used by the constructors of all wobs as the color of their border. It is a pixel value, such as returned by color-make, and is initially set to the pixel of the color Black. It is always overridden by the value of bordertile if not nil.

Variable      (pixmap)

The value of this global variable is used by the constructors of all wobs as the pixmap to display in their border. It is a pixmap object, such as returned by pixmap-make. If set to (), the borderpixel value is used.

Numeric variable      (number)

The value of this global variable is used by the constructors of all wobs to set their border width in pixels. A value of 0 means no border.

(boundp atom)

Returns the (evaluated) atom if it has been defined, () otherwise.

        (setq foo 1)
        (boundp 'foo)                   ==>     foo
        (boundp 'bar)                   ==>     ()

(button number modifier)

Returns a button event matching the X event ButtonPress of button number number, and will verify that the modifier argument was depressed during the click. This event will wait for the corresponding ButtonRelease event before returning.

Number or modifier can take the value any, thus matching any of the values of the corresponding argument. These button events can then be used in the matching part of the transitions of fsms or in the grabs field of a window-make description.

Examples:

(button 1 with-alt)	matches clicking left button of the mouse while keeping the alt key depressed.
(button any with-control)	matches control-clicking with any button

(buttonpress number modifier)

Same as button, but does not wait for the buttonrelease, meaning that the buttonrelease is available for another transition. This can be used to trigger move-window, since this function waits for a button release to terminate.

(buttonrelease number modifier)

Same as button, but only matches a button release. Useful when you cannot wait for a button event, for instance when iconifying a window, because if the window is iconified on a button press, the corresponding release event will be lost (in fact will go to the window underneath)

Numeric variable      (number)

If this flag is set to 1, which is the default, GWM will refuse to set the keyboard focus via the set-focus call to windows having declared that they didn't need the focus. This flag is provided so that you can use clients which set their input hint the wrong way.

(circulate-windows-up)
(circulate-windows-down)

Put the topmost window down, or the lowest window up respectively.

(color-components pixel)

Given a pixel (integer, normally returned by color-make), returns a list of 3 integers, the Red, Green, Blue components of the color. Each of this integer can take values between 0 and 65535.

(color-free pixel)

Frees the entry pixel in the default colormap. pixel must have been the result of a previous color-make call. This is a very dangerous function, since colors returned by color-make can be shared with multiple applications.

(color-make color-name)

Takes a string color-name describing the color by its english name (as found in the rgb.txt system file), and allocates a new entry in the default colormap with a pixel of this color, and returns it if it wasn't allocated before, otherwise just returns the previously allocated pixel if an entry in the colormap already existed. Two consecutive calls with the same argument should then return the same value. A pixel is a number which is the index of the color in the colormap.

This pixel can later be used as values for foreground and background, or in the pixmap-make function. If color is not found, prints a warning, and returns the pixel used for the black color.

Colors can also be specified directly by their RGB¹² values, with the #-convention: if the color-name string begins with a sharp sign, the following characters are taken as hexadecimal digits specifying the most significant part of the Red, Green and, Blue values, with the following syntax: (each letter stands for a digit)

#RGB
#RRGGBB
#RRRGGGBBB
#RRRRGGGGBBBB

        (color-make "DarkSlateBlue")
        (color-make "light grey")
        (color-make "#f00")             ; pixel for red
        (color-make "#300000a076be")

(color-make-rgb red green blue)

This function takes three numeric arguments giving the values of the red, green and blue components of the color which will be returned. Components are scaled between 0 and 65535 (half brightness is 32767 and no light is 0).

(compare n1 n2)
(compare string1 string2)

Compares two numbers or two strings and returns -1, 0 or 1 if its first argument is lesser than, equal to or, greater than the second.

(cond (condition then) [(condition then) ...])

This is the classical ``cond'' Lisp function, returning the evaluation of the ``then'' part of the first true condition.

        (defun fib (n)
            (cond
                ((= n 0) 1)
                ((= n 1) 1)
                (t (+ (fib (- n 1)) 
                        (fib (- n 2))))))

Numeric variable      (number)

If set, during all grabs (either via pop-menu or grab-server) will confine the pointer inside the grabbing wob during the duration of the grab.

Numeric variable      (number)

If set, during all interactive moves or resizes, gwm will ensure that windows stay entirely within screen bounds.

(context-save context)
(context-restore context)

A context is a kind of property list, it is an even-sized list whose even elements are atoms and whose odd ones are their values (see the with function), of the form (var1 val1 var2 val2 ... varN valN). context-save creates a new context where the vali are the result of the evaluation of the var_i in the argument context, whereas context-restore does a (setq vari vali) for each of its variable/value pairs.

Note: the provided vali serves as default for context-save in the case where the corresponding vari is undefined:

        (setq my-context (list 'a 1 'b 2))
        (setq a "foo")                     ; b is undefined
        (print (context-save my-context))
                                        ==>  (a foo b 2)

copy   ---   copies a wool object

EXPERT

(copy object)

Returns a copy of the object argument, which can only be a list for now. This function is flagged as ``Expert,'' because it is of use to people doing physical replacement functions, which are reserved to experts.

(current-event-code)

Returns the code (button or keycode) of the last event received (The one which triggered the transition you are in).

(current-event-from-grab)

If the last event was a crossing or focus event consecutive to a grab set or removed, returns t.

(current-event-modifier)

Returns the modifier (state of shift, control, alternate, ... ) keys that were depressed when the last event occurred (The one which triggered the transition you are in). Note that the combination of two modifiers is expressed by bitwise-oring the modifiers.

(current-event-time)

Returns the time at which occurred the last button, key, crossing, or focus event. Time is expressed as a number of milliseconds.

(current-event-window-coords)

Returns the list of coordinates of the last event, if it was a pointer or a key event, relative to the current client window.

This list has six elements:

WARNING: The position in size increments do not work in the general case, but only for windows having the text widget flush to the bottom right corner of their main windows, like Xterm. There is no fix for it, but this function is a kind of a hack anyways.

(current-event-x)
(current-event-y)
(current-event-relative-x)
(current-event-relative-y)

Returns the x or y coordinate (number) of the mouse during the last event, if it was a key or button event (The one which triggered the transition you are in).

The first coordinates are relative to the root, whereas the last ones are relative to the wob where they occurred.

(current-mouse-position)

Queries the server for the mouse state and returns it as a list of four element where the first element is x, second is y, third is state of modifiers and buttons bitwise-ored, and fourth is the number of the screen where the pointer is.

(current-user-event)

If the last event was an user event, returns the label of the event (the atom that was given as argument to the send-user-event call). Triggers an error if the last event was not a user event.

Variable      (cursor)

The value of this global variable, which must be a cursor returned by a call to cursor-make, is used by the constructors of all wobs to set the appearance of the mouse cursor when the pointer is in the wob. If set to (), the cursor will not change when entering the wob.

This is also used by functions like grab-server, move-window, and resize-window to change the shape of the cursor during a function.

Variables      (cursor)

These values (cursor-NW, cursor-NE, cursor-N, cursor-SW, cursor-SE, cursor-S, cursor-E, cursor-W) defines cursors to be used on the eight directions by some functions, such as resize-window with the mwm-like style (resize-style). The eight corners are respectively: NorthWest, NorthEast, North, SouthWest, SouthEast, South, East and West.

(cursor-make foreground-bitmap-filename 
             mask-bitmap-filename)
(cursor-make cursor-name)
(cursor-make number)

Constructs a mouse cursor with two bitmaps (strings containing the file names). This cursor can then be used in the cursor variable. The bitmaps are files searched for in the same path as in the pixmap-make function.

The convention in use for naming a cursor foo is to name the foreground bitmap as foo-f.xbm and the mask bitmap as foo-m.xbm. This convention is used in the calling of cursor-make with one argument, so that (cursor-make "foo") is equivalent to (cursor-make "foo-f" "foo-m").

You can also define the cursor as one of the predefined ones in the server cursor font by giving its index in the font as the number argument to cursor-make. See the Appendix B of the Xlib manual for the list of available cursors. For instance, ``star trek'' cursor can be made by the call (cursor-make 142). The symbolic names of these cursors are defined in the cursor-names.gwm file. Once this file is loaded, you can for instance use the ``star trek'' cursor by a (cursor-make XC_trek).

Active value      (string)

Its value is the content of the X cut buffer 0, returned as a string. When set, it takes the string argument and stores it in the same cut buffer. This can be used to communicate with clients still using this obsolete way to perform cut-and-paste operations, such as xterm.

(defun function-name (arg1 ... argn) instructions ...)
(defunq function-name (arg1 ... argn) instructions ...)
(lambda (arg1 arg2 ... argn) instructions ...)
(lambdaq (arg1 arg2 ... argn) instructions ...)

Defines a Lisp function and returns the atom pointing to the function. The list of arguments must be present, even if (). If defined by defun, the function will evaluate its arguments before executing, and will not evaluate them if defined by defunq. The return value of an execution of the function is the value returned by the last instruction of its body. de and df are just synonyms for defun and defunq. The lambda call, which evaluates its arguments, defines a function (without binding it to a name) while lambdaq creates a function which does not evaluates its arguments. The two following expressions are equivalent:

        (defun foo(x) (+ x 1))
        (setq foo (lambda (x) (+ x 1)))

When lists are evaluated, WOOL applies the result of the evaluation of the CAR of the list to its CDR, like in the Scheme language. Thus to apply a lambda function to its arguments, just eval the list constructed with the lambda construct and its arguments. The classic Lisp apply function could thus be defined by:

        (defun apply (function list-of-arguments)
            (eval (+ (list function) list-of-arguments)))

Since functions are Lisp objects, to define a synonym of a function, you must use setq. Thus, you can change the meaning of a function easily, for instance to make move-window always raise the window, you would say in your profile:

        (setq original-move-window move-window)
        (defun move-window () 
                (raise-window)
                (original-move-window))

This means also that an atom can only have one value, and (setq move-window 1) will erase the definition of move-window if you didn't save it in another atom.

        (defunq incr (value delta)
                (set value (+ (eval value) (eval delta))))


        (setq x 4)
        (incr x 2)
        (print x)                       ==>     6

Functions taking a variable number of arguments can be defined by providing a parameter name instead of a list of parameters. In the body of the function during its execution, this parameter will be set to the list of the parameters given to the function.

        (defun max l
            (with (max-val 0) 
                (for obj l (if (> obj max-val)
                                  (setq max-val obj)))
                max-val))
        (max)                           ==>     0
        (max 34 65 34 12)               ==>    65

Note: You are not allowed to redefine active values (such as window) or numeric variables (such as foreground), or use them as names for the parameters to the function.

        (defun window (a b) (+ a b))    ==>     ERROR!
        (defun my-window (wob) 
            (window wob))               ==>     ERROR!

(defname name namespace [value])

Defines the atom name to be a name in the namespace. If the value is given, for each state of the namestate, a (set name (eval value)) is done, otherwise the value of name is left undefined in all the states.

Suppose you want to have a variable dpi giving the density of the screen in dots per inches for each screen:

        (defname 'dpi screen.
            (/ (* screen-width 254) 
                (* screen-widthMM 10)))

delete-nth   ---   physically removes an element of a list

EXPERT

(delete-nth index list)
(delete-nth key list)

This function physically removes an element of a list and returns the list. Elements are specified as for the # function. For property lists, the key and the value are deleted.

        (setq l '(a 1 b 2 c 3 d 4))
        (delete-nth 5 l)
        l                               ==>     (a 1 b 2 c d 4)
        (delete-nth 'b l)
        l                               ==>     (a 1 c d 4)

Numeric variable      (number)

If non-zero, all calls to get-x-property deletes the X property after reading it.

(delete-window [window])

This function will ask the client owning the argument window (or the current window if none is given) to delete it. This is only possible if the client participates in the WM_DELETE_WINDOW ICCC protocol, in which case the function returns t, otherwise ().

This is different from the kill-window call, which destroys the client and every top-level window owned by it, in that other windows should survive the call.

(dimensions object)
(width object)
(height object)

These functions return the width and height in pixels of any wob, pixmap, active label, cursor, or string. For wobs, the returned dimensions include the borderwidth. For strings, these are the dimensions that such a string would take on the screen, if printed in the current font, thus including the label-horizontal-margin and label-vertical-margin.

The dimensions function returns a list of four values: x, y, width, height. x and y being non-null only for wobs in which case they are the coordinates of the upper-left corner of the wob relative to the parent wob.

Numeric variable      (number)

This variable controls the main direction of menus created by the menu-make constructor. Possible values are horizontal or vertical.

(describe-screen)

This function must be provided by the user. It must return the description of the screen (cursor, fsm, ... ), made with a window-make call. Of the window-make parameters, only the opening (expression evaluated when all windows are decorated, just before entering the main loop of GWM) and closing (expression evaluated just before ending) parameters are used.

Context used:

This function is called by GWM for each managed screen once. In the current version, only one screen is managed. Before each invocation of this function, the screen characteristics (visual, depth, ...) are updated to reflect the characteristics of the corresponding screen.

(describe-window)

When a new window must be decorated by GWM, it calls this user-defined function with window and wob set to the new window. It must return a list of two window descriptors made with window-make describing respectively the window and the icon of the new client window.

A recommended way to use describe-window is to store in advance all the window descriptions in the resource manager by resource-put calls and use a resource-get call in your describe-window function to retrieve the appropriate description. But this is not mandatory and you are free to design the way to describe a window freely. For instance with the following describe-window function:

        (defun describe-window ()
            (resource-get (+ window-client-class "." window-client-name)
                    "any-client.any-client"))


        (resource-put "any-client.any-client" any-window)
        (resource-put "XTerm.xterm" xterm-window)

GWM will decorate xterm windows by the description held in xterm-window, and will decorate the windows of any other client by the any-window description.

Variable      (string)

This variable holds the name of the display on which GWM is running.

(double-button number modifier)
(double-buttonpress number modifier)

These events look for an incoming X ButtonPress event and matches it if the last key or button event was on the same button, in the same wob, and not a key event, and happened less than double-click-delay milliseconds before it.

The button to be pressed is specified by the number number, and these events verify that the modifier argument was depressed during the click. double-button waits for the corresponding ButtonRelease event before returning, while double-buttonpress returns immediately. Number or modifier can take the value any, thus matching any of the values of the corresponding argument.

Note that handling double-click events this way implies that the action that is done on a simple click event is executed even for a double click event, just before the action associated with it. The recommended way to use double-clicks is to place the double-button event before the button in the state of the fsm as in:

        (on (double-button 1 any) (do-double-action))
        (on (button 1 any) (do-simple-action))

Note: The ``last'' event can be a ButtonRelease event only if it is waited for explicitly by a GWM buttonrelease event, in which case the double-click-delay is measured between the release of the first click and the press of the second. Otherwise (if the first click is awaited by a button event) the delay is taken between the two ``presses'' of the button.

Numeric variable

If two buttonpress events are closer in time than double-click-delay milliseconds then the second one can be matched by the double-button and double-buttonpress events.

(draw-line pixmap x1 y1 x2 y2)

Draws a line (via the XDrawLine X call) in a pixmap from point x1, y1 to point x2, y2 in the pixmap coordinates.

Context used:

(draw-rectangle pixmap x1 y1 width height border style)

Draws a rectangle in the pixmap. Upper corner is placed at x1, y1 coordinates in the pixmap, with the rectangle dimensions being width and height. border is the border width. Note that a value of 0 for border does not means ``no border'' but a border drawn with 0-width lines, which in X means the default line width, usually 1. In the X tradition, the upper-left corner is taken inside the border, and the dimension do not include the border.

style tells which kind of rectangle to draw, namely:

Context used:

(draw-text pixmap x1 y1 font text)

Draws a string of characters text on font font into the pixmap pixmap. Baseline of the string will start at coordinates x1, y1 in the pixmap.

Context used:

(elapsed-time)

Returns the time in milliseconds for which GWM has been running.

(end)

Terminates GWM, de-iconifying all the windows, un-decorating them, restoring their original borderwidth, and closing the display.

Constant      (event)

This event is sent to the wob when the pointer crosses its border. Note that no leave event is generated if the pointer goes over a child window inside it.

Constant      (event)

When the server is grabbed (for instance by GWM when popping a menu or moving/resizing a window), the cursor appears to leave the current window it is in, and thus a leave-window is sent to this window. These events allow you to wait only for real crossing events, and not these grab-provoked ones. This distinguishment is needed to code some tricky menu actions.

eq   ---   tests strict equality of any two objects

EXPERT

(eq object1 object2)

Returns true only if the two object are the same, i.e., if they are at the same memory location.

        (setq l '(a b c))
        (setq lc '(a b c))
        (= l lc)                        ==>        t
        (eq l lc)                       ==>        ()
        (eq (# 1 l) (# 1 lc))           ==>        t

(error-occurred expressions ...)

Executes the given expressions and returns () if everything went fine, but returns t as soon as a WOOL error occurred and does not print the resulting error message.

(eval wool-expression)

This function evaluates its argument. Note that there is a double evaluation, since the argument is evaluated by Lisp before being evaluated by eval.

        (? (eval (+ '( + ) '(1 2))))     ==>     prints "3"

(execute-string string)

Parses the string argument as a WOOL program text and evaluates the read expressions. Returns () if an error occurred in the evaluation, t otherwise. Very useful in conjunction with cut-buffer, to evaluate the current selection with:

        (execute-string cut-buffer)

Constant      (event)

These events are sent to a wob when a child receives or loses the keyboard focus, i.e., the fact that all input from the keyboard goes to that child regardless of the pointer position. Only window wobs receive these events when their client window gets the focus, they must redispatch them to their sons (bar wobs) if they are expected to respond to such events (a title bar might want to invert itself for instance) by using the send-user-event function.

Numeric variable      (number)

This is the font ID used by default for the constructors label-make and active-label-make. Initialized to ``fixed'' or your local implementor's choice. It is also the font returned by font-make when it fails to find a font.

(font-make font-name)

This function loads a font in memory, from the ones available on the server. You can list the available fonts by the XLSFONTS(1) UNIX command. The function returns the descriptor (number) of the loaded font. If it fails to find it, it will issue a warning and return the default font found in the font global variable.

(for variable list-of-values inst1 inst2 ... instN)
(mapfor variable list-of-values inst1 inst2 ... instN)

This Lisp control structure affects successively the variable (not evaluated) to each of the elements of the evaluated list-of-values, and executes the n instructions of the body of the for. The variable is local to the for body and will be reset to its previous value on exit.

for returns the value of the evaluation on instN in the last iteration, whereas mapfor builds a list having for values the successive values of instN for the iterations.

        (for window (list-of-windows)           ; will replace all windows
            (move-window 0 0))                  ; in the upper-left corner


        (for i '(a b 2 (1 2)) 
            (print i ","))              ==>     a,b,2,(1 2),
        (mapfor i '(a b 2 (1 2))
            (list i))                   ==>     ((a) (b) (2) ((1 2)))

Numeric variable --- screen relative      (color)

The value of this global variable is used by the constructors of graphics (labels and pixmaps) to paint the graphic. It is a pixel value, such as returned by color-make, and is initially set to the pixel of the color Black.

Numeric variable      (number)

If set to t or 1, the X server is frozen, i.e. it doesn't process the requests for other clients during the move-window, resize-window and grab-server operations, so that you cannot have your pop-up menu masked by a newly mapped window, or you display mangled when moving or resizing a window.

If set to () or 0, the processing of other clients requests are allowed so that you can print in an xterm while popping a menu, for instance. (If the server is frozen, GWM tries to write on an xterm whose X output is blocked and GWM is deadlocked, forcing you to log on another system to kill it!). This should happen only when debugging, though, so that the default for this variable is t (Menus are normally coded so that user actions are triggered after de-popping).

Variable      (fsm)

This global variable is used by all wob constructors to determine their future behavior. Holds a fsm made with fsm-make, or () (no behavior).

(fsm-make state1 state2 ... stateN)

This function creates a finite state machine with N states. Each wob has an associated fsm, and a current state, which is the first state at creation time. Each time a wob receives an event, its current state of its fsm is searched for a transition which matches the event. If found, the corresponding action is executed and the current state of the fsm becomes the destination state of the transition. If no destination state was specified for the transition (see the on function), the current state of the fsm does not change. See on and state-make functions.

Constant      (event)

This event is sent to the window when its geometry changes by a resize operation either from the client or from GWM.

(get-wm-command)

Returns the command line that can be used to restart the application which created the current window in its current state as a list of strings. (For instance, ("xterm" "-bg" "Blue")). See save-yourself.

(get-x-default program-name option-name)

Calls the ``XGetDefault'' Xlib function to query the server defaults about an option for a program. This function should be used to retrieve defaults set either by the obsolete .Xdefaults files or the XRDB client. It returns () if no such option was defined, or the option as a WOOL string.

(get-x-property property-name)

Returns the value of the X11 property of name property-name of the current client window. It only knows how to handle the types STRING and INTEGER. For instance, (window-name) is equivalent to (get-x-property "WM_NAME").

The value of the global variable delete-read-properties determines whether the read property is deleted afterwards.

(getenv variable-name)

If variable-name (string) is the name of an exported shell variable, getenv returns its value as a string, otherwise returns the nil string.

Numeric variable      (number)

If set, all grabs will also grab the keyboard, i.e. all keyboard events will also be redirected to the grabbing wob, whereas if unset only the pointer events get redirected.

(grab-server wob ['nochild])

Grab-server freezes the server, so that only requests from GWM are processed, and every event received by GWM is sent to the wob (called the ``grabbing'' wob) passed as argument, or to a child of it. Re-grabbing the server afterwards just change the grabbing wob to the new one if it is not a child of the wob currently grabbing the server, in which case the function has no effect. Grabbing the server by a wob is a way to say that all events happening for wobs which are not sons of the grabbing wob are to be processed by it.

For instance, the pop-menu function uses grab-server with the menu as argument in order for the sons to be able to receive enter and leave window events and to catch the release of the button even outside the pop-up.

Grabbing the server sets the mouse cursor to the value of cursor if not ().

If the atom nochild is given as optional argument, if an event was sent to a child of the grabbing wob, it is redirected to the grabbing wob as well (default not to redirect it).

Numeric variable --- screen relative      (color)

This is the color (as returned by color-make) that will be used to draw the grid with (in XOR mode) on the display. Initially set to the ``Black'' color.

Variable      (list)

The events specified in this list are used by the window-make constructor to specify on which events GWM establishes passive grabs on its window to which the client window gets reparented. Passive grabbing means redirecting some events from a window (bars, plugs, client) to the main window, ``stealing'' them from the application.

Numeric variable      (0/1)

This variable evals to 1 if the users specified (by the -q option) a quiet startup. Your code should check for this variable before printing information messages.

hack   ---   raw access to GWM internal structures

EXPERT

(hack type memory-location)

WARNING: Internal debug function: returns the WOOL object constructed from C data supposed present at memory-location (number). The type of the type argument is used to know what to find:

This function is not intended for the normal user, it should be used only as a temporary way to implement missing functionalities or for debugging purposes.

(hashinfo)

Prints statistics on atom storage.

Constant      (number)

Used to specify orientation of menus in menu-make.

Active value      (string --- not settable)

This string holds the name of the host GWM is currently running on.

(iconify-window)

Iconify the current window (or de-iconify it if it is already an icon). The current window is then set to the new window.

WARNING: Never trigger this function with a button event, but with a buttonpress or buttonrelease event. If you trigger it with a button event, the window being unmapped cannot receive the corresponding release event and GWM acts weird!

WARNING: Due to the grab management of X, an unmapped window cannot receive events, so a grab on this window is automatically lost.

(if condition then [condition then] ... [condition then]
              [else])

This is similar to cond but with a level of parentheses suppressed. It executes the ``then'' part of the first true condition, or the else condition (if present) if no previous condition is true.

        (defun fib (n)
            (if (= n 0)
                    1
                (= n 1) 
                    1
                    (+ (fib (- n 1) (- n 2)))))

Numeric variable      (number)

When GWM decorates a new window, it sets the width of the border of the client window to the value of the inner-borderwidth variable at the time of the evaluation of the window-make call.

If inner-borderwidth has the value any, which is the default value, the client window borderwidth is not changed.

Numeric variable --- screen relative      (color)

This is the color (as returned by color-make) that will be used by wob-invert to quickly XOR the wob surface. Initially set to the bitwise-xoring of Black and White colors for each screen.

Numeric variable      (number)

Due to many problems on different servers, you might try to set to 1 this numerical global variable if your loaded cursors appear to be video inverted. Defaults to 0 (no inversion).

(itoa number)

Integer to ASCII yields the base 10 representation of a number in a WOOL string.

        (itoa 10)                       ==>     "10"

(key keysym modifier)
(keypress keysym modifier)
(keyrelease keysym modifier)

Returns an event matching the press on a key of keysym code keysym¹³, with the modifier¹⁴  key modifier depressed. The key event will wait for the corresponding keyrelease event before returning, while the keypress event will return immediately. Number or modifier can take the value any, thus matching any of the values of the corresponding argument.

Keysyms can be given as numbers or as symbolic names.

        (key 0xff08 with-alt)   ; matches typing Alternate-Backspace
        (key "BackSpace" with-alt)       ; same effect

Note: These functions convert the keysym to the appropriate keycode for the keyboard, so you should do any re-mapping of keys via the set-key-binding function before using any of them.

(key-make keyname)

Returns a keysym (number) associated with the symbolic name keyname (string), to be used with the key, keypress, keyrelease and send-key-to-window functions. The list of symbolic names for keys can be found in the include file ``/usr/include/X11/keysymdef.h''.

For instance, the backspace key is listed in keysymdef.h as:

        #define XK_BackSpace            0xFF08  /* back space, back char */

        (key-make "BackSpace")          ==> 65288 (0xFF08)

(keycode-to-keysym code modifier)

This function returns the server-independent numeric code (the KeySym) used to describe the key whose keyboard code is code while the modifier modifier is down.

Note: Only know the alone and with-shift modifiers are meaningful in this X function.

(keysym-to-keycode keysym)

This function returns the key code, i.e., the raw code sent by the displays keyboard when the user depresses the key whose server-independent numeric code is listed in the ``/usr/include/X11/keysymdef.h'' include file and given as a number as the keysym argument.

(kill-window [window])

Calls XKillClient on the current window or window if specified. This is really a forceful way to kill a client, since all X resources opened by the client owning the window are freed by the X server. If only you want to remove a window of a client, use delete-window.

Numeric variables      (number)

The value of these global variables are used by the label-make functions to add margins (given in pixels) around the string displayed. label-horizontal-margin defaults to 4 and label-vertical-margin to 2.

(label-make label [font])

Creates a label with string label drawn with foreground color in the font font on a background background. This function builds a pixmap which is returned.

Note that when used in a plug, the resulting pixmap is directly painted on the background pixmap of the wob, speeding up the redisplay since re-exposure of the wob will be done directly by the server, but consuming a small chunk of server memory to store the pixmap.

Context used:

(last-key)

If the last event processed by a fsm was a key event, returns the string generated by it. (Pressing on A yields the string "A"). It uses XLookupString to do the translation.

(length list)
(length string)

Returns the number of elements of the list or the number of characters of the string.

(list elt1 elt2 ... eltN)

Returns the list of its N evaluated arguments.

        (list (+ 1 2) (+ "foo" "bar"))  ==>     (3 "foobar")

(list-make size elt1 elt2 ... eltN)

Returns the list of size size (number) elements. The element of rank i is initialized to elt$j$, where $j = i$ modulo $N$, if elements are provided, () otherwise.

        (list-make 8 'a 'b 'c)          ==>     (a b c a b c a b)
        (list-make 3)                   ==>     (() () ())

(list-of-screens)

Returns the list of screens actually managed by GWM.

(list-of-windows ['window] ['icon] ['mapped]
    ['stacking-order])

Returns the list of all windows and icons managed by GWM, mapped or not. Called without arguments, this function returns the list of all windows (not icons), mapped or not. It can take the following atoms as optional arguments:

• window lists only main windows

• icon lists only realized icons

• mapped lists only currently mapped (visible) windows or icons

• stacking-order lists windows in stacking order, from bottommost (first) to topmost (last). This option is slower than the default which is to list them by the order in which they were managed by GWM, from the the newest to the oldest.

The window and icon arguments are mutually exclusive.

Note: The two following expressions do not return the same list:

        (list-of-windows 'icon)
        (mapfor w (list-of-windows) window-icon)

Note: The main window of an application is always realized, even if the application started as iconic.

(load filename)

Loads and executes the WOOL file given in the filename string argument, searching through the path specified by the GWMPATH variable or the -p command line switch. Defaults to .:$HOME:$HOME/gwm:INSTDIR, where INSTDIR is your local GWM library directory, which is normally /usr/local/X11/gwm, but can be changed by your local installer.

On startup, GWM does a (load ".gwmrc").

Returns the complete pathname of the file as a string if it was found, () otherwise but does not generate an error, only a warning message.

Searches first for filename.gwm then filename in each directory in the path. If the filename includes a / character, the file is not searched through the path. If any error occurs while the file is being read, WOOL displays the error message and aborts the reading of this file. This implies that you can't expect GWM to run normally if there has been an error in the .gwmrc. (You can turn off this behavior and make GWM continue reading a file after an error at your own risk, with the -D command line option).

(lower-window [window])

Lowers the current window below all other top-level windows or, if the window argument is present, just below the window given as argument.

(make-string-usable-for-resource-key string)

Replaces all characters |.& | (dots, stars, ampersand and spaces) in the string string by underscores '_'. This function should be used before using names for keys in the resource manager functions, as X can go weird if you do not handle the good number of classes and names to the resource manager (see resource-get).

The string argument is not modified; if replacement is done, a new string is returned.

Constant      (event)

This event is sent to a window or icon just afterwards being actually mapped.

Variable      (boolean)

This context variable is used in window decorations, and ,if set, will make the window be mapped (and de-iconifed it it was iconified), when the client raises it.

This is mainly useful for buggy clients assuming that since they put up Motif dialog boxes on the screen, they cannot be iconified since mwm doesn't provide a way to do it. Setting this flag on FrameMaker v3.0 windows will allow correct mapping of iconified dialog boxes.

(map-window [window])

Maps (makes visible) the window (or current window). Does not raise it.

(match regular-expression string [number] ...)

This is the general function to match and extract substrings out of a WOOL string. This string is matched against the pattern in regular expression, and returns () if the pattern could not be found in the string, and the string otherwise.

If number is given, match returns the sub-string matching the part of the regular-expression enclosed in between the number-th open parenthesis and the matching closing parenthesis (first parenthesis is numbered 1). Do not forget to escape twice the parentheses, once for GWM parsing of strings, and once for the regular expression, e.g., to extract ``bar'' from ``foo:bar'' you must use: (match ":\\(.*\\)" "foo:bar" 1). If a match cannot be found, returns the nil string "".

If more than one number argument is given, returns a list made of of all the specified sub-strings in the same way as for a single number argument. If a sub-string wasn't matched, it is the null string. For instance, to parse a X geometry such as 80x24+100+150 into a list (x y width height), you can define the following function:

        (defun parse-x-geometry (string)
          (mapfor dim                   
            (match "=*\\([0-9]*\\)x\\([0-9]*\\)\\([-+][0-9]*\\)\\([-+][0-9]*\\)" 
                   string 3 4 1 2)
            (atoi dim))
        
        (parse-x-geometry "80x24+100+150")  ==>  (100 150 80 24)

Note that this function returns an error if there is a syntax error in the given regular expression.

The accepted regular-expressions are the same as for ED or GREP, viz:

1. Any character except a special character matches itself. Special characters are the regular expression delimiter plus [ . and sometimes ^ * $.

2. A . matches any character.

3. A \ followed by any character except a digit or ( ) matches that character.

4. A nonempty string s bracketed [s] (or [^s]) matches any character in (or not in) s. In s, \ has no special meaning, and ] may only appear as the first letter. A substring a-b, with a and b in ascending ASCII order, stands for the inclusive range of ASCII characters.

5. A regular expression of form 1-4 followed by * matches a sequence of 0 or more matches of the regular expression.

6. A regular expression, x, of form 1-8, bracketed \(x\) matches what x matches.

7. A \ followed by a digit n matches a copy of the string that the bracketed regular expression beginning with the nth \( matched.

8. A regular expression of form 1-8, x, followed by a regular expression of form 1-7, y matches a match for x followed by a match for y, with the x match being as long as possible while still permitting a y match.

9. A regular expression of form 1-8 preceded by ^ (or followed by $), is constrained to matches that begin at the left (or end at the right) end of a line.

10. A regular expression of form 1-9 picks out the longest among the leftmost matches in a line.

11. An empty regular expression stands for a copy of the last regular expression encountered.

(member element list)
(member substring string)

In the first form, scans the list (with the equal predicate) to find the object element. If found, returns its index in the list (starting at 0), () otherwise.

In the second form, looks for the first occurrence of the string substring in the string string, and returns the character position at which it starts, or () if not found.

(meminfo)

Prints the state of the malloc allocator of all dynamic memory used, by WOOL or by the Xlib. You will note that reloading your profile consumes memory. This is unavoidable.

Variable      (menu)

The value of this global variable is used by the constructors of all wobs to set the associated menu of the wob. It should be set to a menu constructed with menu-make or (). This menu is the default one used by the pop-menu and unpop-menu functions.

(menu-make bar1 bar2 ... barN)

Creates a menu, vertical or horizontal depending on the value of the context variable direction (horizontal or vertical). This function returns a menu descriptor and at the same time realize the corresponding menu wob (to get the wob, use the menu-wob function below). Unlike the plug-make or bar-make functions that return the WOOL description to be used to create different wob instances, this is the only WOOL function which really creates a wob (as an unmapped X window) on execution.

A vertical menu is composed of horizontal bars stacked on top of each other. A horizontal menu is composed of vertical bars aligned from left to right. The menu takes the width (or height) of the largest bar, then adjusts the others accordingly in the limits defined by the values of menu-max-width and menu-min-width.

If a bar argument is (), it is just skipped.

Context used:

(menu-wob menu-descriptor)

Returns the wob representing the menu as given by the descriptor returned by menu-make and used in the context variable menu.

(meter [key value]...)
(meter list)

Sets the attributes of the current screen meter. The key must be an atom, and the corresponding attribute is set to the value. If a list is given, it must be a list of keys and values.

meter returns a list of keys and values describing the previous values of attributes that has been changed. This list can then be given as argument to meter to restore the previous values.

Gravity is expressed as in X11 calls, i.e. by the numbers:

For instance, to set temporarily the meter on the lower right corner of the screen:

        (setq previous-meter-config
              (meter 'x screen-width 'y screen-height
                     'gravity 9))
                                         ; ==> (x 0 y 0 gravity 1)
        (my-code...)
        (meter previous-meter-config)

(meter-close)

Closes the meter (makes it disappear).

(meter-open x y string)

Displays the meter at location x,y. The string argument is only used to set the minimum width of the meter, call meter-update to display a string in it.

(meter-update string)

Change the string displayed in the meter to string. Updates the width of the meter accordingly. Since the meter is generally used in a context where speed is important, it is never shrunk, only expanded.

Numeric variables      (number)

These variables control the kind of grid which is displayed on move or resize operations. Currently available grids are:

Numeric variables      (number)

If set to 1, the meter is shown during an interactive move, displaying the coordinates of the moved window.

(move-window)
(move-window window)
(move-window x y)
(move-window window x y)

Moves the window. If coordinates are specified, moves directly the current window (or window argument if specified) to x,y (upper-left corner coordinates in pixels). If coordinates are not specified, moves the window interactively, i.e., display the grid specified with the current value of move-grid-style, and track the grid, waiting for a buttonrelease for confirmation or a buttonpress for abort. If confirmed, the window is moved to the latest grid position. The cursor will take the shape defined by the variable cursor if not (). When move-window is called on another event than buttonpress, there is no way to abort the move.

If you have a strange behavior on move or resize window, check if you didn't trigger them with a button event instead of a buttonpress, since GWM will wait for a release already eaten by move-window!

When used interactively (first two forms), the return value can be one of:

Also, when used interactively, if the context variable confine-windows is set, the window will stay confined to the screen.

Constant      (event)

This event is sent to the window when the client changes its name. The window should then warn the appropriate wobs, by a send-user-event if needed. It is equivalent to the event made by the call (property-change "WM_NAME").

(namespace namespace current-state-index)

Sets the current state of the namespace argument to the index returned from the namespace-add function at the creation of the state. If the index is out of bounds (like ``-1''), returns the current index.

(namespace-add namespace)

Adds a new state to the argument namespace and returns the index (numeric offset starting at 0) of the newly created state. This index should then be used to set the current state of the namespace by the namespace function.

(namespace-make)

Creates a new namespace and returns it. A namespace is a set of variable names, called names, that have different values for each state in which the namespace can be.

The special namespace screen. has as many spaces as there are screens, and its current state is always updated to match the current screen by GWM. Other namespaces must switch states by the namespace function.

For instance, to define a namespace application. with a name application.border which will depend on the current application:

        (setq application. (namespace-make))
        (setq application.clock (namespace-add application.))
        (setq application.load (namespace-add application.))
        (defname 'application.border application.)
        (namespace application. application.clock)
        (setq application.border 1)
        (namespace application. application.load)
        (setq application.border 2)


        (namespace application. application.clock)
        application.border                                ==>  1
        (namespace application. application.load)
        application.border                                ==>  2

(namespace-of name)

Returns the namespace where the name name is declared in, otherwise (if it is a plain atom or an active value) returns ().

(namespace-remove namespace state-index)

Destroys a state (made with namespace-add of a namespace. The number state-index is the index returned by namespace-add at the creation of the state.

(namespace-size namespace)

Returns the number of the states of the namespace, i.e., the number of possible values for each name in this namespace. The legal values for the index to be given to the namespace function are in the range from 0 to the return value - 1.

Numeric variable      (number)

If set, GWM will never attempt to warp the pointer (move the pointer without actual user mouse motion).

(not object)

Logical negation. Returns t if object is (), () otherwise.

(oblist)

Prints the name and value of all currently defined WOOL atoms.

(on event [action [state]])
(on-eval event [action [state]])

This is the function used to build transitions in the states of the fsms. The on evaluates only its event argument, so that it is not necessary to quote the action or state arguments, whereas on-eval evaluates all its arguments.

When an event is handled by an fsm, it checks sequentially all the transitions of the current state for one whose event field matches the incoming event. If found, it calls the WOOL function found in the action field, which must be a function call, and makes the state argument the current state of the fsm. If no state is given, it is taken as the same state of the fsm. If no action is given, no action is performed.

The destination state is an atom which should have a state value defined in the current fsm (i.e., set by setq of an atom with the result of a state-make) at the time when the fsm is evaluated, which means that you can make forward references to states, as in the following example.

Example: To define a behavior of a wob cycling through 3 states on the click of any button, use this fsm:

        (fsm-make 
                (setq state1 (state-make
                        (on (button any any) (? 1) state2))
                (setq state2 (state-make
                        (on (button any any) (? 2) state3)))
                (setq state3 (state-make
                        (on (button any any) (? "3.\n") state1))))

Variables      (Wool)

The values of these global variables are used by the window-make constructor to define WOOL expressions which are evaluated just before creating or just after destroying a window or an icon.

Note: The opening field of a window is always evaluated on the creation of this window, thus the opening of an icon is only executed on the first iconification of the icon.

(or object1 object2 ... objectN)

Logical OR. Returns the first non-() object or ().

(pixmap-load filename [symbolic-color-name color-value]...)

This function builds a pixmap by reading its description in the file filename.xpm or filename, searched in the directory path held by the GWMPATH shell variable (see GWMPATH). In case of error the default pixmap returned is the same as the one returned by the pixmap-make function.

The pixmap is expected to be described in the XPM (for X PixMap) format. XPM is a de-facto standard X pixmap format which can be found on ftp.x.org or any of its mirrors, or koala.inria.fr, or by WWW at http://www.inria.fr/koala/lehors/xpm.html.

XPM allows you to associate symbolic color names to pixels in the file, which may be overrided by actual color to be used at load time. For instance, to use an icon undo defining the symbolic colors lit dark pen in a ``blue'' context, you may want to load it by a

        (pixmap-load 'undo 'lit (color-make "LightBlue")
                           'dark (color-make "SteelBlue")
                           'pen black)

Whereas if you want to give it a pinkish look:

        (pixmap-load 'undo 'lit (color-make "pink1")
                           'dark (color-make "pink4")
                           'pen (color-make "DeepPink4"))

Note: a color can be specified as the string "none", and in which case the pixels are transprent and the resulting pixmap can be used as tiles to construct shaped (non-rectangular) decorations.

        (pixmap-load 'undo 'lit (color-make "pink1")
                           'dark "none"
                           'pen (color-make "DeepPink4"))

(pixmap-make filename)
(pixmap-make width height)
(pixmap-make background-color file1 color1 
             file2 color2 ... )

With a single argument, loads the bitmap file given in the filename string argument, searching through the bitmap path specified by the GWMPATH variable or the -p command line switch (see GWMPATH). Searches first for filename.xbm then filename in each directory in the path. If the filename includes a / character, the file is not searched through the path. The pixmap is built by drawing the ``unset'' bits of the bitmap with the color held by the background variable and the ``set'' bits with the color held by the foreground variable.

When used with two arguments, pixmap-make returns a newly created pixmap of width width and height height filled with the current foreground color if the variable tile is nil, or filled with the pixmap pointed to by the tile variable, if any.

When used with three or more arguments, returns the pixmap constructed by using the bitmaps given as arguments to paint only the ``set'' bits of bitmap in file filei (searched along the same rules as for the first form) to the colori. The ``unset'' bits remain untouched. The pixmap is first painted with the color given in the background-color argument.

If the specified bitmap cannot be loaded, either because the file cannot be found or does not contain a bitmap, a default built-in bitmap is used and a warning is issued. The default is the MIT X Consortium logo as a 20x15 bitmap. Bitmaps can be of any size, they will be centered in the resulting pixmap which will be of the maximum size of its components.

The filename arguments can also be replaced by:

• active-labels The string is centered on the bitmap, drawn in the following color.

• pixmaps The pixmap is painted in the center, with its own background color (note that label-make returns a pixmap!). The following color is then ignored, but must be specified for consistency purposes.

(place-menu name menu [x y])

Places a menu (made with menu-make) on the screen. This window is then managed like any other client window. Its client class and, client name are given by the context variables class-name and client-name, by default Gwm and menu, and its window name is given by the parameter name. The window is placed at position x, y if specified and at 0,0 otherwise (NB: It is placed at last popped position if it was a popped menu). Returns the created wob.

WARNING: Be careful not to mix popup menus and placed ones, calling pop-menu on an already ``placed-menu'' will result in unpredictable behavior.

Context used:

(plug-make pixmap)
(plug-make active-label)

This function builds a plug, the atomic wob object. It is composed of a graphic object (either a pixmap, created with pixmap-make or label-make, or another type of object such as an ``active-label''). The size of the graphic object determines the size of the plug. Thus if you change the pixmap of the plug via wob-tile, the plug is resized accordingly.

Context used:

A plug can be shaped (non-rectangular) if made by pixmap-load-ing an XPM file with some transparent color pixels (or color none in XPM terms.

Numeric variable      (number)

The value of this global variable is used by the bar-make function to give the space in pixels between 2 consecutive plugs not separated by extensible space.

(pop-menu [menu] [position] ['here])

This function grabs the server (using the grab-server function), thus preventing other client requests to be processed by the server, and maps the given menu (or the menu associated with the current wob if menu is not given or is set to ()). The menu is guaranteed to be on the screen when this function returns. The behavior of the menu is then determined by the menu's fsm. The cursor will take the shape defined by the variable cursor if it is non-nil.

The position number is the item in which you want the cursor to appear (centered), the first item is numbered 0.

If the atom fixed is given, the menu is not moved under the current position of the pointer, it stays at the last position it was. So to pop a menu menu at (67, 48), do:

        (move-window (menu-wob menu) 67 48)
        (pop-menu menu 'here)

The current wob at the time of the call to pop-menu becomes the parent of the menu.

Note: A menu is not a GWM window, so when a menu is popped, the current window becomes the window parent of the wob which has popped the menu.

Note: The arguments to pop-menu can be given in any order and are all optional.

Numeric variable      (number)

If nonzero, WOOL error messages are printed on GWM output device, which is the default. error-occurred sets this variable to 0 to prevent printing errors.

Numeric variable      (number)

This variable controls the maximum depth at which the lists will be printed.

        (setq print-level 2)
        '(1 (2 (3 (4 rest))))           ==>      (1 (2 (...)))

process-events   ---   recursively process all pending events

EXPERT

(process-events [sync])

This function reads the event queue and recursively processes all pending events by re-entering the main GWM loop. It returns when there are no more pending events on the X event queue.

This functions allows a pseudo-multitasking capability for GWM. You can thus implement ``background jobs'' such as a general desktop space cleaning routine, to be called after each move, opening, or closing function that pauses by calling process-events at regular intervals to let GWM do its other tasks. You should then take into account the fact that the current function could be recursively called by another move operation triggered by an event processed by process-events, however and thus be re-entrant.

If a non-nil argument sync is given, GWM does a ``Sync'', i.e. requests the server to send all its pending events, before processing the events on the queue.

(process-exposes)

This function reads the event queue and processes all expose events it finds for GWM objects on the screen. It is used by pop-menu to be sure that the menu is completely drawn before letting it react to user events.

(rotate-cut-buffers number)

Exchange the contents of the 8 cut buffers on the X server so that buffer $n$ becomes buffer $n + $ number modulo 8.

(send-current-event window)

Re-sends the last key or button event to the client of the window argument. If window is (), it is taken as the current window.

(progn inst1 inst2 ... instN)
{inst1 inst2 ... instN}

The classical Lisp progn function, evaluating all its arguments and returning the result of the last evaluation. Useful in places where more then one Lisp instruction is expected, for instance in then fields of the if instruction, or in the action field of the on function. The brace notation is just a shortcut for writing progn sequences.

(property-change property-name)

This event is sent when the property of name property-name is changed on the client window.

(raise-window [window])

Raises the current window on top of all other top-level windows or, if the window argument if present, above the window given as argument.

(re-decorate-window [window])

Un-decorate the client window and re-decorate it as if it had appeared on the screen. Useful after a (load ".gwmrc") to test quickly any modifications to your profile.

Numeric variable      (number)

If nonzero (default), GWM will process all events in the queue before mapping a new window. This may pose re-entrancy problems (WOOL code may be called during a call to place-menu for instance), and thus can be turned off.

(refresh [window])

If a window argument is provided, refreshes only this window, otherwise forces a redraw of the screen like XREFRESH(1). Refreshing is done by mapping and unmapping a new window over the area to refresh.

(replayable-event event)

Makes the given button or key event replayable (see ungrab-server-and-replay-event). This is not the default for events because replayable events freeze the server state for GWM when a passive grab is activated with them, which might not be desirable.

        (set-grabs (replayable-event (button 1 alone)))

WARNING: It is recommended to un-freeze the server if you are to do some processing before the button or key is released, either by replaying the event by ungrab-server-and-replay-event or allow-event-processing.

Numeric variable      (number)

This variable controls the way the interaction with the user is handled during resizes, and can take the numeric values:

(resize-window)
(resize-window window)
(resize-window width height)
(resize-window window width height)

Resizes the window. If the dimensions are specified, resizes directly the current window (or the given window argument) to the given size, specified in pixels, rounded down to the allowed size increments (if you want to resize by increments, use the window-size active value). If the dimensions are not specified, resizes the window interactively, i.e., display the grid specified with the current value of resize-grid-style, and track the grid, waiting for a buttonrelease for confirmation or a buttonpress for abort. If confirmed, the window is resized to the latest grid position. The cursor will take the shape defined by the variable cursor, if it is non-nil.

NOTE: The dimensions given to resize-window are those of the outer window, in pixels, including the GWM decoration. Use the window-size active value if you want to specify the client dimensions.

WARNING: When resize-window is called on an event other than buttonpress, there is no way to abort the resize.

The interactive resize interaction is set by the value of the global variable resize-style

When used interactively (first two forms), the return value can be one of:

Also, when used interactively, if the context variable confine-windows is set, the window will stay confined to the screen.

(resource-get name class)

Calls the X11 resource manager for an object of name name and class class (strings of dot-separated names) previously stored by a call to resource-put matching the description (See the X11 documentation for precise description of the rule-matching algorithm of the resource manager).

This is the recommended way to retrieve the window descriptions associated with a client in the describe-window function.

WARNING: The name and class must have the same number of dots in them! (see make-string-usable-for-resource-key).

(resource-put name value)

Puts the value in the GWM resource database so that it can be retrieved by a future call to resource-get. Names can use the same conventions as in the .Xdefaults file for normal X11 clients.

This is the recommended way to store the window descriptions associated with a client so that they can be retrieved later in the describe-window function.

(restart)
(restart "prog" "arg1" "arg2" ... "argn")

Without arguments, restarts GWM, more precisely, it does an EXEC(2) of GWM with the same arguments that were given on startup.

With arguments, terminates GWM and starts a new process with the given command-line arguments. This useful to restart GWM with another profile, as in:

        (restart "gwm" "-f" "another-profile")

Active value      (window id)

Holds the wob describing the root window of the current screen. For instance, to set the background pixmap of the screen to the bitmap in file ``ingrid'', say:

        (with (wob root-window) (setq wob-tile (pixmap-make "ingrid")))

When set to a root window wob, sets the current wob and window to it, and screen to the screen it belongs to.

(save-yourself [window])

Sends to the current window's (or to given window's) client window the ICCC message WM_SAVE_YOURSELF, telling the application to update its WM_COMMAND X property to a command line which should restart it in its current state.

This function returns t if the window supported this protocol, and hence is supposed to update its WM_COMMAND property; () otherwise (see get-wm-command).

Active value      (screen number)

Returns or sets the current screen as the screen number (the same number as X in DISPLAY=unix:0.X). Setting the screen also sets the active values wob and window to the root window of the screen. See the warning about using screen in with constructs under the window entry.

Constant      (number)

The number of screens attached to the display. Not equal to (length (list-of-screens)) if you excluded screens by the -x command line option.

Constants      (number)

These numerical variables hold the size of the current screen in bitplanes (screen-depth) and pixels (screen-width and screen-height). A screen-depth of 1 means that you are on a monochrome screen.

Constants      (number)

Hold the dimensions of the screen in millimeters.

Active value      (atom --- not settable)

Returns the screen visual type as an atom, which can be either color, gray, or mono, if the screen is a color, gray scale, or monochrome device.

(send-button-to-window button modifier x y)

Sends a buttonpress and a buttonrelease X event to the client application of the window. The event is generated as if the user pressed on the button number button, with the modifier keys down and at location x,y in the client window coordinates (in pixels). In particular, this means that the event is sent to the smallest subwindow of the application containing x,y and having selected to receive button events.

(send-key-to-window keysym modifier)
(send-key-to-window string modifier)
(send-keycode-to-window keycode modifier)

These three functions are used to send key events to the client of the current window, to define function keys in GWM, or to implement mouse positioning of the cursor in Emacs for instance. The third form sends the keycode (as returned by current-event-code), the first the keysym as defined in the include file ``keysymdef.h''. Both keysyms and keycodes must be numbers, not names. You can however specify the symbolic name of the key with the key-make function. The modifier parameter indicates which modifier keys or which buttons were supposed to be down for the event.

The second form sends each character of the string (this works for ASCII characters only) with the modifier modifier to the window. A Shift modifier is automatically added to all uppercase characters.

(send-user-event atom [wob [do-not-propagate?]])

This function sends a ``user'' event, to the current window, if no argument is present, or to the wob specified as argument. A user event is a GWM concept and is NOT an X event, i.e., it is not seen by the server and is immediately processed before send-user-event terminates. The peculiarity of an user-event is that it recursively propagates downwards in the wob tree from the destination wob, the event being sent first to the child, then to the wob itself. That is, if you send an user-event to the window, all its decorations will receive it. The atom, which is evaluated by the function, and thus needs to be quoted, is used merely as a kind of label for the event.

If you provide a non-nil third argument, the event is sent to the given wob, but is not propagated to its sons.

Example:

        (send-user-event 'get-focus)

Note: send-user-event saves and restores the current wob, window, screen, and event. Thus if a piece of code triggered in another fsm sets the current wob to another one, it will be restored to its previous value on exit of the calling send-user-event.

(set-acceleration numerator denominator)

Accelerates the mouse cursor movement by a ratio of numerator/denominator (two numbers).

(set-colormap-focus [window])

Installs the colormap of the current window (or the given window). Once a window has the colormap focus, if the client changes its colormap, the new colormap is automatically installed by GWM.

If the window has no declared colormap, the default colormap (the colormap of the root window) is installed instead.

If the argument is (), the default colormap for the screen is re-installed.

(set-focus [window])

Sets the focus to the current window, or to the given window. The keyboard input will then go to the client of this window, regardless of the pointer position. If window is (), the focus is reset to PointerRoot mode, i.e., the focus is always on the window under the pointer.

If the client of the current window follows the ICCC WM_TAKE_FOCUS protocol, GWM does not try to set the focus to the window, it just sends the WM_TAKE_FOCUS message to the client which should then set the focus itself.

NOTE: set-focus will not set the focus on a client window that does not need it, so that set-focus on XCLOCK for instance has no effect. This is the only case where set-focus will return (); it returns t otherwise.

(set-grabs event1 event2 ... eventN)
(unset-grabs event1 event2 ... eventN)

set-grabs establishes what is called a passive grab on a button or a key on the current window, i.e.; all events matching the given events will be transmitted to the window itself, even if they have occurred on a bar, plug, or client window of the window.

unset-grabs removes events from the list of grabbed events. They do not exit an existing active grab.

The set-grabs call is used when decorating a window on the grabs list.

        (set-grabs (button 3 alone) 
                   (buttonpress any with-alt)
                   (key (key-make "Delete") any))
        (unset-grabs (key any any))

(set-icon-sizes min-width min-height
                max-width max-height
                width-inc height-inc)

This function sets a property of name WM_ICON_SIZE on the root window which tells the clients which are the desirable size for their icon pixmaps or icon windows, if they define any, as returned by window-icon-pixmap and window-icon-window.

(set-key-binding keycode keysym 
                 [keysym1 [keysym2 ... [keysymN]]])

This rebinds the keys on the server's keyboard. When the key of keycode keycode is pressed, it will be decoded as the keysym keysym if pressed alone, keysym1 if pressed with modifier1,... keysymN if pressed with modifier N (Modifiers are shift, control, lock, meta, etc.)

WARNING: The storage used by this function is never released.

Note: To obtain the list of current bindings of your server, use the xprkbd X11 utility.

(set-screen-saver timeout interval 
                  prefer-blanking allow-exposures)

Sets the way the screen-saver operates:

• Timeout is the time in seconds of no input after which the screen blanks (0 means no screen saver, -1 = restore default)

• Interval is the interval in seconds between random motion of the background pattern (0 disables motion)

• Prefer-blanking makes the screen go blank if 1

• Allow-exposures if 0 means that the screen saver operation should not generate exposures, even if this implies it cannot operate.

(set-subwindow-colormap-focus [number])

If the current window currently has the colormap focus, as set by the set-colormap-focus function, and the client has set a WM_COLORMAP_WINDOWS property on its window which tells GWM to install the colormaps of its subwindows, calling set-subwindow-colormap-focus without an argument installs the next different colormap in the list of subwindows whose colormaps must be installed.

If a numeric argument is given, it is taken as an offset in the list of subwindows (modulo the size of the list), and the corresponding window's colormap is installed. The main window is always at offset zero.

Calling set-colormap-focus on the window resets the current offset to zero, for subsequent calls to set-subwindow-colormap-focus.

(set-threshold number)

Sets the minimum pointer movement in pixels before acceleration takes place (See mouse-acceleration). The number argument must not be 0.

(setq atom value)
(set object value)

This is the assignment function of all Lisp dialects. In the first form, the first argument is not evaluated, in the second it is. (Thus allowing non-standard atom names to be set via the atom constructor atom, as in (set (atom "foo bar") 1) ). Both forms evaluate their second argument and sets the value of the first argument to the resulting value. Setting active values doesn't modify their value, but calls a predefined function on the value.

: is just a synonym for setq.

        (setq b 'c)
        (setq a (+ 1 2))
        (set  b 4)

(set-x-property property-name value)

Sets the X11 property of name property-name on the current client window. The value currently must be a STRING (or atom) or an INTEGER. For instance, (window-name "foo") is equivalent to (set-x-property "WM_NAME" "foo")

This is the recommended way for communicating between GWM and an X application.

sort   ---   sorts a list in place

EXPERT

(sort list comparison-function)

This function sorts (puts in ascending order) in place the list argument using the ``quicksort'' algorithm with the user-provided comparison function. This function is called on pairs of elements and should return -1, 0 or 1 if its first argument is lower than, equal to, or greater than the second.

This function is flagged as ``Expert,'' as it physically modifies the list. For instance, to obtain a list of windows sorted by names, do:

        (sort (list-of-windows) (lambda (w1 w2)
                (compare (with (window w1) window-name)
                         (with (window w2) window-name))))

Numeric variable      (number)

On error, WOOL prints a stack dump. The number of stack frames printed is given by the value of this variable. Setting it to a negative number puts no limits on the depth of the dump.

(state-make transition1 transition2 ... transitionN)

Makes a state of a fsm (see fsm-make and on functions) composed of the transitions given in arguments. Returns the constructed state which can be affected to a name via setq to be used as the destination state in transitions.

If an argument is itself a state, the new state will include all the transitions in the argument state.

(sublist from to list)

Returns the sublist starting at the from-th element and ending at the to-th element of list list (both from and to are numbers). from is inclusive and to is exclusive, and if they are greater than the size of the list, the elements are set to (). Elements are numbered starting at 0.

Examples:

                (sublist 2 4 '(1 2 3 4))&       ==>  (3 4)
                (sublist 5 9 ())        &       ==>  (() () () ())
                (sublist 10 -8 '(1 2)) &        ==>  ()

t

The ``true'' value, evaluates to itself.

(tag tag-name inst1 inst2 ... instN)
(exit tag-name inst1 inst2 ... instN)

The pair of functions tag/exit implements a non-local goto. When tag is called, the non-evaluated tag-name becomes the label of the goto. The instructions are then evaluated in progn fashion. If a call to exit with the same tag-name (non-evaluated) is made during these instructions, the evaluation of the tag instructions is aborted and tag returns the evaluation of the instructions of the exit call, evaluated like progn.

If exit makes the flow of control exit from a with local variable declarations construct, the previous variable values are restored.

WARNING: Do not, when in a file being loaded by load do an exit with a tag set outside the load call --- This breaks GWM in the current version.

Variable      (pixmap)

The value (pixmap) of this global variable is used by the constructors of all wobs to set their background pixmap. For now, it is only used in bars and screens.

(together modifier1 modifier2 ... modifierN)

Used to indicate that the modifiers must be pressed simultaneously,

        (button 1 (together with-shift with-alt))

Active values      ( )

This is a primitive debugging tool. When the trace value is set to a non-null number (or t) every call to any WOOL function is printed, with the arguments and return value. If set to an expression, this expression will be evaluated before and after each list evaluation (Setting trace to 1 instead of t re-enables the evaluation of the previous expression).

The trace level variable holds the current indentation (stack depth) of the calls. You might reset it to 0 if you re-enable the tracing after disabling it at a non-0 level.

NOTE: This is a primitive debugging tool, others will be added in the future.

(trigger-error exprs...)

This will trigger an error, returning instantly to the toplevel (unless trapped by a error-occurred). It will issue an error message, print all the given arguments exprs..., and append a newline.

(type object)

Returns the WOOL type of the object as an atom. Current types are:

(unbind atom)

Undefine the (evaluated) atom in argument, so that a boundp on it will return nil.

(ungrab-server [wob])

Ungrabs the server, allowing other client requests to be processed. If an argument is given, ungrabs the server only if the argument was the last wob to grab the server, otherwise does nothing. With no argument, unconditionally ungrab the server (keyboard and pointer).

(ungrab-server-and-replay-event flag)

When the X server has been grabbed by a passive grab (a grab set on a window by the grabs context variable or by the set-grabs function), you can release the grab and make the X server replay the event as if the grab didn't occur by calling this function.

You must set the flag parameter to () if the grab was on a mouse button, and to a non-nil object if the grab was on a key.

This call is useful in click to type window managers, to re-send the event which changed the current active window to the client window.

Note: An event can only be replayed if it has been grabbed on a replayable event (see replayable-event).

(unmap-window [window])

Unmaps (makes invisible) the window (or the current one).

(unpop-menu [menu])

Removes the grab set by the menu (or menu affected to the current wob if no argument is given) and unmaps it. The menu argument can be either a menu (as returned by the menu-make function) or a wob (as provided by the wob active-value). This function synchronize GWM with the server, so the menu is guaranteed to be unmapped when it returns.

Warning: The current-wob is not changed by this function. The wob which triggered the menu can be accessed as the parent of the menu.

(user-event atom)

This function is used in transitions to match user-events of the given (evaluated) atom (see send-user-event).

Example:

        (on (user-event 'get-focus) (set-pixmap focus-pattern))

Constants      (event)

This events are sent to a window when its visibility changes, e.g. when it gets obscured by moving another window on top of it.

warp-pointer   ---   warps the mouse pointer to a location

EXPERT

(warp-pointer x y [window-relative-to])

Warps (sets) the mouse pointer to the position (x,y), relative to its current position if no third argument is given, or in the coordinates of the given window-relative-to if given. For instance, to warp the pointer to the next screen at the same relative location say:

        (setq coordinates (current-mouse-position))
        (setq screen (% (+ (# 3 coordinates) 1) screen-count))
        (warp-pointer (# 0 coordinates) (# 1 coordinates) root-window)

WARNING: Use this function just like you would use ``goto'' in normal programming: never. warp-pointer will ruin a window management policy just as easily as ``goto''s will ruin a program.

(while condition inst1 inst2 ... instN)

Executes the N instructions in sequence until condition becomes (). Returns always ().

Active value      (window id)

Returns or sets the descriptor of the current window as a WOOL number. The current window is the default for all window functions. Setting window to a value sets also the current wob to this window.

WARNING: A (with (window w)...) call will modify the value of the current wob:

                                         ; window is A, wob is B
        (with (window C) (foo))          ; in foo, window is C, wob is C
                                         ; window is A, wob is A

Active value      (string)

Returns a string containing the class of the client owning the window, e.g., XTerm for an xterm window.

Active value      (number --- not settable)

Returns the dimensions in pixels of the client window, its position inside the GWM window frame, and the borderwidth of the client window (i.e. the inner-borderwidth of the decorated window).

Active value      (string)

Returns a string containing the name of the client owning the window, e.g., xterm for an xterm window.

Active value      (window id)

In X11, windows can be grouped with each window in the group bearing a reference to a distinguished window, the group leader. GWM maintains such groups as a list of windows, the group leader being the first one in the list. This active value returns () if the window does not belong to a group, otherwise it returns the list of windows in the group.

The user can himself define groups of windows by setting the window-group active value to a window id, which is the group leader to which the window should be grouped. The entire group (list) can also be passed as argument, in which case the first element is taken as the window to be grouped to.

To remove a window from a group, just assign () to window-group for this window, it is removed from the group it was in. If the window was a group leader, the group is broken and all the windows in it are ungrouped.

Note: A window can only belong to one group.

Active value      (window id --- not settable)

Returns the icon associated with the current window. If the current window is already an icon, returns the current window itself.

Note: When GWM decorates a window, it caches the WOOL description given for the icon, but does not create it. The icon is physically created, (and its opening field evaluated) on the first access to the window-icon active value or the first call to the iconify-window function. To just check that the window has an associated icon, without creating it if it didn't exist, use window-icon?.

(window-icon? [window])

Returns t if the icon has already been created, () if not, without creating it.

Active value      (string)

Returns the name that the client of the current window has given to its icon. If set, will modify the X property on the client name specifying the icon, so that this change will resist a window manager restart, but the name will be overriden by the client application if it changes its icon name in the future.

Active value      (pixmap --- not settable)

Returns the pixmap given as a hint by the current client to be used in its icon, or () if no pixmap was specified. The bitmap specified by the application is used to construct the returned pixmap by painting the unset pixels with the background color and the set pixels with the foreground color on the invocation of this function for each window. Thus each time it is called a new pixmap is created. It is highly recommended that you store the returned value instead of re-calling the function another time.

Use it as the plug argument of the window-make function after making a plug via plug-make.

Constant      (event)

When an application changes its pixmap to be used as its icon, this event is generated. You should then use the window-icon-pixmap function to retrieve it if your icon style supports it.

Active value      (number --- not settable)

This id is used to know which bitmap the client provided, and if it has changed since last time.

Active value      (window id --- not settable)

Returns a descriptor (number) of the window provided by the current client to be used as its icon, or () otherwise. Should only be used as the plug argument of the window-make function.

Active value      (boolean --- not settable)

If the current window is mapped (visible) returns it, () otherwise.

Active value      (boolean --- not settable)

If the current client window has a non-rectangular outline (on servers supporting the shape X11 extension), returns t, () otherwise.

Active value      (window --- not settable)

If not (), the window is transient for another window, and thus you might decide not to decorate it too much. (The window it is transient for is returned.)

(window-is-valid window)
(wob-is-valid wob)

Since in GWM, windows and wobs are represented by reference, i.e. by numbers meaning a pointer to some data, there is the risk of ``dangling pointers'', i.e. accessing a memory containing a no longer valid window. To test for these cases, two functions are provided. wob-is-valid will test if wob is any valid (non closed) plug, bar, menu , window, icon, or root window, whereas window-is-valid will verify that window is actually only a window or icon. These functions are not strictly necessary, but are useful for debugging purposes.

Active value      (string --- not settable)

Returns the string containing the name of the machine on which the client owning the window executes (Defaults to "machine" if not set.)

(window-make titlebar leftbar rightbar basebar plug)

Returns a description of a GWM window to decorate a newly created X window. This is also used to describe the associated icon and the screen. The four bars are the ones that frame the client and are evaluated another time when the window is physically created. This allows you to give expressions for bars (quoted to evade the first evaluation of arguments of the window-make function itself) which evaluates to a bar on the realization of the wob. Any bar can be set to (), indicating that that no corresponding bar should be created.

The fifth argument plug is only used when describing an icon, to be used as the central window around which the bars will be framed. You can give a plug (or an expression which when evaluated gives a plug) or the value of window-icon-window for the window. If set to (), the icon has the dimension of the longest side bar, or if they are also set to (), the dimension of the longest top or base bar.

Context used:

grabs is a list of button, buttonpress, key or keypress events which will be ``grabbed'' from the client window to be sent to the GWM window. This means that the event will be sent directly to the GWM window and not to the client window. For instance, to implement a ``uwm'' move style (moving a window on Alternate/right button anywhere in the window), the grab list should include a (buttonpress 3 with-alt), and the fsm of the window should have a (on (buttonpress 3 with-alt) (move-window)) transition.

Events declared in the grabs list are trapped on the whole surface of the window, including the bars and the client window, and redirected to the main window's fsm.

opening and closing are two Lisp expressions that are evaluated when the window (or icon) is created and destroyed respectively, just before being mapped or unmapped. This is the right place to position or resize the window before it appears. For the screen, opening is evaluated once all windows already on screen have been framed and closing is evaluated when leaving GWM.

When used for screen description, no arguments are used, only the context values for grabs, opening, closing, fsm, menu, cursor, and property context variables, with the additional context value:

Context used:

Active value      (string)

Returns the string containing the name of the window, as set by the client owning it. Note that it is a transient property, and the event name-change is issued when it is changed by the client.

When window-name is set, the WM_NAME X property on the client window is updated accordingly, resulting in the X name-change event to be sent to the window by the X server. This change will resist a window manager restart, but the name will be overriden by the client application if it changes its window name in the future.

Note: All dots in the name are converted to underscores, so that you can use the value of window-name safely as an name for the X resource manager.

Active value

To each wob is associated a property, which is any Lisp object given by the user. These active values return or set the stored property for the current wob or window. When creating a wob, the property is taken as the current value of the global variable property.

Active value      (list of two numbers)

Returns the size of the window expressed as a list of two numbers, multiples of the minimal size (e.g. character positions for xterm). When set, the window is resized accordingly. This is the size of the inner client window, to specify the outer dimensions, use resize-window.

Active value      (boolean)

If not (), the window appears as an icon on its first mapping or the first time it is decorated by GWM. This ``hint'' can thus be set either by the application or the window manager.

Active value      (atom --- not settable)

Returns the type of the current wob or window as an ATOM. Possible types are:

Thus, to check if the current window is an icon, just say:

        (if (= window-status 'icon) ...)

Active value      (boolean --- not settable)

Return t if the position or size of the current window was set explicitly by the user at creation time via command line switches, () otherwise. If called on an icon, tells if the user defined the initial icon position.

Active value      (boolean --- not settable)

Return t if the position or size of the current window was set by default by the program.

(window-to-client gwm-window)
(client-to-window X-window-id)

Converts GWM windows gwm-window to and from actual decorated client window Ids X-window-id (numbers used by ``xwininfo'' for instance).

Active value      (boolean --- not settable)

Returns t if the window was already on the screen before GWM. You may test its value to do certain actions only on newly created windows (if ()), such as interactive placement.

Active value      (number --- not settable)

These functions return the size of the current window (with decoration) or wob in pixels. These do not include the width of the border, following the X11 conventions.

Active value      (window id --- not settable)

Returns the window associated with the current window if it is an icon. If the current window is not an icon, returns the current window itself.

Active value      (atom --- not settable)

Returns an atom indicating which state the window is in, according to the WM_STATE property. The state of the window can be:

window\icon	mapped	unmapped
mapped	normal	iconic
unmapped	normal	withdrawn

The atom window is returned if the window is in the normal state, the atom icon is returned if it is iconic, and () is returned if it is withdrawn.

This state information is used by session managers and other window managers, for instance GWM itself will re-iconify the windows that were previously iconified on a restart.

Active value      (window id)

GWM manages automatically the WM_STATE property on client windows. However, if you implement in a WOOL package your own icons which are not the GWM ones, which are managed by the window-icon and iconify-window primitives, for instance by creating a window via the place-menu primitive, you need to declare which window must logically be considered as the icon for your window. This is done by setting the window-wm-state-icon on the window to the icon.

Once you have declared that a window has a user-managed icon, GWM no longer updates the WM_STATE property, so you should call window-wm-state-update each time you change the state of the window

(window-wm-state-update [state])

Once you have declared that a window has a user-managed icon, you should update the WM_STATE property by calling this function with the window global variable set to the managed window each time the state of the window changes.

An optional argument window, icon or () forces the WM_STATE property to be set to normal, iconic or withdrawn respectively. This can be useful for example if ``iconifying'' is done by unmapping the window.

Active value      (number --- not settable)

These functions return the coordinates of the upper-left corner of the current window, including its decoration, in the root window.

(with (var1 value1 ... varN valueN) instructions ...)
(with context instructions ...)
(with-eval expression instructions ...)

This is the construct used to declare and initialize variables local to a group of instructions. Active-values and functions are handled as expected, resetting their initial value after the execution of the body of the with. The values are evaluated sequentially.

A context is a list of variables and associated values that can be re-used in many with functions (see context-save).

with-eval first evaluates the expression and then uses it as a context, so that the two following calls are equivalent:

        (with (a 1 b 2) c)
        (with (+ '(a 1) '(b 2)) c)

Due to the structure of the WOOL interpreter, with works also with active-values and functions. For example the following call can be made to move the window ``my-window'' in the upper left corner of the screen.

        (with (window my-window move-ul (lambda () (move-window 0 0)))
                (move-ul))

        (setq bluegreen '(foreground green background blue))
        (with bluegreen (pixmap-make "Bull"))
        (with (a 2 b (+ a 1)) (print b))        ==>     3

Constants      (number)

These numerical values describe what was in a ``down'' state (i.e., pressed) when a key or button event was sent. You can combine them with the together function, for instance if you want shift and control pressed.

N can takes values 2 to 5 for modifiers and 1 to 5 for buttons, e.g., the with-modifier-5 and with-button-1 variables are defined.

Active value      (wob id)

Returns the descriptor of the current wob (i.e., the wob which received the event being processed) as a WOOL number. The current wob is the default for all wob functions. When set, the current wob is now the wob argument.

(wob-at-coords x y)

Returns the wob including the coordinates relative to the root. Returns () if coordinates were off-screen.

Active value      (color)

Returns or sets the (solid) background color of the wob. If set, discards the tile of the wob (if there was one) to paint its background with a solid color. Works only with bars and screens.

Active value      (color or pixmap)

Get or set the solid color or pixmap of the border of the current wob.

Active value      (number)

Gets or sets the width in pixels of the border of the current wob. If it is in a composite wob, the father is then resized.

Active value      (cursor)

This active value allows the user to get or modify the mouse cursor which is displayed when the pointer is in the current wob.

Active value      (fsm)

This active value allows the user to get or modify the fsm associated with a wob. If you set the fsm of a wob, it is placed in the initial state. This function is intended for debugging purposes, and its use should be avoided in normal operation. Try using multiple-state fsms instead of changing the fsm.

(wob-invert)

Inverts the colors over the surface of the current wob. This is just drawn on top of everything else, and does not affect permanently the wob. This should only be used after calling grab-server and then process-exposes (Note that pop-menu does that for you). This is a ``lightweight'' function to be used on transient objects. To invert a wob in a cleaner way, use wob-tile.

The wob is inverted by using the invert-color color (screen relative). This color should be chosen to be the bitwise-xoring of two colors that will be inverted by this functions, the other colors being affected in an unpredictable way.

Active value      (menu)

This active value allows the user to get or modify the menu associated with a wob.

Active value      (wob id --- not settable)

Returns the parent of the current wob. Note that the parent of a pop-up is the wob which called the pop-menu function. The parent of windows and icons is the root window itself, and the parent of a root window is nil.

Active value      (pixmap)

Returns or sets what is the current wob's pixmap background. For the screen itself or a bar, this is its background tile; for a plug this is the pixmap around which the plug is built. If you change the size of the wob-tile for a plug, it is automatically resized (but not a bar or a screen). wob-pixmap is just a synonym for wob-tile for backward compatibility purposes.

Active values      (wob id --- not settable)

Returns the position of the top left corner of the wob, including its border as absolute pixel coordinates in its screen.

(xid-to-wob id)

Returns the wob whose associated X window has the X ID id. If no wob if found, returns (). The X ID is the identification of windows used by all standard X tools such as xwininfo.