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 proce