The Common LISP X Interface (CLX)
*********************************

The Common LISP X Interface (CLX)

Copyright © 1988, 1989 Texas Instruments Incorporated

     Permission is granted to any individual or institution to use, copy, modify and distribute this document, provided that this complete copyright and permission notice is maintained, intact, in all copies and supporting documentation. Texas Instruments Incorporated makes no representations about the suitability of this document or the software described herein for any purpose. It is provided "as is" without express or implied warranty.

Acknowledgments
***************

Primary Interface Author:

Robert W. Scheifler

     MIT Laboratory for Computer Science
     545 Technology Square, Room 418
     Cambridge, MA 02139
     rws@zermatt.lcs.mit.edu

Primary Implementation Author:

LaMott Oren

     Texas Instruments
     PO Box 655474, MS 238
     Dallas, TX 75265
     oren@csc.ti.com

Design Contributors:

  * Dan Cerys, BBN

  * Scott Fahlman, CMU

  * Kerry Kimbrough, Texas Instruments

  * Chris Lindblad, MIT

  * Rob MacLachlan, CMU

  * Mike McMahon, Symbolics

  * David Moon, Symbolics

  * LaMott Oren, Texas Instruments

  * Daniel Weinreb, Symbolics

  * John Wroclawski, MIT

  * Richard Zippel, Symbolics

Documentation Contributors:

  * Keith Cessna, Texas Instruments

  * Kerry Kimbrough, Texas Instruments

  * Mike Myjak

  * LaMott Oren, Texas Instruments

  * Dan Stenger, Texas Instruments

The X Window System is a trademark of MIT.

UNIX is a trademark of AT&T Bell Laboratories.

ULTRIX, ULTRIX-32, ULTRIX-32m, ULTRIX-32w, and VAX/VMS are trademarks of Digital Equipment Corporation.

Introduction to CLX
*******************

This manual assumes a basic understanding of window systems and the Common Lisp programming language. To provide an introduction to the Common Lisp X Interface (CLX) programming, this section discusses the following:

  * Overview of the X Window System

  * Naming and argument conventions

  * Programming considerations

The X Window System
===================

The X Window System was developed at the Massachusetts Institute of Technology (MIT) and first released in 1985. Since then, the X Window System has become an industry-standard product available on virtually every type of bit-mapped workstation. The current version of X, Version 11, has been implemented for several different computer architectures, for a wide variety of display hardware, and also for many different operating systems. X Version 11 represents the fulfillment of the original design goals proposed by MIT, as follows:

Portable
     Support virtually any bitmap display and any interactive input device (including keyboards, mice, tablets, joysticks, and touch screens). Make it easy to implement the window system on different operating systems.

Device-Independent Applications
     Avoid rewriting, recompiling, or even relinking in order to use different display/input hardware. Make it easy for an application to work on both monochrome and color hardware.

Network Transparent
     Let an application run on one computer while using another computer's display, even if the other computer has a different operating system or hardware architecture.

Multitasking
     Support multiple applications being displayed simultaneously.

No User Interface Policy

     Since no one agrees on what constitutes the best user interface, make it possible for a broad range of user interface styles (or policies) to be implemented, external to the window system and to the application programs.

Cheap Windows
     Windows should be abundant, and ubiquitous. Provide overlapping windows and a simple mechanism for window hierarchy.

High-Performance Graphics
     Provide powerful interfaces for synthesizing 2-D images (geometric primitives, high-quality text with multiple typefaces, and scanned images).

Extensible
     Include a mechanism for adding new capabilities. Allow separate sites to develop independent extensions without becoming incompatible with remote applications.

Some of these goals lead directly to the basic X architecture -- the client-server model. The basic window system is implemented by the X server program. An application program (the client) sends window system requests to the X server through a reliable two-way byte-stream.

In general, the server and the client can be executing on separate host computers, in which case the byte-stream is implemented via some network protocol (TCP, DECnet(tm), Chaosnet, and so forth). The X server, which is connected to several client programs running concurrently, executes client requests in round-robin fashion. The server is responsible for drawing client graphics on the display screen and for making sure that graphics output to a window stays inside its boundary.

The other primary job of the X server is to channel input from the keyboard, pointer, and other input devices back to the appropriate client programs. Input arrives at the client asynchronously in the form of input events representing up/down transitions of keys or pointer buttons, changes in the pointer position, and so on. In some cases, a request generates a return value (or reply) from the server, which is another kind of client input. Replies and input events are received via the same byte-stream connecting the client with the server.

Windows
-------

The X Window System supports one or more screens containing overlapping windows and subwindows. A screen is a physical monitor and hardware, which can be either color or black and white. There can be multiple screens per display workstation. A single server can provide display services for any number of screens. A set of screens for a single user with one keyboard and one mouse is called a display.

All windows in an X server are arranged in a strict hierarchy. At the top of the hierarchy are the root windows, which cover each of the display screens. Each root window is either partially or completely covered by child windows. All windows, except for root windows, have parents. Any window can in turn have its own children. In this way, an application program can create a window tree of arbitrary depth on each screen.

A child window can be larger than its parent. That is, part or all of the child window can extend beyond the boundaries of the parent. However, all output to a window is clipped by the boundaries of its parent window. If several children of a window have overlapping locations, one of the children is considered to be on top of/or raised over the others, obscuring them. Window output to areas that are covered by other windows is suppressed.

A window has a border that is zero or more pixels in width and can be any pattern (pixmap) or solid color. A window usually has a background pattern that is drawn by the X server. Each window has its own coordinate system. Child windows obscure their parents unless the child windows have no background. Graphics operations in the parent window are usually clipped by the children.

X also provides objects called pixmaps for off-screen storage of graphics. Single-plane pixmaps (that is, of depth 1) are sometimes referred to as bitmaps. Both pixmaps and windows can be used interchangeably in most graphics functions. Pixmaps are also used in various graphics operations to define patterns, or tiles. Windows and pixmaps together are referred to as drawables.

Input Events
------------

The X input mechanism is conceptually simple yet quite powerful. Most events are attached to a particular window (that is, contain an identifier for the window receiving the event). A client program can receive multiple window input streams, all multiplexed over the single byte-stream connection to the server.

Clients can tailor their input by expressing interest in only certain event types. The server uses special event types to send important messages to the client. For example, the client can elect to receive an :ENTER-NOTIFY (see :enter-notify) event when the pointer cursor moves into a certain window. Another vital message from the server is an :EXPOSURE (see :exposure) event. This is a signal to the client indicating that at least some portion of the window has suddenly become visible (perhaps the user moved another window which had been overlapping it). The client is then responsible for doing what is necessary to redisplay the window's image.  Client programs must be prepared to regenerate the contents of windows in this way on demand.

Input is also subject to policy decisions about which client window receives keyboard and pointer events. Since the pointer is free to roam between windows, just clicking on a window is often enough to send a pointer event to that window. Keyboard events, however, must go to a keyboard focus window which has to be designated in some other way. Usually, the arbiter of such input management policy is a program called the window manager. The window manager gives the human user a way to make a window the keyboard focus, to manage the layout of windows on the screen, to represent windows with icons, and so forth. In fact, the window manager client determines most of the so-called look and feel of the X Window System.

A Quick Tour of CLX
===================

The X Window System is defined by the X Window System Protocol Specification, a detailed description of the encoding and the meaning of requests and events sent between a client and a server. This standard protocol does not depend on any particular programming language. As a result, each programming language must define its own functional interface for using the X protocol. The standard X interface used by Common Lisp programmers is called CLX. CLX is a set of data types, functions, and macros which allow a Common Lisp client program to interact with an X server to send requests and to receive input events and replies.

For the most part, CLX functions are closely tied to the underlying requests in the X protocol. Many CLX functions simply add requests to an output buffer. These requests later execute asynchronously on the X display server. However, some functions of CLX lie outside the scope of the protocol--for example, reading events and managing a clientside event queue. CLX is also responsible for important batching and caching tasks that minimize network communication.

The following paragraphs show an example of a CLX client program. All CLX functions and macros are shown in upper case. Note that some of the terms used are unique to X, while other terms that are common to other window systems have different meanings in X. It may be helpful to refer to the glossary when you are uncertain of a term's meaning in the context of the X Window System.

A Simple Menu
-------------

The example client program creates and displays a simple pop-up menu consisting of a column of strings--a title string followed by selectable menu item strings. The implementation uses one window to represent the entire menu, plus a set of subwindows, one for each menu item. Here is the definition of a structure which represents such a menu.

     (defstruct (menu)
       "A simple menu of text strings."
       (title "Choose an item:")
       item-alist				;((item-window item-string))
       window
       gcontext
       width
       title-width
       item-width
       item-height
       (geometry-changed-p t))	     ;nil if unchanged since displayed

The window slot will contain the WINDOW (see window) object that represents the menu. The item- alist represents the relationship between the menu items and their associated subwindows. Each entry in item-alist is a list whose first element is a (sub)window object and whose second element is the corresponding item string. A WINDOW (see window) object is an instance of a CLX-defined data type which represents X windows. A WINDOW (see window) object actually carries two pieces of information: an X window ID integer and a DISPLAY (see display) object. A DISPLAY (see display) is another CLX-defined data type that represents a connection to a specific X display server. The gcontext slot contains an instance of a CLX data type known as a graphics context. A graphics context is a set of display attribute values, such as foreground color, fill style, line style, text font, and so forth. Each X graphics request (and hence each CLX graphics function call) must supply a graphics context to use in displaying the request. The menu's gcontext will thus hold all of the attribute values used during menu display.

The first thing to do is make an instance of a menu object:

     (defun create-menu (parent-window text-color background-color text-font)
       (make-menu
        ;; Create menu graphics context
        :gcontext (CREATE-GCONTEXT :drawable   parent-window
     			      :foreground text-color
     			      :background background-color
     			      :font       text-font)

        ;; Create menu window
        :window    (CREATE-WINDOW
     	       :parent            parent-window
     	       :class             :input-output
     	       :x                 0	;temporary value
     	       :y                 0	;temporary value
     	       :width             16	;temporary value
     	       :height            16	;temporary value
     	       :border-width 2
     	       :border            text-color
     	       :background        background-color
     	       :save-under        :on
     	       :override-redirect :on ;override window mgr when positioning
     	       :event-mask        (MAKE-EVENT-MASK :leave-window :exposure))))

CREATE-WINDOW (see create-window) is one of the most important CLX functions, since it creates and returns a WINDOW (see window) object. Several of its options are shown here. The default window class is :INPUT-OUTPUT, but X provides for :INPUT-ONLY windows, too. Every window must have a parent window, except for a system-defined root window, which represents an entire display screen. The :EVENT-MASK keyword value, a CLX EVENT-MASK (see event-mask) data type, says that an input event will be received for the menu window when the window is exposed and also when the pointer cursor leaves the window. The window border is a pattern-filled or (as in this case) a solid-colored boundary which is maintained automatically by the X server; a client cannot draw in a window's border, since all graphics requests are relative to the origin (upper-left corner) of the window's interior and are clipped by the server to this inside region. Turning on the :SAVE-UNDER option is a hint to the X server that, when this window is made visible, it may be more efficient to save the pixels it obscures, rather than require several client programs to refresh their windows when the pop-up menu disappears. This is a way to work around X's client-managed refresh policy when only a small amount of screen space is needed temporarily.

Why is :OVERRIDE-REDIRECT turned on for the menu window? This is actually a little unusual, because it prevents any window manager client from redirecting the position of the menu when it is popped up. Remember that the window manager represents the user's policy for controlling the positions of his windows, so this kind of redirection is ordinarily correct. However, in this case, as a favor to the user, the menu avoids redirection in order to pop up the menu at a very specific location; that is, under the pointer cursor.

What about the item subwindows? The menu-set-item-list function in the following example creates them whenever the menu's item list is changed. The upper-left x and y coordinates and the width and height are not important yet, because they are computed just before the menu is displayed. This function also calls CREATE-WINDOW (see create-window), demonstrating the equal treatment of parent and children windows in the X window hierarchy.

     (defun menu-set-item-list (menu &rest item-strings)
       ;; Assume the new items will change the menu's width and height
       (setf (menu-geometry-changed-p menu) t)

       ;; Destroy any existing item windows
       (dolist (item (menu-item-alist menu))
         (DESTROY-WINDOW (first item)))

       ;; Add (item-window item-string) elements to item-alist
       (setf (menu-item-alist menu)
     	(let (alist)
     	  (dolist (item item-strings (nreverse alist))
     	    (push (list (CREATE-WINDOW
     			 :parent       (menu-window menu)
     			 :x            0 ;temporary value
     			 :y            0 ;temporary value
     			 :width        16 ;temporary value
     			 :height       16 ;temporary value
     			 :background   (GCONTEXT-BACKGROUND (menu-gcontext menu))
     			 :event-mask   (MAKE-EVENT-MASK :enter-window
     							:leave-window
     							:button-press
     							:button-release))
     			item)
     		  alist)))))

Displaying the Menu
-------------------

The menu-recompute-geometry function (shown in the following example) handles the job of calculating the size of the menu, based on its current item list and its current text font. CLX provides a way to inquire the geometrical properties of a font object (for example, its ascent and descent from the baseline) and also a TEXT-EXTENTS (see text-extents) function. TEXT-EXTENTS (see text-extents) returns the geometry of a given string as displayed in a given font. Notice the use of the WITH-STATE (see with-state) macro when setting a window's geometry attributes. CLX strives to preserve the familiar setf style of accessing individual window attributes, even though an attribute access actually involves sending a request to a (possibly remote) server and/or waiting for a reply. WITH-STATE (see with-state) tells CLX to batch together all read and write accesses to a given window, using a local cache to minimize the number of server requests. This CLX feature can result in a dramatic improvement in client performance without burdening the programmer interface.

menu-recompute-geometry causes all the item subwindows to become mapped. Mapping a window means attempting to make it visible on the screen. However, a subwindow will not actually be visible until it and all of its ancestors are mapped. Even then, another window might be covering up the subwindow.

     (defun menu-recompute-geometry (menu)
       (when (menu-geometry-changed-p menu)
         (let* ((menu-font   (GCONTEXT-FONT (menu-gcontext menu)))
     	   (title-width (TEXT-EXTENTS menu-font (menu-title menu)))
     	   (item-height (+ (FONT-ASCENT menu-font)
     			   (FONT-DESCENT menu-font)
     			   *menu-item-margin*))
     	   (item-width     0)
     	   (items          (menu-item-alist menu))
     	   menu-width)

           ;; Find max item string width
           (setf item-width
     	    (+ *menu-item-margin*
     	       (dolist (next-item items item-width)
     		 (setf item-width (max item-width
     				       (TEXT-EXTENTS menu-font (second next-item)))))))

           ;; Compute final menu width, taking margins into account
           (setf menu-width (max title-width (+ item-width *menu-item-margin*)))
           (let ((window     (menu-window menu)))

     	;; Update width and height of menu window
     	(WITH-STATE (window)
     		    (setf (DRAWABLE-WIDTH      window) menu-width
     			  (DRAWABLE-HEIGHT window) (* (1+ (length items)) item-height)))

     	;; Update width, height, position of item         windows
     	(let ((item-left         (round (- menu-width item-width) 2))
     	      (next-item-top (- item-height (round *menu-item-margin* 2))))
     	  (dolist (next-item items)
     	    (let ((window (first next-item)))
     	      (WITH-STATE (window)
     			  (setf (DRAWABLE-HEIGHT window) item-height
     				(DRAWABLE-WIDTH      window) item-width
     				(DRAWABLE-X          window) item-left
     				(DRAWABLE-Y          window) next-item-top)))
     	    (incf next-item-top item-height))))

           ;; Map all item windows
           (MAP-SUBWINDOWS (menu-window menu))

           ;; Save item geometry
           (setf (menu-item-width menu)         item-width
     	    (menu-item-height menu)        item-height
     	    (menu-width menu)              menu-width
     	    (menu-title-width menu)        title-width
     	    (menu-geometry-changed-p menu) nil))))

Of course, the sample client must know how to draw/redraw the menu and its items, so the function menu-refresh is defined next to handle that task (shown in the following example). Note that the location of window output is given relative to the window origin. Windows and subwindows have different coordinate systems. The location of the origin (upper-left corner) of a subwindow's coordinate system is given with respect to its parent window's coordinate system. Negative coordinates are valid, although only output to the +x/+y quadrant of a window's coordinate system will ever be visible.

     (defun menu-refresh (menu)
       (let* ((gcontext   (menu-gcontext menu))
     	 (baseline-y (FONT-ASCENT (GCONTEXT-FONT gcontext))))
         ;; Show title centered in "reverse-video"
         (let ((fg (GCONTEXT-BACKGROUND gcontext))
     	  (bg (GCONTEXT-FOREGROUND gcontext)))
           (WITH-GCONTEXT (gcontext :foreground fg :background bg)
     		     (DRAW-IMAGE-GLYPHS
     		      (menu-window menu)
     		      gcontext
     		      (round (- (menu-width menu)
     				(menu-title-width menu)) 2) ;start x
     		      baseline-y	;start y
     		      (menu-title menu))))

         ;; Show each menu item (position is relative to item window)
         (let ((box-margin (round *menu-item-margin* 2)))
           (dolist (item (menu-item-alist menu))
     	(DRAW-IMAGE-GLYPHS
     	 (first item) gcontext
     	 box-margin			;start x
     	 (+ baseline-y box-margin)	;start y
     	 (second item))))))

WITH-GCONTEXT (see with-gcontext) is a CLX macro that allows you temporarily to modify a graphics context within the dynamic scope of the macro body. DRAW-IMAGE-GLYPHS (see draw-image-glyphs) is a CLX text drawing function which produces a terminal-like rendering: foreground character on a background block. (More sophisticated text rendering functions are also available.) The strange use of glyphs instead of string here actually highlights an important fact: X and Common Lisp have totally different concepts of a character. A Common Lisp character is an object whose implementation can comprehend a vast universe of text complexities (typefaces, type styles, international character sets, symbols, and so forth). However, to X, a string is just a sequence of integer indexes into the array of bitmaps represented by a CLX font object. In general, DRAW-IMAGE-GLYPHS (see draw-image-glyphs), TEXT-EXTENTS (see text-extents), and other CLX text functions accept a :TRANSLATE keyword argument. Its value is a function which translates the characters of a string argument into the appropriate font-and-index pairs needed by CLX. This example relies upon the default translation function, which simply uses CHAR-CODE to compute an index into the current font.

Menu Input
----------

Now that a menu can be displayed, the sample client program must define how the menu will process user input. The menu-choose function (shown in the following example) has the classic structure of an X client program. First, do some initialization (for example, present the menu at a given location). Then, enter an input event loop. Read an input event, process it, and repeat the loop until a termination event is received. The EVENT-CASE (see event-case) macro continues reading an event from the menu window's display object until one of its clauses returns non-NIL. These clauses specify the action to be taken for each event type and also bind values from the event report to local variables, such as the EVENT-WINDOW receiving the event. Notice that the :FORCE-OUTPUT-P option is enabled, causing EVENT-CASE (see event-case) to begin by sending any client requests which CLX has not yet output to the server. To improve performance, CLX quietly queues up requests and periodically sends them off in a batch. However, in an interactive feedback loop such as this, it is important to keep the display crisply up-to-date.

     (defun menu-choose (menu x y)
       ;; Display the menu so that first item is at x,y.
       (menu-present menu x y)

       (let ((items (menu-item-alist menu))
     	(mw    (menu-window menu))
     	selected-item)

         ;; Event processing loop
         (do () (selected-item)
           (EVENT-CASE ((DRAWABLE-DISPLAY mw) :force-output-p t)
     		  (:exposure
     		   (count)
     		   ;; Discard all but final :exposure then display the menu
     		   (when (zerop count) (menu-refresh menu))
     		   t)

     		  (:button-release
     		   (event-window)
     		   ;;Select an item
     		   (setf selected-item (second (assoc event-window items)))
     		   t)

     		  (:enter-notify
     		   (window)
     		   ;;Highlight an item
     		   (menu-highlight-item menu (find window items :key #'first))
     		   t)

     		  (:leave-notify
     		   (window kind)
     		   (if (eql mw window)
     		       ;; Quit if pointer moved out of main menu window
     		       (setf selected-item (when (eq kind :ancestor) :none))
     		     ;; Otherwise, unhighlight the item window left
     		     (menu-unhighlight-item menu (find window items :key #'first)))
     		   t)

     		  (otherwise
     		   ()
     		   ;;Ignore and discard any other event
     		   t)))

         ;; Erase the menu
         (UNMAP-WINDOW mw)

         ;; Return selected item string, if any
         (unless (eq selected-item :none) selected-item)))

The event loop in menu-choose demonstrates an idiom used in all X programs: the contents of a window are displayed (in this case, by calling menu-refresh) only when an :EXPOSURE (see :exposure) event is received, signaling that the server has actually made the window viewable. The handling of :EXPOSURE (see :exposure) in menu-choose also implements a little trick for improving efficiency. In general, when a window is exposed after being previously obscured (perhaps only partially), the server is free to send several :EXPOSURE (see :exposure) events, one for each rectangular tile of the exposed region. For small windows like this menu, it is not worth the trouble to redraw the image one tile at a time. So the code above just ignores all but the last tile exposure and redraws everything in one call to menu-refresh.

The Main Program
----------------

After all the preceding build-up and the other functions referenced (but not shown here) have been implemented, the code for the main client program is very small.

     (defun just-say-lisp (host &optional (font-name "fg-16"))
       (let* ((display   (OPEN-DISPLAY host))
     	 (screen    (first (DISPLAY-ROOTS display)))
     	 (fg-color  (SCREEN-BLACK-PIXEL screen))
     	 (bg-color  (SCREEN-WHITE-PIXEL screen))
     	 (nice-font (OPEN-FONT display font-name))

     	 ;; Create a menu as a child of the root window.
     	 (a-menu       (create-menu (SCREEN-ROOT screen)
     				    fg-color bg-color nice-font)))

         (setf (menu-title a-menu) "Please pick your favorite language:")
         (menu-set-item-list a-menu "Fortran" "APL" "Forth" "Lisp")

         ;; Bedevil the user until he picks a nice programming language
         (unwind-protect
     	(loop
     	 ;; Determine the current root window position of the pointer
     	 (multiple-value-bind (x y) (QUERY-POINTER (SCREEN-ROOT screen))

     	   (let ((choice (menu-choose a-menu x y)))
     	     (when (string-equal "Lisp" choice)
     	       (return)))))

           (CLOSE-DISPLAY display))))

Note that the main program event loop lies in the body of an UNWIND-PROTECT form. This is a good programming technique because, without this protection, an unexpected error could cause the program to terminate without freeing the server resources it has created. Server resources are CLX objects which refer to objects actually stored on the X server. Examples of these are WINDOW (see window), FONT (see font), PIXMAP (see pixmap), CURSOR (see cursor), COLORMAP (see colormap), and GCONTEXT (see gcontext) objects. These server resources are created and destroyed by user requests. Server resources created by a client are also destroyed when its display connection is closed. If client resources are repeatedly created without being destroyed, then the server will eventually run out of memory and fail.

Most server resources are potentially sharable between applications. In fact, windows are manipulated explicitly by window manager programs. Fonts and cursors are typically shared automatically since the X server loads and unloads font storage as needed. GCONTEXT (see gcontext) objects are not ordinarily shared between client applications.

Debugging With CLX
------------------

Typically, most CLX programs do not need to control the buffering of output requests directly. However, CLX programmers need to be aware of the asynchronous nature of client-server communication. It may be convenient to control the CLX output buffer more directly, especially during debugging.

A client that wants a request to execute immediately instead of asynchronously can follow it with a call to DISPLAY-FORCE-OUTPUT (see display-force-output). This function blocks (does not return) until all previously buffered output requests have been sent. Otherwise, the output buffer is always flushed by a call to any function which returns a value from the server or which waits for input (for example, GET-PROPERTY (see get-property). Certain output requests can cause input events to be sent. For example, MAP-WINDOW (see map-window) can cause :EXPOSURE (see :exposure) events to be sent. Synchronizing output with the resulting input can be done with the DISPLAY-FINISH-OUTPUT (see display-finish-output) function. This function blocks until all previously buffered output has been sent and all resulting input events have been received.

Functions that return information from the server block until an explicit reply is received or an error occurs. If a nonblocking call results in an error, the error is generally not reported until later. All errors (synchronous and asynchronous) are processed by calling an error handler defined for the display. If the handler is a sequence it is expected to contain handler functions specific to each error. The error code is used to index the sequence, fetching the appropriate handler. Any results returned by the handler are ignored since it is assumed that the handler either takes care of the error completely, or else signals.

Naming and Argument Conventions
===============================

Throughout CLX, a number of conventions for naming and syntax of the CLX functions have been followed. These conventions are intended to make the syntax of the functions more predictable.

The major naming conventions are as follows:

  * To better differentiate the CLX symbols from other symbols, they have all been placed in the package XLIB. External symbols have been explicitly exported.

  * The display argument, where used, is always first in the argument list.

  * All server resource objects, where used, occur at the beginning of the argument list, immediately after the display variable.

  * When a graphics context (gcontext) is present together with another type of server resource (most commonly, a drawable), the graphics context occurs in the argument list after the other server resource. Drawables out rank all other server resources.

  * Source arguments always precede the destination arguments in the argument list.

  * The x argument always precedes the y argument in the argument list.

  * The width argument always precedes the height argument in the argument list.

  * Where the x, y, width and height arguments are used together, the x and y arguments always precede the width and height arguments.

  * Where a mask is accompanied with a structure, the mask always precedes the structure in the argument list.

Programming Considerations
==========================

The major programming considerations are as follows:

  * Keyboards are the greatest variable between different manufacturer's workstations. If you want your program to be portable, you should be particularly conservative here.

  * Many display systems have limited amounts of off-screen memory. If you can, you should minimize use of pixmaps and backing store.

  * The user should have control of his screen real-estate. Therefore, you should write your applications to react to window management, rather than presume control of the entire screen. What you do inside of your top level window, however, is up to your application.

  * Coordinates and sizes in X are actually 16-bit quantities. They usually are declared as an INT16 (see int16) in the functions. Values larger than 16 bits can be truncated silently. Sizes (width and height) are unsigned quantities.

  * The types COLOR (see color), COLORMAP (see colormap), CURSOR (see cursor), DISPLAY (see display), FONT (see font), GCONTEXT (see gcontext), PIXMAP (see pixmap), SCREEN (see screen), and WINDOW (see window) are defined solely by a functional interface. Even though they are treated like structures in this document, it is not specified whether they are implemented as structures or classes. Although some interfaces are described as functions, they are not required to be defined using DEFUN. (It is a requirement that they be functions as opposed to macros or special forms.)

Data Types
==========

The following are some data type definitions that are commonly used in CLX function definitions.

 -- Type: alist (key-type-and-name datum-type-and-name) 'list
     ALIST defines an association list. An association list is a sequence, containing zero or more repetitions of the given elements with each of the elements expressed as (type name).

 -- Type: angle `(number ,(* -2pi) ,(* 2pi))
     ANGLE defines an angle in units of radians and is bounded by (-2%pi;) and (2%pi;). Note that we are explicitly using a different angle representation than what is actually transmitted in the protocol.

 -- Type: arc-seq '(repeat-seq (int16 x) (int16 y) (card16 width) (card16 height) (angle angle1) (angle angle2))
     ARC-SEQ defines a six-tuple sequence of the form (x, y, width, height, angle1, angle2). The points x and y are signed, 16-bit quantities with a range from -32,768 to 32,767. The width and height values are unsigned, 16-bit quantities and range from 0 to 65,535. angle1 and angle2 are in units of radians, and bounded by (-2%pi;) and (2%pi;).

 -- Type: array-index `(integer 0 ,array-dimension-limit)
     ARRAY-INDEX defines a type which is a subtype of the integers and can be used to describe all variables that can be array indices. The range is inclusive because start and end array index specifiers can be one (1) past the end.

 -- Type: bit-gravity '(member gravity*)
     A keyword that specifies which region of a window should be retained when the window is resized.

     gravity -- One of the following:

       :CENTER

       :NORTH

       :SOUTH

       :STATIC

       :EAST

       :NORTH-EAST

       :SOUTH-EAST :WEST

       :FORGET

       :NORTH-WEST

       :SOUTH-WEST

     If a window is reconfigured without changing its inside width or height, then the contents of the window moves with the window and are not lost. Otherwise, the contents of a resized window are either moved or lost, depending on its bit-gravity attribute. See WINDOW-BIT-GRAVITY, in Window Attributes, for additional information.

 -- Type: bitmap '(array bit (* *))
     Specifies a two-dimensional array of bits.

 -- Structure: bitmap-format

     A structure that describes the storage format of a bitmap.

     The BITMAP-FORMAT structure contains slots for UNIT, PAD, and LSB-FIRST-P. The UNIT member indicates the unit of increments used to maintain the bitmap data. The units available for use are 8, 16, or 32 bits. The PAD member indicates how many bits are needed to pad the left edge of the scan-line. The LSB-FIRST-P member is a predicate which indicates the ordering of bits with the bitmap unit.

 -- Slot of bitmap-format: unit

     Type: (MEMBER 8 16 32).

     The size of a contiguous grouping of bits, which can be 8, 16, or 32. The default is 8.

 -- Slot of bitmap-format: pad

     Type: (MEMBER 8 16 32).

     The number of bits to left-pad the scan-line, which can be 8, 16, or 32. The default is 8.

 -- Slot of bitmap-format: lsb-first-p

     Type: BOOLEAN.

     A predicate indicating whether the least significant bit comes first (TRUE) or not (NIL).

 -- Type: boolean '(or nil (not nil))
     BOOLEAN defines a type which is all inclusive. It is used for variables that can take on a true (non-NIL) or false (NIL) value.

 -- Type: boole-constant `(member value*)

     BOOLE-CONSTANT defines a type that is a set of the values associated with the 16 boolean operation-code constants for the Common Lisp language. It is used for the set of allowed source and destination combination functions in a graphics context.

     value -- One of the following:

       BOOLE-1

       BOOLE-C1

       BOOLE-NAND

       BOOLE-XOR

       BOOLE-2

       BOOLE-C2

       BOOLE-NOR

       BOOLE-AND

       BOOLE-CLR

       BOOLE-ORC1

       BOOLE-ANDC1

       BOOLE-EQV

       BOOLE-ORC2

       BOOLE-ANDC2

       BOOLE-IOR

       BOOLE-SET

 -- Type: card8 '(unsigned-byte 8)
     An unsigned integer value that is a maximum of eight bits long. This gives a number of this type a range from 0 to 255.

 -- Type: card16 '(unsigned-byte 16)
     An unsigned integer value that is a maximum of 16 bits long. This gives a number of this type a range from 0 to 65,535.

 -- Type: card29 '(unsigned-byte 29)
     An unsigned integer value that is a maximum of 29 bits long. This gives a number of this type a range from 0 to 536,870,911.

 -- Type: card32 '(unsigned-byte 32)
     An unsigned integer value that is a maximum of 32 bits long. This gives a number of this type a range from 0 to 4,294,967,295.

 -- Type: color '(satisfies color-p)
     A COLOR. See Color Functions, for additional information.

 -- Type: colormap '(satisfies colormap-p)
     A COLORMAP. See Colormap Functions, for additional information.

 -- Type: cursor '(satisfies cursor-p)
     A CURSOR. See Cursors, for additional information.

 -- Type: device-event-mask '(or mask32 (list device-event-mask-class))

     Provides a way to specify a set of bits for an event bitmask. Two ways of specifying the bits are allowed: by setting the event bits in a 32 bit mask, or by listing the keyword names of the device related event bits in a list.

 -- Type: device-event-mask-class '(member event*)
     A keyword name, for a device related event, that corresponds to a particular bit in an event bitmask. The set of names is a subset of the names in the type EVENT-MASK-CLASS.

     event -- One of the following:

       :BUTTON-1-MOTION

       :BUTTON-MOTION

       :BUTTON-2-MOTION

       :BUTTON-PRESS

       :BUTTON-3-MOTION

       :KEY-PRESS

       :BUTTON-4-MOTION

       :KEY-RELEASE

       :BUTTON-5-MOTION

       :POINTER-MOTION

 -- Type: display '(satisfies display-p)
     A connection to an X server. See Displays, for additional information.

 -- Type: drawable '(or window pixmap)
     Both WINDOWS and PIXMAPS can be used as sources and destinations in graphics operations. WINDOWS and PIXMAPS together are known as drawables. However, an :INPUT-ONLY window cannot be used as a source or destination in a graphics operation.

 -- Type: draw-direction '(member :left-to-right :right-to-left)
     Defines a list of rotation directions for drawing arcs and fonts. DRAW-DIRECTION can have the values of :LEFT-TO-RIGHT or :RIGHT-TO-LEFT.

 -- Type: error-key '(member error*)
     Defines a list of all predefined errors. All errors (synchronous and asynchronous) are processed by calling an error handler in the display. The handler is called with the display as the first argument and the error-key as its second argument.

     error -- One of the following:

       :ACCESS

       :DRAWABLE

       :IMPLEMENTATION

       :VALUE

       :ALLOC

       :FONT

       :LENGTH

       :WINDOW

       :ATOM

       :GCONTEXT

       :MATCH

       :COLORMAP

       :ID-CHOICE

       :NAME

       :CURSOR

       :ILLEGAL-REQUEST

       :PIXMAP

 -- Type: event-key '(member event-type*)
     Defines a list that specifies all predefined event-types. Clients are informed of information asynchronously by means of events. These events can be either asynchronously generated from devices or generated as side effects of client requests.

     event-type -- One of the following:

       :BUTTON-PRESS

       :EXPOSURE

       :MOTION-NOTIFY

       :BUTTON-RELEASE

       :FOCUS-IN

       :NO-EXPOSURE

       :CIRCULATE-NOTIFY

       :FOCUS-OUT

       :PROPERTY-NOTIFY

       :CIRCULATE-REQUEST

       :GRAPHICS-EXPOSURE

       :REPARENT-NOTIFY

       :CLIENT-MESSAGE

       :GRAVITY-NOTIFY

       :RESIZE-REQUEST

       :COLORMAP-NOTIFY

       :KEYMAP-NOTIFY

       :SELECTION-CLEAR

       :CONFIGURE-NOTIFY

       :KEY-PRESS

       :SELECTION-NOTIFY

       :CONFIGURE-REQUEST

       :KEY-RELEASE

       :SELECTION-REQUEST

       :CREATE-NOTIFY

       :LEAVE-NOTIFY

       :UNMAP-NOTIFY

       :DESTROY-NOTIFY

       :MAP-NOTIFY

       :VISIBILITY-NOTIFY

       :ENTER-NOTIFY

       :MAP-REQUEST

 -- Type: event-mask '(or mask32 (list event-mask-class))
     Provides a way to specify a set of bits for an event bitmask. Two ways of specifying the bits are allowed: by setting the event bits in a 32 bit mask, or by listing the keyword names of the event bits in a list.

 -- Type: event-mask-class '(member event*)
     The elements of the type EVENT-MASK-CLASS are keyword names that correspond to a particular bit in an event bitmask.

     event -- One of the following:

       :BUTTON-1-MOTION

       :ENTER-WINDOW

       :POINTER-MOTION-HINT

       :BUTTON-2-MOTION

       :EXPOSURE

       :PROPERTY-CHANGE

       :BUTTON-3-MOTION

       :FOCUS-CHANGE

       :RESIZE-REDIRECT

       :BUTTON-4-MOTION

       :KEY-PRESS

       :STRUCTURE-NOTIFY

       :BUTTON-5-MOTION

       :KEY-RELEASE

       :SUBSTRUCTURE-NOTIFY

       :BUTTON-MOTION

       :KEYMAP-STATE

       :SUBSTRUCTURE-REDIRECT

       :BUTTON-PRESS

       :LEAVE-WINDOW

       :VISIBILITY-CHANGE

       :BUTTON-RELEASE

       :OWNER-GRAB-BUTTON

       :COLORMAP-CHANGE

       :POINTER-MOTION

 -- Function: make-event-keys event-mask
     Returns a list of EVENT-MASK-CLASS keyword names for the event bits that are set in the specified event mask.

     event-mask
          An event mask (type MASK32).

 -- Function: make-event-mask &rest keys

     keys
          EVENT-MASK-CLASS keywords.

     Constructs an event mask from a set of EVENT-MASK-CLASS keyword names.

     event-mask
          Type MASK32.

 -- Type: font '(satisfies font-p)

     A text font. See Font and Characters, for additional information.

 -- Type: fontable '(or stringable font)

     A FONTABLE is either a FONT object or the name of one of the fonts in the font database.

 -- Type: font-props 'list

     A LIST that contains alternating keywords and integers.

 -- Type: gcontext '(satisfies gcontext-p)

     A graphics context. See Graphics Contexts, for additional information.

 -- Type: gcontext-key '(member type*)

     A list of predefined types for use in GCONTEXT processing. Various information for graphics output is stored in a graphics context (GC or GContext), such as foreground pixel, background pixel, line width, clipping region, and so forth.

     TYPE -- One of the following:

       :ARC-MODE

       :EXPOSURES

       :LINE-WIDTH

       :BACKGROUND

       :FILL-RULE

       :PLANE-MASK

       :CAP-STYLE :FILL-STYLE

       :STIPPLE

       :CLIP-MASK

       :FONT

       :SUBWINDOW-MODE

       :CLIP-X

       :FOREGROUND

       :TILE

       :CLIP-Y

       :FUNCTION

       :TS-X

       :DASH-OFFSET

       :JOIN-STYLE

       :TS-Y

       :DASHES

       :LINE-STYLE

 -- Type: grab-status '(member grab-type*)

     There are two kinds of grabs: active and passive. An active grab occurs when a single client grabs the keyboard and/or pointer explicitly. Clients can also grab a particular keyboard key or pointer button in a window. The grab activates when the key or button is actually pressed, and is called a passive grab. Passive grabs can be very convenient for implementing reliable pop-up menus.

     GRAB-TYPE -- One of the following:

       :ALREADY-GRABBED

       :FROZEN

       :INVALID-TIME

       :NOT-VIEWABLE

       :SUCCESS

 -- Type: image-depth '(integer 0 32)
     Used in determining the depth of a pixmap, window, or image. The value specifies the number of bits deep that a given pixel has within a given pixmap, window, or image.

 -- Type: index-size '(member :default 8 16)
     Used to control the element size of the destination buffer given to the translate function when drawing glyphs. If :DEFAULT is specified, the size is based on the current font, if known; otherwise, 16 is used.

 -- Type: int8 '(signed-byte 8)
     A signed integer value that is a maximum of eight bits long. A number of this type can have a range from -128 to 127.

 -- Type: int16 '(signed-byte 16)
     A signed integer value that is a maximum of 16 bits long. A number of this type can have a range from -32,768 to 32,767.

 -- Type: int32 '(signed-byte 32)
     A signed integer value that is a maximum of 32 bits long. A number of this type can have a range from -2,147,483,648 to 2,147,483,647.

 -- Type: keysym 'card32
     Used as an encoding of a symbol on a keycap on a keyboard. It is an unsigned integer value represented in a maximum of 32 bits long. A KEYSYM type can have a range from 0 to 4,294,967,295.

 -- Type: mask16 ' card16
     A positional bitmask that contains 16 boolean flags.

 -- Type: mask32 ' card32
     A positional bitmask that contains 32 boolean flags.

 -- Type: modifier-key '(member modifier*)
     A keyword identifying one of the modifier keys on the keyboard device.

     MODIFIER -- One of the following:

       :SHIFT

       :MOD-2

       :LOCK

       :MOD-3

       :CONTROL

       :MOD-4

       :MOD-1

       :MOD-5

 -- Type: modifier-mask '(or (member :any) mask16 (list modifier-key))
     A bitmask or list of keywords that specifies a set of modifier keys. The keyword :ANY is equivalent to any subset of modifier key.

 -- Type: pixarray '(or (array pixel (* *)) (array card16 (* *)) (array card8 (* *)) (array (unsigned-byte 4) (* *)) (array bit (* *)))

     Specifies a two-dimensional array of pixels.

 -- Type: pixel '(unsigned-byte 32)

     An unsigned integer value that is a maximum of 32 bits long. This gives a pixel type a value range from 0 to 4,294,967,295. Useful values are dependent on the class of colormap being used.

 -- Type: pixmap '(satisfies pixmap-p)

     A PIXMAP, see Pixmaps), for additional information.

 -- Structure: pixmap-format

     A structure that describes the storage format of a pixmap.

     The PIXMAP-FORMAT structure contains slots for DEPTH, BITS-PER-PIXEL, and SCANLINE-PAD. The DEPTH member indicates the number of bit planes in the pixmap. The BITS-PER-PIXEL member indicates the number of bits used to represent a single pixel. For X, a pixel can be 1, 4, 8, 16, 24, or 32 bits wide. As for BITMAP-FORMAT, the SCANLINE-PAD member indicates how many pixels are needed to pad the left edge of the scan-line.

 -- Slot of pixmap-format: depth

     Type: IMAGE-DEPTH.

     The number of bit planes in the pixmap.

 -- Slot of pixmap-format: bits-per-pixel

     Type: (MEMBER 1 4 8 16 24 32).

     The number of consecutive bits used to encode a single pixel. The default is 8.

 -- Slot of pixmap-format: scanline-pad

     Type: (MEMBER 8 16 32).

     The number of bits to left-pad the scan-line, which can be 8, 16, or 32. The default is 8.

 -- Type: point-seq '(repeat-seq (int16 x) (int16 y))

     The POINT-SEQ type is used to define sequences of (X,Y) pairs of points. The paired values are 16-bit, signed integer quantities. This gives the points in this type a range from -32,768 to 32,767.

 -- Type: pointer-event-mask '(or mask32 (list pointer-event-mask-class))

     Provides a way to specify a set of bits for an event bitmask. Two ways of specifying the bits are allowed: by setting the event bits in a 32 bit mask, or by listing the keyword names of the pointer related event bits in a list.

 -- Type: pointer-event-mask-class '(member event*)

     A keyword name, for a pointer related event, that corresponds to a particular bit in an event bitmask. The set of names is a subset of the names in the type EVENT-MASK-CLASS.

     EVENT -- One of the following:

       :BUTTON-1-MOTION

       :BUTTON-MOTION

       :LEAVE-WINDOW

       :BUTTON-2-MOTION

       :BUTTON-PRESS

       :POINTER-MOTION

       :BUTTON-3-MOTION

       :BUTTON-RELEASE

       :POINTER-MOTION-HINT

       :BUTTON-4-MOTION

       :ENTER-WINDOW

       :BUTTON-5-MOTION

       :KEYMAP-STATE

 -- Type: rect-seq '(repeat-seq (int16 x) (int16 y) (card16 width) (card16 height))

     RECT-SEQ defines a four-tuple sequence of the form (X, Y, WIDTH, HEIGHT). The points X and Y are signed, 16-bit quantities with a range from -32,768 to 32,767. The WIDTH and HEIGHT values are unsigned, 16-bit quantities and range from 0 to 65,535.

 -- Type: repeat-seq (&rest elts) 'sequence

     A subtype used to define repeating sequences.

 -- Type: resource-id 'card29

     A numeric identifier that is assigned by the server to a server resource object.

 -- Type: rgb-val '(float 0.0 1.0)

     An RGB-VAL is a floating-point value between 0 and 1 that specifies a saturation for a red, green, or blue additive primary. The 0 value indicates no saturation and 1 indicates full saturation.

 -- Type: screen '(satisfies screen-p)

     A display screen. See Screens, for further information.

 -- Type: seg-seq '(repeat-seq (int16 x1) (int16 y1) (int16 x2) (int16 y2))

     Defines sequences of (X1, Y1, X2, Y2) sets of points. The point values are 16-bit, signed integer quantities. This gives the points in this type a range from -32,768 to 32,767.

 -- Type: state-mask-key '(or modifier-key (member button*))

     A keyword identifying one of the display modifier keys or pointer buttons whose state is reported in device events.

     BUTTON -- One of the following:

       :BUTTON-1

       :BUTTON-4

       :BUTTON-2

       :BUTTON-5

       :BUTTON-3

 -- Function: make-state-keys state-mask

     state-mask
          A 16-bit mask of type MASK16.

     Returns a list of STATE-MASK-KEY symbols corresponding to the STATE-MASK. A symbol belongs to the returned list if, and only if, the corresponding STATE-MASK bit is 1.

     state-keywords
          Type LIST.

 -- Function: make-state-mask &rest keys

     keys
          A list of STATE-MASK-KEY symbols.

     Returns a 16-bit MASK representing the given STATE-MASK-KEY symbols. The returned MASK contains a 1 bit for each keyword.

     mask
          Type MASK16.

 -- Type: stringable '(or string symbol)

     Used for naming something. This type can be either a string or a SYMBOL whose SYMBOL-NAME is used as the string containing the name. The case of the characters in the string is ignored when comparing stringables.

 -- Type: timestamp '(or null card32)

     An encoding of a time. NIL stands for the current time.

 -- Structure: visual-info

     A structure that represents a visual type. The elements of this structure are ID, CLASS, RED-MASK, GREEN-MASK, BLUE-MASK, BITS-PER-RGB, and COLORMAP-ENTRIES.

 -- Slot of visual-info: id

     Type: CARD29.

     A unique identification number.

 -- Slot of visual-info: class

     Type: (member :direct-color :gray-scale :pseudo-color :static-color :static-gray :true-color).

     The class of the visual type.

 -- Slots of visual-info: red-mask
 -- Slots of visual-info: green-mask
 -- Slots of visual-info: blue-mask

     Type: PIXEL.

     The RED-MASK, GREEN-MASK, and BLUE-MASK elements are only meaningful for the :DIRECT-COLOR and :TRUE-COLOR classes. Each mask has one contiguous set of bits with no intersections.

 -- Slot of visual-info: bits-per-rgb

     Type: CARD8.

     Specifies the log base 2 of the approximate number of distinct color values ( individually) of red, green, and blue. Actual RGB values are unsigned 16-bit numbers.

 -- Slot of visual-info: colormap-entries

     Type: CARD16.

     Defines the number of available colormap entries in a newly created colormap. For :DIRECT-COLOR and :TRUE-COLOR, this is the size of an individual pixel subfield.

 -- Type: win-gravity '(member gravity*)

     A keyword that specifies how to reposition a window when its parent is resized.

     GRAVITY -- One of the following:

       :CENTER

       :NORTH-WEST

       :STATIC

       :EAST

       :SOUTH

       :UNMAP

       :NORTH

       :SOUTH-EAST

       :WEST

       :NORTH-EAST

       :SOUTH-WEST

     If a parent window is reconfigured without changing its inside width or height, then all child windows move with the parent and are not changed. Otherwise, each child of the resized parent is moved, depending on the child's gravity attribute. See WINDOW-GRAVITY (see Window Attributes)), for additional information.

 -- Type: window '(satisfies window-p)

     A window. See Windows and Pixmaps, for additional information.

 -- Type: xatom '(or string symbol)

     A name that has been assigned a corresponding unique ID by the server. XATOMS are used to identify properties, selections, and types defined in the X server. An XATOM can be either a STRING or SYMBOL whose SYMBOL-NAME is used as the XATOM name. The case of the characters in the string are significant when comparing XATOMS.

Displays
********

A particular X server, together with its screens and input devices, is called a display. The CLX DISPLAY object contains all the information about the particular display and its screens, as well as the state that is needed to communicate with the display over a particular connection.

Before your program can use a display, you must establish a connection to the X server driving your display. Once you have established a connection, you then can use the CLX macros and functions discussed in this section to return information about the display.  This section discusses how to:

  * Open (connect) a display

  * Obtain information about a display

  * Access and change display attributes

  * Close (disconnect) a display

Opening the Display
===================

The OPEN-DISPLAY and OPEN-DEFAULT-DISPLAY functions are used to open a connection to an X server.  OPEN-DEFAULT-DISPLAY is an extension that is not present in the MIT CLX tree, but is preferred where available as it uses the same rules for display defaulting as the C Xlib bindings, and tends to get authorization right more often than OPEN-DISPLAY (particularly on ssh-forwarded connections)

 -- Function: open-display host &key :display :protocol

     host
          Specifies the name of the host machine on which the server executes. A string must be acceptable as a host, but otherwise the possible types are not constrained and will likely be very system dependent.

     :display
          An integer that specifies which display device on the host should be used for this connection. This is needed since multiple displays can be controlled by a single X server. The default is display 0 (zero).

     :protocol
          A keyword argument that specifies which network protocol should be used for connecting to the server (for example, :TCP, :DNA, or :CHAOS). The set of possible values and the default value are implementation specific.

     Returns a DISPLAY that serves as the connection to the X server and contains all the information about that X server.

     Authorization, if any, is assumed to come from the environment. After a successful call to OPEN-DISPLAY, all screens on the display can be used by the client application.

     display
          Type DISPLAY.

 -- Function: open-default-display &optional display-name

     display-name
          The display to connect to.  Display names have the format

            [protocol/] [hostname] : [:] displaynumber [.screennumber]

          There are two special cases in parsing, to match that done in the Xlib C language bindings

            * If the hostname is unix or the empty string, any supplied protocol is ignored and a connection is made using the local transport.

            * If a double colon separates HOSTNAME from DISPLAYNUMBER, the protocol is assumed to be decnet.

          If DISPLAY-NAME is not supplied, a default will be provided appropriate for the local environment: on a POSIX system - the only kind this CLX port runs on - the default display is taken from the environment variable DISPLAY.  See also the section ``DISPLAY NAMES'' in X(7)

     Open a connection to DISPLAY-NAME or to the appropriate default display.

     open-display-name always attempts to do display authorization, following complicated rules that closely match the ones that the C Xlib bindings use.  Briefly: the hostname is resolved to an address, then authorization data for the (protocol, host-address, displaynumber) triple is looked up in the file given by the environment variable AUTHORITY_PATHNAME (typically $HOME/.Xauthority).  If the protocol is :local, or if the hostname resolves to the local host, authority data for the local machine's actual hostname - as returned by gethostname(3) - is used instead.

Display Attributes
==================

The complete set of display attributes is discussed in the following paragraphs.

 -- Function: display-authorization-data display

     display
          A DISPLAY object.

     Returns the authorization data string for DISPLAY that was transmitted to the server by OPEN-DISPLAY during connection setup. The data is specific to the particular authorization protocol that was used. The DISPLAY-AUTHORIZATION-NAME function returns the protocol used.

     authorization-data
          Type STRING.

 -- Function: display-authorization-name display

     display
          A DISPLAY object.

     Returns the authorization protocol namestring for DISPLAY that was transmitted by OPEN-DISPLAY to the server during connection setup. The AUTHORIZATION-NAME indicates what authorization protocol the client expects the server to use. Specification of valid authorization mechanisms is not part of the X protocol. A server that implements a different protocol than the client expects, or a server that only implements the host-based mechanism, can simply ignore this information. If both name and data strings are empty, this is to be interpreted as "no explicit authorization."

     authorization-name
          Type STRING.

 -- Function: display-bitmap-format display

     display
          A DISPLAY object.

     Returns the bitmap-format information for the specified display.

     bitmap-format
          Type BITMAP-FORMAT.

 -- Function: display-byte-order display

     display
          A DISPLAY object.

     Returns the BYTE-ORDER to be employed in communication with the server for the given DISPLAY. The possible values are as follows:

     :lsbfirst
          Values are transmitted least significant byte first.

     :msbfirst
          Values are transmitted most significant byte first.

     Except where explicitly noted in the protocol, all 16-bit and 32-bit quantities sent by the client must be transmitted with this BYTE-ORDER, and all 16-bit and 32-bit quantities returned by the server are transmitted with this BYTE-ORDER.

     byte-order
          Either :LSBFIRST or :MSBFIRST.

 -- Function: display-display display

     display
          A DISPLAY object.

     Returns the DISPLAY-NUMBER for the host associated with DISPLAY.

     display-number
          Type INTEGER.

 -- Function: display-error-handler display

     display
          A DISPLAY object.

     Returns and (with setf) sets the ERROR-HANDLER function for the given DISPLAY. CLX calls (one of) the display error handler functions to handle server errors returned to the connection. The default error handler, DEFAULT-ERROR-HANDLER, signals conditions as they occur. See Errors, for a list of the conditions that CLX can signal. For more information about errors and error handling, refer to the section entitled Common Lisp Condition System in the Lisp Reference manual.

     If the value of ERROR-HANDLER is a sequence, it is expected to contain a handler function for each specific error. The error code is used as an index into the sequence to fetch the appropriate handler function. If this element is a function, it is called for all errors. Any results returned by the handler are ignored since it is assumed the handler either takes care of the error completely or else signals. The arguments passed to the handler function are the DISPLAY object, a symbol naming the type of error, and a set of keyword-value argument pairs that vary depending on the type of error. For all core errors, the keyword-value argument pairs are:

     :CURRENT-SEQUENCE   CARD16
     :MAJOR   CARD8
     :MINOR   CARD16
     :SEQUENCE   CARD16

     For COLORMAP, CURSOR, DRAWABLE, FONT, GCONTEXT, ID-CHOICE, PIXMAP, and WINDOW errors, the keyword-value pairs are the core error pairs plus:

     :RESOURCE-ID   CARD32

     For :ATOM errors, the keyword-value pairs are the core error pairs plus:

     :ATOM-ID   CARD32

     For :VALUE errors, the keyword-value pairs are the core error pairs plus:

     :VALUE   CARD32

     error-handler
          Type FUNCTION or SEQUENCE.

 -- Function: display-image-lsb-first-p display

     display
          A DISPLAY object.

     Although the server is generally responsible for byte swapping communication data to match the client, images (pixmaps/bitmaps) are always transmitted and received in formats (including byte order) specified by the server. Within images for each scan-line unit in bitmaps or for each pixel value in pixmaps, the leftmost bit in the image as displayed on the screen is either the least or most significant bit in the unit. For the given DISPLAY, DISPLAY-IMAGE-LSB-FIRST-P returns non-NIL if the leftmost bit is the least significant bit; otherwise, it returns NIL.

     image-lsb-first-p
          Type BOOLEAN.

 -- Function: display-keycode-range display

     display
          A DISPLAY object.

     Returns MIN-KEYCODE and MAX-KEYCODE as multiple values. See the DISPLAY-MAX-KEYCODE and DISPLAY-MIN-KEYCODE functions for additional information.

     min-keycode
     max-keycode
          Type CARD8.

 -- Function: display-max-keycode display

     display
          A DISPLAY object.

     Returns the maximum keycode value for the specified display. This value is never greater than 255. Not all keycodes in the allowed range are required to have corresponding keys.

     max-keycode
          Type CARD8.

 -- Function: display-max-request-length display

     display
          A DISPLAY object.

     Returns the maximum length of a request, in four-byte units, that is accepted by the specified display. Requests larger than this generate a length error, and the server will read and simply discard the entire request. This length is always at least 4096 (that is, requests of length up to and including 16384 bytes are accepted by all servers).

     max-request-length
          Type CARD16.

 -- Function: display-min-keycode display

     display
          A DISPLAY object.

     Returns the minimum keycode value for the specified DISPLAY. This value is never less than eight. Not all keycodes in the allowed range are required to have corresponding keys.

     min-keycode
          Type CARD8.

 -- Function: display-motion-buffer-size display

     display
          A DISPLAY object.

     Returns the approximate size of the motion buffer for the specified DISPLAY. The server can retain the recent history of pointer motion at a finer granularity than is reported by :MOTION-NOTIFY events. Such history is available through the MOTION-EVENTS function.

     motion-buffer-size
          Type CARD32.

 -- Function: display-p display

     display-p
          Type BOOLEAN.

     Returns non-NIL if display is a DISPLAY object;

 -- Function: display-pixmap-formats display

     display
          A DISPLAY object.

     Returns the list of PIXMAP-FORMAT values for the given display. This list contains one entry for each depth value. The entry describes the format used to represent images of that depth. An entry for a depth is included if any screen supports that depth, and all screens supporting that depth must support (only) the format for that depth.

     pixmap-formats
          Type LIST.

 -- Function: display-plist display

     display
          A DISPLAY object.

     Returns and (with setf) sets the property list for the specified display. This function provides a hook where extensions can add data.

     plist
          Type LIST.

 -- Function: display-protocol-major-version display

     display
          A DISPLAY object.

     Returns the major version number of the X protocol associated with the specified display. In general, the major version would increment for incompatible changes. The returned protocol version number indicates the protocol the server actually supports. This might not equal the version supported by the client. The server can (but need not) refuse connections from clients that offer a different version than the server supports. A server can (but need not) support more than one version simultaneously.

     protocol-major-version
          Type CARD16.

 -- Function: display-protocol-minor-version display

     display
          A DISPLAY object.

     Returns the minor protocol revision number associated with the specified display. In general, the minor version would increment for small upward compatible changes in the X protocol.

     protocol-minor-version
          Type CARD16.

 -- Function: display-protocol-version display

     display
          A DISPLAY object.

     Returns protocol-major-version and protocol-minor-version as multiple values. See the DISPLAY-PROTOCOL-MAJOR-VERSION and DISPLAY-PROTOCOL-MINOR-VERSION functions for additional information.

     protocol-major-version
     protocol-minor-version

 -- Function: display-resource-id-base display

     display
          A DISPLAY object.

     Returns the resource-id-base value that was returned from the server during connection setup for the specified display. This is used in combination with the resource-id-mask to construct valid IDs for this connection.

     resource-id-base
          Type RESOURCE-ID.

 -- Function: display-resource-id-mask display

     display
          A DISPLAY object.

     Returns the resource-id-mask that was returned from the server during connection setup for the specified display. The resource-id-mask contains a single contiguous set of bits (at least 18) which the client uses to allocate resource IDs for types WINDOW, PIXMAP, CURSOR, FONT, GCONTEXT, and COLORMAP by choosing a value with (only) some subset of these bits set, and ORing it with the resource-id-base. Only values constructed in this way can be used to name newly created server resources over this connection. Server resource IDs never have the top three bits set. The client is not restricted to linear or contiguous allocation of server resource IDs. Once an ID has been freed, it can be reused, but this should not be necessary.

     An ID must be unique with respect to the IDs of all other server resources, not just other server resources of the same type. However, note that the value spaces of server resource identifiers, atoms, visualids, and keysyms are distinguished by context, and as such are not required to be disjoint (for example, a given numeric value might be both a valid window ID, a valid atom, and a valid keysym.)

     resource-id-mask
          Type RESOURCE-ID.

 -- Function: display-roots display

     display
          A DISPLAY object.

     Returns a list of all the SCREEN structures available for the given display.

     roots
          A list of screens.

 -- Function: display-vendor display

     display
          A DISPLAY object.

     Returns vendor-name and release-number as multiple values. See the DISPLAY-VENDOR-NAME and DISPLAY-RELEASE-NUMBER functions for additional information.

     vendor-name
     release-number

 -- Function: display-vendor-name display

     display
          A DISPLAY object.

     Returns a string that provides some vendor identification of the X server implementation associated with the specified display.

     vendor-name
          Type STRING.

 -- Function: display-version-number display

     display
          A DISPLAY object.

     Returns the X protocol version number for this implementation of CLX.

     version-number
          Type CARD16.

 -- Function: display-xid display

     display
          A DISPLAY object.

     Returns the function that is used to allocate server resource IDs for this display.

     resource-allocator
          Type FUNCTION.

 -- Macro: with-display display &body body

     This macro is for use in a multi-process environment. WITH-DISPLAY provides exclusive access to the local DISPLAY object for multiple request generation. It need not provide immediate exclusive access for replies. That is, if another process is waiting for a reply (while not in a WITH-DISPLAY), then synchronization need not (but can) occur immediately. Except where noted, all routines effectively contain an implicit WITH-DISPLAY where needed, so that correct synchronization is always provided at the interface level on a per-call basis. Nested uses of this macro work correctly. This macro does not prevent concurrent event processing (see with-event-queue).

     display
          A DISPLAY.

Managing the Output Buffer
==========================

Most CLX functions cause output requests to be generated to an X server. Output requests are not transmitted immediately but instead are stored in an output buffer for the appropriate display. Requests in the output buffer are typically sent only when the buffer is filled. Alternatively, buffered requests can be sent prior to processing an event in the input event queue (see Processing Events). In either case, CLX sends the output buffer automatically without explicit instructions from the client application.

However, in some cases, explicit control over the output buffer is needed, typically to ensure that the X server is in a consistent state before proceeding further. The DISPLAY-FORCE-OUTPUT and DISPLAY-FINISH-OUTPUT functions allow a client program to synchronize with buffered output requests.

 -- Function: display-after-function display

     display
          A DISPLAY object.

     Returns and (with setf) sets the after-function for the given display. If after-function is non-NIL, it is a function that is called after every protocol request is generated, even those inside an explicit WITH-DISPLAY, but never called from inside the after-function. The function is called inside the effective WITH-DISPLAY for the associated request. The default value is NIL. This can be set, for example, to #'DISPLAY-FORCE-OUTPUT or #' DISPLAY-FINISH-OUTPUt.

     after-function
          Type FUNCTION or NULL.

 -- Function: display-force-output display

     display
          A DISPLAY object.

     Forces any buffered output to be sent to the X server.

 -- Function: display-finish-output display

     display
          A DISPLAY object.

     Forces any buffered output to be sent to the X server and then waits until all requests display error handler. Any events generated by output requests are read and stored in the event queue.

Closing the Display
===================

To close or disconnect a display from the X server, use CLOSE-DISPLAY.

 -- Function: close-display display

     display
          A DISPLAY object.

     Closes the connection to the X server for the specified DISPLAY. It destroys all server resources (WINDOW, FONT, PIXMAP, COLORMAP, CURSOR, and GCONTEXT), that the client application has created on this display, unless the close down mode of the server resource has been changed (see set-close-down-mode). Therefore, these server resources should never be referenced again. In addition, this function discards any output requests that have been buffered but have not yet been sent.

Screens
*******

Screens and Visuals
===================

An X display supports graphical output to one or more screens. Each screen has its own root window and window hierarchy. Each window belongs to exactly one screen and cannot simultaneously appear on another screen.

The kinds of graphics hardware used by X screens can vary greatly in their support for color and in their methods for accessing raster memory. X uses the concept of a visual type (usually referred to simply as a visual) which uniquely identifies the hardware capabilities of a display screen. Fundamentally, a visual is represented by a CARD29 integer ID, which uniquely identifies the visual type relative to a single display. CLX also represents a visual with a VISUAL-INFO structure that contains other attributes associated with a visual (see Data Types). A screen can support more than one depth (that is, pixel size), and for each supported depth, a screen may support more than one visual. However, it is more typical for a screen to have only a single depth and a single visual type.

A visual represents various aspects of the screen hardware, as follows:

  * A screen can be color or gray-scale.

  * A screen can have a colormap that is either writable or read-only.

  * A screen can have a single colormap or separate colormaps for each of the red, green, and blue components. With separate colormaps, a pixel value is decomposed into three parts to determine indexes into each of the red, green, and blue colormaps.

CLX supports the following classes of visual types: :DIRECT-COLOR, :GRAY-SCALE, :PSEUDO-COLOR, :STATIC-COLOR, :STATIC-GRAY, and :TRUE-COLOR. The following tables show how the characteristics of a screen determine the class of its visual type.

For screens with a single colormap:

Read-only   :STATIC-COLOR   :STATIC-GRAY
Writable   :PSEUDO-COLOR   :GRAY-SCALE

For screens with red, green, and blue colormaps:

Read-only   :TRUE-COLOR
Writable   :DIRECT-COLOR   :GRAY-SCALE

The visual class also indicates how screen colormaps are handled. see Colormaps and Colors).

Screen Attributes
=================

In CLX, each display screen is represented by a SCREEN structure. The DISPLAY-ROOTS function returns the list of SCREEN structures for the display. The following paragraphs discuss the attributes of CLX SCREEN structures.

 -- Function: screen-backing-stores screen

     screen
          A SCREEN.

     Returns a value indicating when the screen supports backing stores, although it may be storage limited in the number of windows it can support at once. The value returned can be one of :ALWAYS, :NEVER, or :WHEN-MAPPED.

     backing-stores-type
          One of :ALWAYS, :NEVER, or :WHEN-MAPPED.

 -- Function: screen-black-pixel screen

     screen
          A SCREEN.

     Returns the black pixel value for the specified screen.

     black-pixel
          Type PIXEL.

 -- Function: screen-default-colormap screen

     screen
          A SCREEN.

     Returns the default-colormap for the specified screen. The default-colormap is initially associated with the root window. Clients with minimal color requirements creating windows of the same depth as the root may want to allocate from this map by default. Most routine allocations of color should be made out of this colormap.

     default-colormap
          Type COLORMAP.

 -- Function: screen-depths screen

     screen
          A SCREEN.

     Returns an association list that specifies what drawable depths are supported on the specified screen. Elements of the returned association list have the form (depth visual*), where each visual is a VISUAL-INFO structure. Pixmaps are supported for each depth listed, and windows of that depth are supported if at least one visual type is listed for the depth.  A pixmap depth of one is always supported and listed, but windows of depth one might not be supported. A depth of zero is never listed, but zero-depth :INPUT-ONLY windows are always supported.

     depths
          Type ALIST.

 -- Function: screen-event-mask-at-open screen

     screen
          A SCREEN.

     Returns the initial root event mask for the specified screen.

     event-mask-at-open
          Type MASK32.

 -- Function: screen-height screen

     screen
          A SCREEN.

     Returns the height of the specified screen in pixel units.

     height
          Type CARD16.

 -- Function: screen-height-in-millimeters screen

     screen
          A SCREEN.

     Returns the height of the specified screen in millimeters. The returned height can be used with the width in millimeters to determine the physical size and the aspect ratio of the screen.

     height-in-millimeters
          Type CARD16.

 -- Function: screen-max-installed-maps screen

     screen
          A SCREEN.

     Returns the maximum number of colormaps that can be installed simultaneously with INSTALL-COLORMAP.

     max-installed-colormaps
          Type CARD16.

 -- Function: screen-min-installed-maps screen

     screen
          A SCREEN.

     Returns the minimum number of colormaps that can be guaranteed to be installed simultaneously.

     min-installed-colormaps
          Type CARD16.

 -- Function: screen-p screen

     screen-p
          Type BOOLEAN.

     Returns non-nil if the screen argument is a

 -- Function: screen-plist screen

     screen
          A SCREEN.

     Returns and (with setf) sets the property list for the specified screen. This function provides a hook where extensions can add data.

     plist
          Type LIST.

 -- Function: screen-root screen

     screen
          A SCREEN.

     Returns the root-window for the specified screen. This function is useful with functions that take a parent window as an argument. The class of the root window is always :INPUT-OUTPUT.

     root-window
          Type WINDOW or NULL.

 -- Function: screen-root-depth screen

     screen
          A SCREEN.

     Returns the depth of the root window for the specified screen. Other depths can also be supported on this screen.

     root-window-depth
          Type IMAGE-DEPTH.

 -- Function: screen-root-visual screen

     screen
          A SCREEN.

     Returns the default visual type for the root window for the specified screen.

     root-window-visual
          Type CARD29.

 -- Function: screen-save-unders-p screen

     screen
          A screen.

     If true, the server can support the save-under mode in CREATE-WINDOW and in changing window attributes.

     save-unders-p
          Type BOOLEAN.

 -- Function: screen-white-pixel screen

     screen
          A screen.

     Returns the white pixel value for the specified screen.

     white-pixel
          Type PIXEL.

 -- Function: screen-width screen

     screen
          A screen.

     Returns the width of the specified screen in pixel units.

     width
          Type CARD16.

 -- Function: screen-width-in-millimeters screen

     screen
          A screen.

     Returns the width of the specified screen in millimeters. The returned width can be used with the height in millimeters to determine the physical size and the aspect ratio of the screen.

     width-in-millimeters
          Type CARD16.

Windows and Pixmaps
*******************

Drawables
=========

Both windows and pixmaps can be used as sources and destinations in graphics operations. These are collectively known as drawables. The following functions apply to both windows and pixmaps.

 -- Function: drawable-display drawable

     drawable
          A DRAWABLE object.

     Returns the display for the specified drawable.

 -- Function: drawable-equal drawable-1 drawable-2

     drawable-1
     drawable-2
          DRAWABLE objects.

     Returns true if the two arguments refer to the same server resource, and NIL if they do not.

 -- Function: drawable-id drawable

     drawable
          A DRAWABLE object.

     Returns the unique resource ID assigned to the specified DRAWABLE.

     id
          Type RESOURCE-ID.

 -- Function: drawable-p drawable

     boole
          Type BOOLEAN.

     Returns true if the argument is a DRAWABLE and NIL otherwise.

 -- Function: drawable-plist drawable

     plist
          A property list.

     Returns and (with setf) sets the property list for the specified drawable. This function provides a hook where extensions can add data.

Creating Windows
================

A window is a DRAWABLE that can also receive input events. CLX represents a window with a WINDOW object. The CREATE-WINDOW function creates a new WINDOW object.

 -- Function: create-window &key :parent :x :y :width :height (:depth 0) (:border-width 0) (:class :copy) (:visual :copy) :background :border :gravity :bit-gravity :backing-store :backing-planes :backing-pixel :save-under :event-mask :do-not-propagate-mask :override-redirect :colormap :cursor

     :parent
          The parent window. This argument is required.

     :x
     :y
          INT16 coordinates for the outside upper-left corner of the new window with respect to the origin (inside upper-left corner) of the :PARENT. These arguments are required.

     :width
     :height

          CARD16 values for the size of the new window. These arguments are required.

     :depth

          A CARD16 specifying the depth of the new window.

     :class

          One of :INPUT-OUTPUt, :INPUT-ONLY, or :COPY.

     :visual

          A CARD29 ID specifying the visual type of the new window.

     :background
     :backing-pixel
     :backing-planes
     :backing-store
     :bit-gravity
     :border
     :border-width
     :colormap
     :cursor
     :do-not-propagate-mask
     :event
     :gravity
     :override-redirect
     :save-under

          Initial attribute values for the new window. If NIL, the default value is defined by the X protocol.See paragraph

     Creates and returns a window. A :PARENT window must be specified; the first window created by a client will have a root window as its :PARENT. The new window is initially unmapped and is placed on top of its siblings in the stacking order. A :CREATE-NOTIFY event is generated by the server.

     The :CLASS of a window can be :INPUT-OUTPUT or :INPUT-ONLY. Windows of class :INPUT-ONLY cannot be used as the destination drawable for graphics output and can never receive :EXPOSURE events, but otherwise operate the same as :INPUT-OUTPUT windows. The :CLASS can also be :COPY, in which case the new window has the same class as its :PARENT.

     For an :INPUT-OUTPUT window, the :VISUAL and :DEPTH must be a combination supported by the :PARENT's screen, but the :DEPTH need not be the same as the :PARENT's. The :PARENT of an :INPUT-OUTPUT window must also be :INPUT-OUTPUT. A :DEPTH of 0 means that the depth of the :PARENT is used.

     For an :INPUT-ONLY window, the :DEPTH must be zero, and the :VISUAL must be supported by the :PARENT's screen. The :PARENT of an :INPUT-ONLY window can be of any class. The only attributes that can be given for an :INPUT-ONLY window are :CURSOR, :DO-NOT-PROPAGATE-MASK, :EVENT-MASK, :GRAVITY, and :OVERRIDE-REDIRECT.

     window
          Type WINDOW.

Window Attributes
=================

The following paragraphs describe the CLX functions used to return or change window attributes. Using the WITH-STATE macro improves the performance of attribute access by batching related accesses in the minimum number of server requests.

 -- Function: drawable-border-width drawable

     drawable
          A DRAWABLE object.

     Returns the border-width of the drawable in pixels. It always returns zero if the drawable is a pixmap or an :INPUT-ONLY window. Used with setf, this function also changes the border width of the :INPUT-ONLY window. The default border width of a new window is zero.

     Changing just the border width leaves the outer left corner of a window in a fixed position but moves the absolute position of the window's origin. It is an error to make the border width of an :INPUT-ONLY window nonzero.

     When changing the border-width of a window, if the override-redirect attribute of the window is :OFF and some other client has selected :SUBSTRUCTURE-REDIRECT on the parent, a :CONFIGURE-REQUEST event is generated, and no further processing is performed.  Otherwise, the border-width is changed.

     border-width
          Type CARD16.

 -- Function: drawable-depth drawable

     drawable
          A DRAWABLE object.

     Returns the depth of the specified drawable (bits per pixel).

     depth
          Type CARD8.

 -- Function: drawable-height drawable

     inside-height
          Type CARD16.

 -- Function: drawable-width drawable

     drawable
          A DRAWABLE object.

     These functions return the height or width of the drawable. These coordinates define the inside size of the drawable, in pixels. Used with setf, these functions also change the inside height or width of a window. However, the height or width of a pixmap cannot be changed.

     Changing the width and height resizes a window without changing its position or stacking priority.

     Changing the size of a mapped window may cause the window to lose its contents and generate an :EXPOSURE event. If a mapped window is made smaller, :EXPOSURE events are generated on windows that it formerly obscured.

     When changing the size of a window, if the override-redirect attribute of the window is :OFF and some other client has selected :SUBSTRUCTURE-REDIRECT on the parent, a :CONFIGURE-REQUEST event is generated, and no further processing is performed. Otherwise, if another client has selected :RESIZE-REDIRECT on the window, a :RESIZE-REQUEST event is generated, and the current inside width and height are maintained. Note that the override-redirect attribute of the window has no effect on :RESIZE-REDIRECT and that :SUBSTRUCTURE-REDIRECT on the parent has precedence over :RESIZE-REDIRECT on the window.

     When the inside size of the window is changed, the children of the window can move according to their window gravity. Depending on the window's bit gravity, the contents of the window can also be moved.

     inside-width
          Type CARD16.

 -- Function: drawable-x drawable

     outside-left
          Type INT16.

 -- Function: drawable-y drawable

     drawable
          A DRAWABLE object.

     These functions return the x or y coordinate of the specified drawable. They always return zero if the drawable is a pixmap. These coordinates define the location of the top left pixel of the window's border or of the window, if it has no border. Used with setf, these functions also change the x or y coordinate of a window. However, the x or y coordinate of a pixmap cannot be changed.

     Changing the x and y coordinates moves a window without changing its size or stacking priority. Moving a mapped window generates :EXPOSURE events on any formerly obscured windows.

     When changing the position of a window, if the override-redirect attribute of the window is :OFF and some other client has selected :SUBSTRUCTURE-REDIRECT on the parent, a :CONFIGURE-REQUEST event is generated, and no further processing is performed.  Otherwise, the window is moved.

     outside-top
          Type INT16.

 -- Function: window-all-event-masks window

     window
          A WINDOW.

     Returns the inclusive-or of the event masks selected on the specified window by all clients.

     all-event-masks
          Type MASK32.

 -- Function: setf (window-background) window background

     window
          A WINDOW.

     background
          Either a PIXEL, a PIXMAP, :NONE, or :PARENT-RELATIVE.

     Changes the background attribute of the window to the specified value. This operation is not allowed on an :INPUT-ONLY window. Changing the background does not cause the window contents to be changed. Note that the background of a window cannot be returned from the X server. The default background of a new window is :NONE.

     In general, the server automatically fills in exposed areas of the window when they are first made visible. A background pixmap is tiled to fill each area. However, if the background is :NONE, the server will not modify exposed areas. If the background is :PARENT-RELATIVE, the window and its parent must have the same depth. In this case, the window shares the same background as its parent. The parent's background is not copied and is reexamined whenever the window's background is required. If the background is :PARENT-RELATIVE, the background pixmap tile origin is the same as the parent's; otherwise, the tile origin is the window origin.

     background
          Either a PIXEL, a PIXMAP, :NONE, or :PARENT-RELATIVE.

 -- Function: window-backing-pixel window

     window
          A WINDOW.

     Returns and (with setf) changes the value of the backing-pixel attribute for the specified window. Changing the backing-pixel attribute of a mapped window may have no immediate effect. The default backing-pixel of a new window is zero.

     backing-pixel
          Type PIXEL.

 -- Function: window-backing-planes window

     window
          A WINDOW.

     Returns and (with setf) changes the value of the backing-planes attribute for the specified window. Changing the backing-planes attribute of a mapped window may have no immediate effect. The default backing-planes of a new window is all one's.

     backing-planes
          Type PIXEL.

 -- Function: window-backing-store window

     window
          A WINDOW.

     Returns and (with setf) changes the value of the backing-store attribute for the specified window. Changing the backing-store attribute of an obscured window to :WHEN-MAPPED or :ALWAYS may have no immediate effect. The default backing-store of a new window is :NOT-USEFUL.

     backing-store-type
          One of :ALWAYS, :NOT-USEFUL, or :WHEN-MAPPED.

 -- Function: window-bit-gravity window

     window
          A WINDOW.

     Returns and (with setf) changes the bit-gravity attribute of the window. If a window is reconfigured without changing its inside width or height, the contents of the window move with the window and are not lost. Otherwise, the contents of the resized window are either moved or lost, depending on its bit-gravity attribute. The default bit-gravity of a new window is :FORGET.

     For example, suppose a window's size is changed by W pixels in width and H pixels in height. The following table shows, for each bit-gravity value, the change in position (relative to the window origin) that results for each pixel of the window contents.

     :CENTER   W/2   H/2
     :EAST   W   H/2
     :NORTH   W/2   0
     :NORTH-EAST   W   0
     :NORTH-WEST   0   0
     :SOUTH   W/2   H
     :SOUTH-EAST   W   H
     :SOUTH-WEST   0   H
     :WEST   0   H/2

     A :STATIC bit-gravity indicates the contents or window should not move relative to the origin of the root window.

     A server can choose to ignore the specified bit-gravity attribute and use :FORGET instead.  A :FORGET bit-gravity attribute indicates that the window contents are always discarded after a size change, even if backing-store or save-under attributes are :ON. The window's background is displayed (unless it is :NONE), and zero or more :EXPOSURE events are generated.

     bit-gravity
          Type BIT-GRAVITY.

 -- Function: setf (window-border) window border

     window
          A WINDOW.

     border
          Either a PIXEL, a PIXMAP, or :COPY.

     Changes the border attribute of the window to the specified value. This operation is not allowed on an :INPUT-ONLY window. Changing the border attribute also causes the window border to be repainted. Note that the border of a window cannot be returned from the X server. The default border of a new window is :COPY.

     A border pixmap is tiled to fill the border. The border pixmap tile origin is the same as the background tile origin. A border pixmap and the window must have the same root and depth. If the border is :COPY, the parent's border is copied and used; subsequent changes to the parent's border do not affect the window border.

     border
          Either a PIXEL, a PIXMAP, or :COPY.

 -- Function: window-class window

     window
          A WINDOW.

     Returns the class of the specified window.

     class
          Either :INPUT-OUTPUT or :INPUT-ONLY.

 -- Function: window-colormap window

     window
          A WINDOW.

     Returns and (with setf) changes the value of the colormap attribute for the specified window. A value of :COPY is never returned, since the parent's colormap attribute is actually copied, but the attribute can be set to :COPY in a setf form. Changing the colormap of a window (defining a new map, not changing the contents of the existing map) generates a :COLORMAP-NOTIFY event. Changing the colormap of a visible window may have no immediate effect on the screen (see install-colormap). The default colormap of a new window is :COPY.

     colormap
          Type COLORMAP or NULL.

 -- Function: window-colormap-installed-p window

     window
          A WINDOW.

     Returns non-NIL if the colormap associated with this window is installed. Otherwise, this function returns NIL.

     colormap-installed-p
          Type BOOLEAN.

 -- Function: setf (window-cursor) window cursor

     window
          A WINDOW.

     cursor
          Either CURSOR or :NONE.

     Changes the cursor attribute of the window to the specified value. Changing the cursor of a root window to :NONE restores the default cursor. Note that the cursor of window cannot be returned from the X server. The default cursor of a new window is :NONE.

     cursor
          Type CURSOR or :NONE.

 -- Function: window-display window

     window
          A WINDOW.

     Returns the DISPLAY object associated with the specified window.

     display
          Type DISPLAY.

 -- Function: window-do-not-propagate-mask window

     window
          A WINDOW.

     Returns and (with setf) changes the do-not-propagate-mask attribute for the window.  The default do-not-propagate-mask of a new window is zero.

     If a window receives an event from one of the user input devices, and if no client has selected to receive the event, the event can instead be propagated up the window hierarchy to the first ancestor for which some client has selected it. However, any event type selected by the do-not-propagate-mask is not be propagated. The types of events that can be selected by the do-not-propagate-mask are those of type DEVICE-EVENT-MASK-CLASS. See Selecting Events.

     do-not-propagate-mask
          Type MASK32.

 -- Function: window-equal window-1 window-2

     window-1
     window-2
          The windows to compare for equality.

     Returns non-NIL if the two arguments are the same window, and NIL if they are not.

     equal-p
          Type BOOLEAN.

 -- Function: window-event-mask window

     window
          A WINDOW.

     Returns and (with setf) changes the value of the event-mask attribute for the window.  The default event-mask of a new window is zero.

     event-mask
          Type MASK32.

 -- Function: window-gravity window

     window
          A WINDOW.

     Returns and (with setf) changes the gravity attribute of the window. If a parent window is reconfigured without changing its inside width or height, then all child windows move with the parent and are not changed. Otherwise, each child of the resized parent is moved, depending on the child's gravity attribute. The default gravity of a new window is :NORTH-WEST.

     For example, suppose the size of the window's parent is changed by W pixels in width and H pixels in height. The following table shows, for each possible gravity value, the resulting change in the window's position relative to its parent's origin. When the window is moved, two events are generated--a :CONFIGURE-NOTIFY event followed by a :GRAVITY-NOTIFY event.

     :CENTER   W/2   H/2
     :EAST   W   H/2
     :NORTH   W/2   0
     :NORTH-EAST   W   0
     :NORTH-WEST   0   0
     :SOUTH   W/2   H
     :SOUTH-EAST   W   H
     :SOUTH-WEST   0   H
     :WEST   0   H/2

     A :STATIC gravity indicates that the position of the window should not move relative to the origin of the root window.

     An :UNMAP gravity is like :NORTH-WEST, except the window is also unmapped and an :UNMAP-NOTIFY event is generated. This :UNMAP-NOTIFY event is generated after the :CONFIGURE-NOTIFY event is generated for the parent.

     gravity
          Type WIN-GRAVITY.

 -- Function: window-id window

     window
          A WINDOW.

     Returns the unique ID assigned to window.

     id
          Type RESOURCE-ID.

 -- Function: window-map-state window

     window
          A WINDOW.

     Returns the map state of window. A window is :UNVIEWABLE if it is mapped but some ancestor is unmapped.

     map-state
          One of :UNMAPPED, :UNVIEWABLE, or :VIEWABLE.

 -- Function: window-override-redirect window

     window
          A WINDOW.

     Returns and (with setf) changes the value of the override-redirect attribute for window.  The default override-redirect of a new window is :OFF.

     The override-redirect attribute determines whether or not attempts to change window geometry or parent hierarchy can be redirected by a window manager or some other client. The functions that might be affected by the override-redirect attribute are CIRCULATE-WINDOW-DOWN, CIRCULATE-WINDOW-UP, DRAWABLE-BORDER-WIDTH, DRAWABLE-HEIGHT, DRAWABLE-WIDTH, DRAWABLE-X, DRAWABLE-Y, MAP-WINDOW, and WINDOW-PRIORITY.

     override-redirect
          Either :ON or :OFF.

 -- Function: window-p object

     window-p
          Type BOOLEAN.

     Returns non-NIL if the object argument is a window; otherwise, it returns NIL.

 -- Function: window-plist window

     window
          A WINDOW.

     Returns and (with setf) sets the property list for the specified window. This function provides a hook where extensions can hang data.

     plist
          A property list.

 -- Function: setf (window-priority window) (&optional sibling) mode

     window
          A WINDOW.

     sibling
          An optional argument specifying that window is to be restacked relative to this sibling WINDOW.

     mode
          One of :ABOVE, :BELOW, :BOTTOM-IF, :OPPOSITE, or :TOP-IF.

     Changes the stacking priority element of the window to the specified value. It is an error if the sibling argument is specified and is not actually a sibling of the window. Note that the priority of an existing window cannot be returned from the X server.

     When changing the priority of a window, if the override-redirect attribute of the window is :OFF and some other client has selected :substructure-redirect on the parent, a :configure-request event is generated, and no further processing is performed. Otherwise, the priority is changed.

     mode
          One of :ABOVE, :BELOW, :BOTTOM-IF, :OPPOSITE, or :TOP-IF.

 -- Function: window-save-under window

     window
          A WINDOW.

     Returns and (with setf) changes the value of the save-under attribute for the specified window. Changing the save-under attribute of a mapped window may have no immediate effect.

     save-under
          Either :ON or :OFF.

 -- Function: window-visual window

     window
          A WINDOW.

     Returns the visual-type associated with the specified window.

     visual-type
          Type CARD29.

 -- Macro: with-state drawable &body body

     Batches successive read and write accesses to window attributes and drawable geometry, in order to minimize the number of requests sent to the server. Batching occurs automatically within the dynamic extent of the body. The body is not executed within a WITH-DISPLAY form.

     All window attributes can be returned or changed in a single request. Similarly, all drawable geometry values can be returned or changed in a single request. WITH-STATE combines accesses to these values into the minimum number of server requests necessary to guarantee that each read access returns the current server state of the drawable.  The number of server requests sent depends on the sequence of calls to reader and setf functions within the dynamic extent of the body. There are two groups of reader and setf functions--the Window Attributes group and the Drawable Geometry group--as shown in Table 4-1.

     Window Attributes   WINDOW-ALL-EVENT-MASKS   WINDOW-BACKGROUND

       WINDOW-BACKING-PIXEL   WINDOW-BACKING-PIXEL
       WINDOW-BACKING-PLANES   WINDOW-BACKING-PLANES
       WINDOW-BACKING-STORE   WINDOW-BACKING-STORE
       WINDOW-BIT-GRAVITY   WINDOW-BIT-GRAVITY
       WINDOW-CLASS   WINDOW-BORDER
       WINDOW-COLORMAP   WINDOW-COLORMAP
       WINDOW-COLORMAP-INSTALLED-P   WINDOW-CURSOR
       WINDOW-DO-NOT-PROPAGATE-MASK   WINDOW-DO-NOT-PROPAGATE-MASK
       WINDOW-EVENT-MASK   WINDOW-EVENT-MASK
       WINDOW-GRAVITY   WINDOW-GRAVITY
       WINDOW-MAP-STATE
       WINDOW-OVERRIDE-REDIRECT   WINDOW-OVERRIDE-REDIRECT
       WINDOW-SAVE-UNDER   WINDOW-SAVE-UNDER
       WINDOW-VISUAL

     Drawable Geometry   DRAWABLE-BORDER-WIDTH   DRAWABLE-BORDER-WIDTH

       DRAWABLE-DEPTH   DRAWABLE-HEIGHT
       DRAWABLE-HEIGHT   DRAWABLE-WIDTH
       DRAWABLE-ROOT   DRAWABLE-X
       DRAWABLE-WIDTH   DRAWABLE-Y
       DRAWABLE-X   WINDOW-PRIORITY
       DRAWABLE-Y

     The results from a sequence of calls to setf functions in a given group are cached and sent in a single server request, either upon exit from the body or when a reader function from the corresponding group is called.

     WITH-STATE sends a single request to update all its cached values for the drawable before the first call to a reader function within the body and also before the first call to a reader function following a sequence of calls to setf functions from the corresponding group.

     drawable
          A DISPLAY.

     body
          The forms in which attributes accesses are batched.

Stacking Order
==============

Sibling windows can stack on top of each other. Windows above can obscure or occlude lower windows. This relationship between sibling windows is known as the stacking order. The WINDOW-PRIORITY function can be used to change the stacking order of a single window. CLX also provides functions to raise or lower children of a window.  Raising a mapped window can generate :EXPOSURE events for the window and any mapped subwindows that were formerly obscured. Lowering a mapped window can generate :EXPOSURE events on any windows it formerly obscured.

 -- Function: circulate-window-down window

     window
          A WINDOW.

     Lowers the highest mapped child of the specified window that partially or completely occludes another child to the bottom of the stack. Completely unobscured children are unaffected. Exposure processing is performed on formerly obscured windows.

     If some other client has selected :SUBSTRUCTURE-REDIRECT on the window, a :CIRCULATE-REQUEST event is generated, and no further processing is performed. Otherwise, the child window is lowered and a :CIRCULATE-NOTIFY event is generated if the window is actually restacked.

 -- Function: circulate-window-up window

     window
          A WINDOW.

     Raises the lowest mapped child of the specified window that is partially or completely occluded by another child to the top of the stack. Completely unobscured children are unaffected. Exposure processing is performed on formerly obscured windows.

     If another client has selected :SUBSTRUCTURE-REDIRECT on the window, a :CIRCULATE-REQUEST event is generated, and no further processing is performed. Otherwise, the child window is raised and a :CIRCULATE-NOTIFY event is generated if the window is actually restacked.

Window Hierarchy
================

All the windows in X are arranged in a strict hierarchy. At the top of the hierarchy are the root windows, which cover the display screens. Each root window is partially or completely covered by its child windows. All windows, except for root windows, have parents. Child windows can have their own children. In this way, a tree of arbitrary depth on each screen can be created. CLX provides several functions for examining and modifying the window hierarchy.

 -- Function: drawable-root drawable

     drawable
          A DRAWABLE.

     Returns the root window of the specified drawable.

     root-window
          Type WINDOW.

 -- Function: query-tree window &key (:result-type `list)

     window
          A WINDOW.

     :result-type
          A valid type specifier for a sub-type of SEQUENCE. The default is a LIST.

     Returns the children windows, the parent window, and the root window for the specified window. The children are returned as a sequence of windows in current stacking order, from bottom-most (first) to top-most (last). The :RESULT-TYPE specifies the type of children sequence returned.

     children
          Type SEQUENCE of WINDOW.

     parent
          Type WINDOW or NULL.

     root
          Type WINDOW.

 -- Function: reparent-window window parent x y

     window
          A WINDOW.

     parent
          The new parent WINDOW.

     x
     y
          The position (type INT16) of the window in its new parent. These coordinates are relative to the parent's origin, and specify the new position of the upper, left, outer corner of the window.

     Changes a window's parent within a single screen. There is no way to move a window between screens.

     The specified window is reparented by inserting it as a child of the specified parent. If the window is mapped, an UNMAP-WINDOW operation is automatically performed on the specified window. The window is then removed from its current position in the hierarchy and inserted as the child of the specified parent. The window is placed on top in the stacking order with respect to sibling windows.

     After reparenting the specified window, a :REPARENT-NOTIFY event is generated. The override-redirect attribute of the window is passed on in this event. Window manager clients normally should ignore this event if this attribute is :ON. See Events and Input, for more information on :REPARENT-NOTIFY event processing. Finally, if the specified window was originally mapped, a MAP-WINDOW operation is automatically performed on it.

     The X server performs normal exposure processing on formerly obscured windows. It might not generate :EXPOSURE events for regions from the initial UNMAP-WINDOW operation if they are immediately obscured by the final MAP-WINDOW operation.

     It is an error if any of the following are true:

       * The new parent window is not on the same screen as the old parent window.

       * The new parent window is the specified window or an inferior of the specified window.

       * The specified window has a :PARENT-RELATIVE background attribute and the new parent window is not the same depth as the specified window.

 -- Function: translate-coordinates source source-x source-y destination

     source
          A WINDOW defining the source coordinate system.

     source-x
     source-y
          Coordinates (INT16) relative to the origin of the source WINDOW.

     destination
          A WINDOW defining the destination coordinate system.

     Returns the position defined by source-x and source-y (relative to the origin of the source window), expressed as coordinates relative to the origin of the destination window.

     destination-x
          Type INT16 or NULL.

     destination-y
          Type INT16 or NULL.

     destination-child
          Type WINDOW or NULL.

Mapping Windows
===============

A window is considered mapped if a MAP-WINDOW call has been made on it. When windows are first created, they are not mapped because an application may wish to create a window long before it is mapped to the screen. A mapped window may not be visible on the screen for one of the following reasons:

  * It is obscured by another opaque sibling window.

  * One of its ancestors is not mapped.

  * It is entirely clipped by an ancestor.

A subwindow will appear on the screen as long as all of its ancestors are mapped and not obscured by a sibling or clipped by an ancestor. Mapping a window that has an unmapped ancestor does not display the window, but marks it as eligible for display when the ancestor becomes mapped. Such a window is called unviewable. When all its ancestors are mapped, the window becomes viewable and remains visible on the screen if not obscured by any sibling or ancestor.

Any output to a window not visible on the screen is discarded. :EXPOSURE events are generated for the window when part or all of it becomes visible on the screen. A client only receives the :EXPOSURE events if it has selected them. Mapping or unmapping a window does not change its stacking order priority.

 -- Function: map-window window

     window
          A WINDOW.

     Maps the window. This function has no effect when the window is already mapped.

     If the override-redirect attribute of the window is :OFF and another client has selected :SUBSTRUCTURE-REDIRECT on the parent window, the X server generates a :MAP-REQUEST event and the MAP-WINDOW function does not map the window. Otherwise, the window is mapped, and the X server generates a :MAP-NOTIFY event.

     If the window becomes visible and no earlier contents for it are remembered, MAP-WINDOW tiles the window with its background. If no background was defined for the window, the existing screen contents are not altered, and the X server generates one or more :EXPOSURE events. If a backing-store was maintained while the window was unmapped, no :EXPOSURE events are generated. If a backing-store will now be maintained, a full window exposure is always generated. Otherwise, only visible regions may be reported.  Similar tiling and exposure take place for any newly viewable inferiors.

     MAP-WINDOW generates :EXPOSURE events on each :INPUT-OUTPUT window that it causes to become visible.

 -- Function: map-subwindows window

     window
          A WINDOW.

     Maps all child windows for a specified window in top-to-bottom stacking order. The X server generates an :EXPOSURE event on each newly visible window. This function is much more efficient than mapping each child individually.

 -- Function: unmap-window window

     window
          A WINDOW.

     Unmaps the specified window and causes the X server to generate an :UNMAP-NOTIFY event. If the specified window is already unmapped, UNMAP-WINDOW has no effect.  Normal exposure processing on formerly obscured windows is performed. Any child window is no longer viewable. Unmapping the window generates :EXPOSURE events on windows that were formerly obscured by window and its children.

 -- Function: unmap-subwindows window

     window
          A WINDOW.

     Unmaps all child windows for the specified window in bottom to top stacking order. The X server generates an :UNMAP-NOTIFY event on each child and :EXPOSURE events on formerly obscured windows. Using this function is much more efficient than unmapping child windows individually.

Destroying Windows
==================

CLX provides functions to destroy a window or destroy all children of a window. Note that by default, windows are destroyed when a connection is closed. For further information, see Closing the Display, and see Client Termination.

 -- Function: destroy-window window

     window
          A WINDOW.

     Destroys the specified window as well as all of its inferiors. The windows should never again be referenced. If the specified window is mapped, it is automatically unmapped.  The window and all of its inferiors are then destroyed, and a :DESTROY-NOTIFY event is generated for each window. The ordering of the :DESTROY-NOTIFY events is such that for any given window being destroyed, :DESTROY-NOTIFY is generated on the window's inferiors before being generated on the window. The ordering among siblings and across sub-hierarchies is not otherwise constrained. If the window is a root window, no windows are destroyed. Destroying a mapped window generates :EXPOSURE events on other windows that the mapped window obscured.

 -- Function: destroy-subwindows window

     window
          A WINDOW.

     Destroys all inferiors of the specified window, in bottom to top stacking order. The X server generates a :DESTROY-NOTIFY event for each window. This is much more efficient than deleting many windows individually. The inferiors should never be referenced again.

Pixmaps
=======

A pixmap is a three-dimensional array of bits. A pixmap is normally thought of as a two-dimensional array of pixels, where each pixel can be a value from 0 to 2n-1, where n is the depth of the pixmap. A pixmap can also be thought of as a stack of n bitmaps. A bitmap is a single bit pixmap of depth 1. CLX provides functions to:

  * Create or free a pixmap

  * Test if an object is a pixmap

  * Test if two pixmap objects are equal

  * Return the pixmap resource ID from a PIXMAP object

Note that pixmaps can only be used on the screen where they were created. Pixmaps are off-screen server resources that are used for a number of operations. These include defining patterns for cursors or as the source for certain raster operations.

 -- Function: create-pixmap &key :width :height :depth :drawable

     :width
     :height
          The nonzero width and height (type CARD16).

     :depth
          The depth (type CARD8) of the pixmap.

     :drawable
          A DRAWABLE which determines the screen where the pixmap will be used.

     Creates a pixmap of the specified :WIDTH, :HEIGHT, and :DEPTH. It is valid to pass a window whose class is :INPUT-ONLY as the :DRAWABLE argument. The :WIDTH and :HEIGHT arguments must be nonzero. The :DEPTH must be supported by the screen of the specified :DRAWABLE.

     pixmap
          Type PIXMAP.

 -- Function: free-pixmap pixmap

     pixmap
          A PIXMAP.

     Allows the X server to free the pixmap storage when no other server resources reference it. The pixmap should never be referenced again.

 -- Function: pixmap-display pixmap

     pixmap
          A PIXMAP.

     Returns the DISPLAY object associated with the specified pixmap.

     display
          Type DISPLAY.

 -- Function: pixmap-equal pixmap-1 pixmap-2

     pixmap-1
     pixmap-2
          A three-dimensional array of bits to be tested.

     Returns true if the two arguments refer to the same server resource, and NIL if they do not.

 -- Function: pixmap-id pixmap

     pixmap
          A PIXMAP.

     Returns the unique resource ID that has been assigned to the specified pixmap.

     id
          Type RESOURCE-ID.

 -- Function: pixmap-p object

     pixmap
          Type BOOLEAN.

     Returns true if the argument is a PIXMAP object and NIL otherwise.

 -- Function: pixmap-plist pixmap

     pixmap
          A PIXMAP.

     Returns and (with setf) sets the property list for the specified pixmap. This function provides a hook where extensions can add data.

     plist
          A property list.

Graphics Contexts
*****************

Clients of the X Window System specify the visual attributes of graphical output primitives by using graphics contexts. A graphics context is a set of graphical attribute values such as foreground color, font, line style, and so forth. Like a window, a graphics context is another kind of X server resource which is created and maintained at the request of a client program. The client program, which may use several different graphics contexts at different times, is responsible for specifying a graphics context to use with each graphical output function.

CLX represents a graphics context by an object of type GCONTEXT and defines functions to create, modify, and manipulate GCONTEXT objects. By default, CLX also records the contents of graphics contexts in a cache associated with each display. This local caching of graphics contexts has two important advantages:

 1. Communication efficiency -- Changes to attribute values in a GCONTEXT are first made only in the local cache. Just before a GCONTEXT is actually used, CLX automatically sends any changes to the X server, batching all changes into a single request.

 2. Inquiring GCONTEXT contents -- Accessor functions can be used to return the value of any individual GCONTEXT component by reading the copy of the GCONTEXT from the cache. This kind of inquiry is not supported by the basic X protocol. There is no way for a client program to request an X server to return the contents of a GCONTEXT.

Caching graphics contexts can result in a synchronization problem if more than one client program modifies a graphics context. However, this problem is unusual. Sharing a graphics context among several clients, while possible, is not expected to be useful and is not very easy to do. At any rate, a client program can choose to not cache a GCONTEXT when it is created.

Each client program must determine its own policy for creating and using graphics contexts. Depending on the display hardware and the server implementation, creating a new graphics context can be more or less expensive than modifying an existing one. In general, some amount of graphics context information can be cached in the display hardware, in which case modifying the hardware cache is faster than replacing it. Typical display hardware can cache only a small number of graphics contexts. Graphics output is fastest when only a few graphics contexts are used without heavy modifications.

This section explains the CLX functions used to:

  * Create a graphics context

  * Return the contents of a graphics context

  * Change the contents of a graphics context

  * Copy a graphics context

  * Free a graphics context

Creating Graphics Contexts
==========================

To create a graphics context, use CREATE-GCONTEXT.

 -- Function: create-gcontext &key :arc-mode :background (:cache-p t) :cap-style :clip-mask :clip-ordering :clip-x :clip-y :dash-offset :dashes :drawable :exposures :fill-rule :fill-style :font :foreground :function :join-style :line-style :line-width :plane-mask :stipple :subwindow-mode :tile :ts-x :ts-y

     :cache-p
          Specifies if this graphics context should be cached locally by CLX. If NIL then the state is not cached, otherwise a local cache is kept.

     :drawable
          The DRAWABLE whose root and depth are to be associated with this graphics context. This is a required keyword argument.

     :arc-mode
     :background
     :cap-style
     :clip-mask
     :clip-ordering
     :clip-x
     :clip-y
     :dash-offset
     :dashes
     :exposures
     :fill-rule
     :fill-style
     :font
     :foreground
     :function
     :join-style
     :line-style
     :line-width
     :plane-mask
     :stipple
     :subwindow-mode
     :tile
     :ts-x
     :ts-y
          Initial attribute values for the graphics context.

     Creates, initializes, and returns a graphics context (GCONTEXT). The graphics context can only be used with destination drawables having the same root and depth as the specified :DRAWABLE. If :CACHE-P is non-NIL, the graphics context state is cached locally, and changing a component has no effect unless the new value differs from the cached value.  Changes to a graphics context (setf and WITH-GCONTEXT) are always deferred regardless of the cache mode and sent to the server only when required by a local operation or by an explicit call to FORCE-GCONTEXT-CHANGES.

     All of the graphics context components are set to the values that are specified by the keyword arguments, except that a value of NIL causes the default value to be used. These default values are as follows:

     ARC-MODE   :PIE-SLICE
     BACKGROUND   1
     CAP-STYLE   :BUTT
     CLIP-MASK   :NONE
     CLIP-ORDERING   :UNSORTED
     CLIP-X   0
     CLIP-Y   0
     DASH-OFFSET   0
     DASHES   4 (that is, the list '(4, 4))
     EXPOSURES   :ON
     FILL-RULE   :EVEN-ODD
     FILL-STYLE   :SOLID
     FONT   server dependent
     FOREGROUND   0
     FUNCTION   BOOLE-1
     JOIN-STYLE   :MITER
     LINE-STYLE   :SOLID
     LINE-WIDTH   0
     PLANE-MASK   A bit mask of all ones
     STIPPLE   Pixmap of unspecified size filled with ones
     SUBWINDOW-MODE   :CLIP-BY-CHILDREN
     TILE   Pixmap of an unspecified size filled with the foreground pixel (that is, the client-specified pixel if any, or else 0)
     TS-X   0
     TS-Y   0

     Note that foreground and background do not default to any values that are likely to be useful on a color display. Since specifying a NIL value means use the default, this implies for clip-mask that an empty rectangle sequence cannot be specified as an empty list; :NONE must be used instead. Specifying a STRINGABLE for font causes an implicit OPEN-FONT call to occur.

     gcontext
          Type GCONTEXT.

Graphics Context Attributes
===========================

The following paragraphs describe the CLX functions used to return or change the attributes of a GCONTEXT. Functions that return the contents of a GCONTEXT return NIL if the last value stored is unknown (for example, if the GCONTEXT was not cached or if the GCONTEXT was not created by the inquiring client).

 -- Function: gcontext-arc-mode gcontext

     gcontext
          A GCONTEXT.

     Returns and (with setf) changes the arc-mode attribute of the specified graphics context.

     The arc-mode attribute of a graphics context controls the kind of filling, if any, to be done by the DRAW-ARCS function. A value of :CHORD specifies that arcs are filled inward to the chord between the end points of the arc. :PIE-SLICE specifies that arcs are filled inward to the center point of the arc, creating a pie slice effect.

     arc-mode
          Either :CHORD or :PIE-SLICE.

 -- Function: gcontext-background gcontext

     gcontext
          A GCONTEXT.

     Returns and (with setf) changes the background attribute of the specified graphics context.

     The background attribute specifies the pixel value drawn for pixels that are not set in a bitmap and for pixels that are cleared by a graphics operation, such as the gaps in dashed lines.

     background
          Type CARD32.

 -- Function: gcontext-cache-p gcontext

     gcontext
          A GCONTEXT.

     Returns and (with setf) changes the local cache mode for the gcontext. If true, the state of the gcontext is cached by CLX and changes to its attributes have no effect unless the new value differs from its cached value.

     cache-p
          Type BOOLEAN.

      -- Function: gcontext-cap-style gcontext

          gcontext
               A GCONTEXT.

          Returns and (with setf) changes the cap-style attribute of the specified graphics context.

          The cap-style attribute of a graphics context defines how the end points of a path are drawn. The possible values and their interpretations are as follows:

          :BUTT
          Square at the end point (perpendicular to the slope of the line) with no projection beyond.

          :NOT-LAST

          Equivalent to :BUTT, except that for a line-width of zero or one
          the final end point is not drawn.

          :PROJECTING

          Square at the end, but the path continues beyond the end point for a
          distance equal to half the line-width. This is equivalent to
          :BUTT for line-width zero or one.

          :ROUND

          A circular arc with the radius equal to 1/2 of the line-width,
          centered on the end point. This is equivalent to :BUTT for
          line-width zero or one.

          The following table describes what happens when the end points of a line are identical.  The effect depends on both the cap style and line width.

          :BUTT   thin

          Device dependent, but the desired effect is that a single pixel is
          drawn.

          :BUTT   wide

          Nothing is drawn.

          :NOT-LAST   thin

          Device dependent, but the desired effect is that nothing is drawn.

          :PROJECTING   thin

          Same as :BUTT with thin line-width.

          :PROJECTING   wide

          The closed path is a square, aligned with the coordinate axes,
          centered at the end point, with sides equal to the line-width.

          :ROUND   wide

          The closed path is a circle, centered at the end point, with diameter equal to the line-width.

          :ROUND   thin

          Same as :BUTT with thin line-width.

          cap-style
               One of :BUTT, :NOT-LAST, :PROJECTING, or :ROUND.

      -- Function: gcontext-clip-mask gcontext &optional ordering

          gcontext
               A GCONTEXT.

          ordering
               One of :UNSORTED, :Y-SORTED, :YX-BANDED, :YX-SORTED, or NIL.

          Returns and (with setf) changes the clip-mask attribute of the graphics context.

          When changing the clip-mask attribute, the new clip-mask can be specified as a pixmap or a RECT-SEQ or as the values :NONE or NIL. The ordering argument can be specified only with setf when the new clip-mask is a RECT-SEQ.

          The clip-mask attribute of a graphics context affects all graphics operations and is used to restrict output to the destination drawable. The clip-mask does not clip the source of a graphics operation. A value of :NONE for clip-mask indicates that no clipping is to be done.

          If a pixmap is specified as the clip-mask, it must have depth one and the same root as the specified graphics context. Pixels where the clip-mask has a one bit are drawn. Pixels outside the area covered by the clip-mask or where the clip-mask has a zero bit are not drawn.

          If a sequence of rectangles is specified as the clip-mask, the output is clipped to remain contained within the rectangles. The rectangles should be non-intersecting, or the results of graphics operations will be undefined. The rectangle coordinates are interpreted relative to the clip origin. Note that the sequence of rectangles can be empty, which effectively disables output. This is the opposite of setting the clip-mask to :NONE.

          If known by the client, the ordering of clip-mask rectangles can be specified to provide faster operation by the server. A value of :UNSORTED means the rectangles are in arbitrary order. A value of :Y-SORTED means that the rectangles are non-decreasing in their Y origin. A :YX-SORTED value is like :Y-SORTED with the additional constraint that all rectangles with an equal Y origin are non-decreasing in their X origin. A :YX-BANDED value additionally constrains :YX-SORTED by requiring that, for every possible Y scan line, all rectangles that include that scan line have an identical Y origins and Y extents. If incorrect ordering is specified, the X server may generate an error, but it is not required to do so. If no error is generated, the results of the graphics operations are undefined.

      -- Function: gcontext-clip-x gcontext

          gcontext
               A GCONTEXT.

          Returns and (with setf) changes the clip-x attribute of the specified graphics context.

          The clip-x and clip-y attributes specify the origin for the clip-mask, whether it is a pixmap or a sequence of rectangles. These coordinates are interpreted relative to the origin of whatever destination drawable is specified in a graphics operation.

          clip-x
               Type INT16.

      -- Function: gcontext-clip-y gcontext

          gcontext
               A GCONTEXT.

          Returns and (with setf) changes the clip-y attribute of the specified graphics context.

          The clip-x and clip-y attributes specify the origin for the clip-mask, whether it is a pixmap or a sequence of rectangles. These coordinates are interpreted relative to the origin of whatever destination drawable is specified in a graphics operation.

          clip-y
               Type INT16.

      -- Function: gcontext-dash-offset gcontext

          gcontext
               A GCONTEXT.

          Returns and (with setf) changes the dash-offset attribute of the specified graphics context.

          The dash-offset attribute of a graphics context defines the phase of the pattern contained in the dashes attribute. This phase specifies how many elements (pixels) into the path the pattern should actually begin in any single graphics operation. Dashing is continuous through path elements combined with a join-style, but is reset to the dash-offset each time a cap-style is applied at a line end point.

          dash-offset
               Type CARD16.

      -- Function: gcontext-dashes gcontext

          gcontext
               A GCONTEXT.

          Returns and (with setf) changes the dashes attribute of the specified graphics context.  The sequence must be non-empty and the elements must be non-zero CARD8 values.

          The dashes attribute in a graphics context specifies the pattern that is used for graphics operations which use the dashed line styles. It is a non-NIL sequence with each element representing the length of a single dash or space. The initial and alternating elements of the dashes are the even dashes, while the others are the odd dashes. An odd length sequence is equivalent to the same sequence concatenated with itself to produce an even length sequence. All of the elements of a dashes sequence must be non-zero.

          Specifying a single integer value, N, for the dashes attribute is an abbreviated way of specifying a two element sequence with both elements equal to the specified value [N, N].

          The unit of measure for dashes is the same as in the ordinary coordinate system. Ideally, a dash length is measured along the slope of the line, but server implementations are only required to match this ideal for horizontal and vertical lines.

          dashes
               Type SEQUENCE or CARD8.

      -- Function: gcontext-display gcontext

          gcontext
               A GCONTEXT.

          Returns the DISPLAY object associated with the specified gcontext.

          display
               Type DISPLAY.

      -- Function: gcontext-equal gcontext-1 gcontext-2

          gcontext-1
          gcontext-2
               A GCONTEXT.

          Returns true if the two arguments refer to the same server resource, and NIL if they do not.

          equal-p
               Type BOOLEAN.

      -- Function: gcontext-exposures gcontext

          gcontext
               A GCONTEXT.

          Returns and (with setf) changes the exposures attribute of the specified graphics context.

          The exposures attribute in a graphics context controls the generation of :GRAPHICS-EXPOSURE events for calls to the COPY-AREA and COPY-PLANE functions. If :ON, :GRAPHICS-EXPOSURE events will be reported when calling the COPY-AREA and COPY-PLANE functions with this graphics context. Otherwise, if :OFF, the events will not be reported.

          exposures
               Either :OFF or :ON.

      -- Function: gcontext-fill-rule gcontext

          gcontext
               A GCONTEXT.

          Returns and (with setf) changes the fill-rule attribute of the specified graphics context.

          The fill-rule attribute in a graphics context specifies the rule used to determine the interior of a filled area. It can be specified as either :EVEN-ODD or :WINDING.

          The :EVEN-ODD rule defines a point to be inside if any infinite ray starting at the point crosses the border an odd number of times. Tangencies do not count as a crossing.

          The :WINDING rule defines a point to be inside if any infinite ray starting at the point crosses an unequal number of clockwise and counterclockwise directed border segments. A clockwise directed border segment crosses the ray from left to right as observed from the point. A counterclockwise segment crosses the ray from right to left as observed from the point. The case where a directed line segment is coincident with the ray is uninteresting because you can simply choose a different ray that is not coincident with a segment.

          For both :EVEN-ODD and :WINDING, a point is infinitely small, and the border is an infinitely thin line. A pixel is inside if the center point of the pixel is inside, and the center point is not on the border. If the center point is on the border, the pixel is inside if, and only if, the polygon interior is immediately to its right (x increasing direction). Pixels with centers along a horizontal edge are a special case and are inside if, and only if, the polygon interior is immediately below (y increasing direction).

          fill-rule
               Either :EVEN-ODD or :WINDING.

      -- Function: gcontext-fill-style gcontext

          gcontext
               A GCONTEXT.

          Returns and (with setf) changes the fill-style attribute of the specified graphics context.

          The fill-style attribute of a graphics context defines the contents of the source for line, text, and fill graphics operations. It determines whether the source image is drawn with a solid color, a tile, or a stippled tile. The possible values and their meanings are as follows:

          :opaque-stippled
               Filled with a tile with the same width and height as stipple, but with the background value used everywhere stipple has a zero and the foreground pixel value used everywhere stipple has a one.

          :solid
               Filled with the foreground pixel value.

          :stippled
               Filled with the foreground pixel value masked by stipple.

          :tiled
               Filled with tile.

          When drawing lines with line-style :DOUBLE-DASH, the filling of the odd dashes are controlled by the fill-style in the following manner:

          :opaque-stippled
               Same as for even dashes.

          :solid
               Filled with the background pixel value.

          :stippled
               Filled with the background pixel value masked by stipple.

          :tiled
               Filled the same as the even dashes.

          fill-style
               One of :OPAQUE-STIPPLED, :SOLID, :STIPPLED, or :TILED.

      -- Function: gcontext-font gcontext &optional metrics-p

          gcontext
               A GCONTEXT.

          metrics-p
               Specifies whether a pseudo-font is returned when the real font stored in the graphics context is not known. The default is NIL, which means do not return a pseudo-font.

          Returns and (with setf) changes the font attribute of the specified graphics context. If the stored font is known, it is returned. If it is not known and the metrics-p argument is NIL, then NIL is returned. If the font is not known and metrics-p is true, then a pseudo-font is constructed and returned. For a constructed pseudo-font, full metric and property information can be obtained, but it does not have a name or a resource ID, and attempts to use it where a resource ID is required results in an invalid-font error.

          The font attribute in a graphics context defines the default text font used in text drawing operations. When setting the value of the font attribute, either a FONT object or a font name can be used. If a font name is passed, OPEN-FONT is call automatically to get the FONT object.

          font
               Type FONT or NULL.

 -- Function: gcontext-foreground gcontext

     gcontext
          A GCONTEXT.

     Returns and (with setf) changes the foreground attribute of the specified graphics context.

     The foreground attribute of a graphics context specifies the pixel value drawn for set bits in a bitmap and for bits set by a graphics operation.

     foreground
          Type CARD32.

 -- Function: gcontext-function gcontext

     gcontext
          A GCONTEXT.

     Returns the function of the specified graphics context.

     In all graphic operations, given a source pixel and a corresponding destination pixel, the resulting pixel drawn is computed bitwise on the bits of the source and destination pixels. That is, a logical operation is used to combine each bit plane of corresponding source and destination pixels. The graphics context function attribute specifies the logical operation used via one of the 16 operation codes defined by Common Lisp for the BOOLE function.

     The following table shows each of the logical operation codes that can be given by the function attribute. For each operation code, its result is shown as a logical function of a source pixel S and a destination pixel D.

     BOOLE-1
     S
     BOOLE-2
     D
     BOOLE-ANDC1
     (logandc1 S D)
     BOOLE-ANDC2
     (logandc2 S D)
     BOOLE-AND
     (logand S D)
     BOOLE-C1
     (lognot S)
     BOOLE-C2
     (lognot D)
     BOOLE-CLR
     0
     BOOLE-EQV
     (logeqv S D)
     BOOLE-IOR
     (logior S D)
     BOOLE-NAND
     (lognand S D)
     BOOLE-NOR
     (lognor S D)
     BOOLE-ORC1
     (logorc1 S D)
     BOOLE-ORC2
     (logorc2 S D)
     BOOLE-SET
     1
     BOOLE-XOR
     (logxor S D)

     function
          Type BOOLE-CONSTANT.

 -- Function: gcontext-id gcontext

     gcontext
          A GCONTEXT.

     Returns the unique ID that has been assigned to the specified graphics context.

     id
          Type RESOURCE-ID.

 -- Function: gcontext-join-style gcontext

     gcontext
          A GCONTEXT.

     Returns and (with setf) changes the join-style attribute of the specified graphics context.

     The join-style attribute of a graphics context defines how the segment intersections are drawn for wide polylines. The possible values and their interpretations are as follows:

     :bevel
          Uses :BUTT end point styles with the triangular notch filled.

     :miter
          The outer edges of two lines extend to meet at an angle.

     :round
          A circular arc with diameter equal to the line-width, centered on the join point.

     When the end points of a polyline segment are identical, the effect is as if the segment was removed from the polyline. When a polyline is a single point, the effect is the same as when the cap-style is applied at both end points.

     join-style
          One of :BEVEL, :MITER, or :ROUND.

 -- Function: gcontext-line-style gcontext

     gcontext
          A GCONTEXT.

     Returns and (with setf) changes the line-style attribute of the specified graphics context.

     The line-style attribute of a graphics context specifies how (which sections of) lines are drawn for a path in graphics operations. The possible values and their meanings are as follows:

     :solid
          The full path is drawn.

     :double-dash
          The full path is drawn, but the even dashes are filled differently than the odd dashes. The :BUTT style is used where even and odd dashes meet (see paragraph 5.4.7, Fill-Rule and Fill-Style).

     :on-off-dash
          Only the even dashes are drawn, with cap-style applied to all internal ends of the individual dashes, except :NOT-LAST is treated as :BUTT.

     line-style
          One of :DASH, :DOUBLE-DASH, or :SOLID.

 -- Function: gcontext-line-width gcontext

     gcontext
          A GCONTEXT.

     Returns the line-width of the specified graphics context.

     The line-width is measured in pixels and can be greater than or equal to one (wide line) or can be the special value zero (thin line).

     Wide lines are drawn centered on the path described by the graphics operation. Unless otherwise specified by the join-style or cap-style, the bounding box of a wide line with end points [x1, y1], [x2, y2], and width w is a rectangle with vertices at the following real coordinates:

     [x1 - (w*sin/2), y1 + (w*cos/2)], [x1+ (w*sin/2), y1 - (w*cos/2)],

     [x2 - (w*sin/2), y2 + (w*cos/2)], [x2 + (w*sin/2), y2 - (w*cos/2)]

     where sin is the sine of the angle of the line and cos is the cosine of the angle of the line. A pixel is part of the line and, hence, is drawn if the center of the pixel is fully inside the bounding box (which is viewed as having infinitely thin edges). If the center of the pixel is exactly on the bounding box, it is part of the line if, and only if, the interior is immediately to its right (x increasing direction). Pixels with centers on a horizontal edge are a special case and are part of the line if, and only if, the interior is immediately below (y increasing direction).

     Thin lines (zero line-width) are always one pixel wide lines drawn using an unspecified, device dependent algorithm. There are only two constraints on this algorithm.

      1. If a line is drawn unclipped from [x1,y1] to [x2,y2] and if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], a point [x,y] is touched by drawing the first line if, and only if, the point [x+dx,y+dy] is touched by drawing the second line.

      2. The effective set of points comprising a line cannot be affected by clipping. That is, a point is touched in a clipped line if, and only if, the point lies inside the clipping region and the point would be touched by the line when drawn unclipped.

     A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style and join-style. Implementors are encouraged to make this property true for thin lines, but it is not required. A line-width of zero may differ from a line-width of one in which pixels are drawn. This permits the use of many manufacturer's line drawing hardware, which may run much faster than the more precisely specified wide lines.

     In general, drawing a thin line is faster than drawing a wide line of width one. However, because of their different drawing algorithms, thin lines may not mix well, aesthetically speaking, with wide lines. If it is desirable to obtain precise and uniform results across all displays, a client should always use a line-width of one, rather than a line-width of zero.

     line-width
          Type CARD16.

 -- Function: gcontext-p gcontext

     gcontext
          Type BOOLEAN.

     Returns non-NIL if the argument is a graphics context and

 -- Function: gcontext-plane-mask gcontext

     gcontext
          A GCONTEXT.

     Returns the plane-mask of the specified graphics context.

     The plane-mask attribute of a graphics context specifies which bit planes of the destination drawable are modified during a graphic operation. The plane-mask is a pixel value in which a 1 bit means that the corresponding bit plane will be modified and a 0 bit means that the corresponding bit plane will not be affected during a graphic operations. Thus, the actual result of a graphic operation depends on both the function and plane-mask attributes of the graphics context and is given by the following expression:

          (logior (logand
          	 (boole function source destination)
          	 plane-mask)

          	(logandc2
          	 destination
          	 plane-mask))

     plane-mask
          Type CARD32.

 -- Function: gcontext-plist gcontext

     gcontext
          A GCONTEXT.

     Returns and (with setf) sets the property list for the specified gcontext. This function provides a hook where extensions can add data.

     gcontext-p
          Type LIST.

 -- Function: gcontext-stipple gcontext

     gcontext
          A GCONTEXT.

     Returns the stipple of the specified graphics context.

     The stipple attribute of a graphics context is a bitmap used to prevent certain pixels in the destination of graphics operations from being affected by tiling.

     The stipple and tile have the same origin. This origin point is interpreted relative to the origin of whatever destination drawable is specified in a graphics request. The stipple pixmap must have depth one and must have the same root as the graphics context. The tile pixmap must have the same root and depth as the graphics context. For stipple operations where the fill-style is :STIPPLED (but not :OPAQUE-STIPPLED), the stipple pattern is tiled in a single plane and acts as an additional clip mask to be ANDed with the clip-mask.  Any size pixmap can be used for stipple or tile, although some sizes may be faster to use than others.

     Specifying a pixmap for stipple or tile in a graphics context might or might not result in a copy being made. If the pixmap is later used as the destination for a graphics operation, the change might or might not be reflected in the graphics context. If the pixmap is used both as the destination for a graphics operation and as a stipple or tile, the results are not defined.

     Some displays have hardware support for tiling or stippling with patterns of specific sizes. Tiling and stippling operations that restrict themselves to those sizes may run much faster than such operations with arbitrary size patterns. CLX provides functions to determine the best size for stipple or tile (see QUERY-BEST-STIPPLE and QUERY-BEST-TILE).

     stipple
          Type PIXMAP.

 -- Function: gcontext-subwindow-mode gcontext

     gcontext
          A GCONTEXT.

     Returns and (with setf) changes the subwindow-mode attribute of the specified graphics context.

     The subwindow-mode attribute of a graphics context specifies whether subwindows obscure the contents of their parent window during a graphics operation. For a value of :CLIP-BY-CHILDREN, both source and destination windows are clipped by all viewable :INPUT-OUTPUT class children. This clipping is in addition to the clipping provided by the clip-mode attribute. For a value of :INCLUDE-INFERIORS, neither the source nor destination window is clipped by its inferiors. This results in the inclusion of subwindow contents in the source and the drawing through of subwindow boundaries of the destination. The use of :INCLUDE-INFERIORS on a window of one depth with mapped inferiors of differing depth is not illegal, but the semantics are not defined by the core protocol.

     subwindow-mode
          One of :CLIP-BY-CHILDREN or :INCLUDE-INFERIORS.

 -- Function: gcontext-tile gcontext

     gcontext
          A GCONTEXT.

     Returns the tile of the specified graphics context.

     The tile attribute is a pixmap used to fill in areas for graphics operations. It is so named because copies of it are laid out side by side to fill the area.

     The stipple and tile have the same origin. This origin point is interpreted relative to the origin of whatever destination drawable is specified in a graphics request. The stipple pixmap must have depth one and must have the same root as the graphics context. The tile pixmap must have the same root and depth as the graphics context. For stipple operations where the fill-style is :STIPPLED (but not :OPAQUE-STIPPLED), the stipple pattern is tiled in a single plane and acts as an additional clip mask to be ANDed with the clip-mask.  Any size pixmap can be used for stipple or tile, although some sizes may be faster to use than others.

     Specifying a pixmap for stipple or tile in a graphics context might or might not result in a copy being made. If the pixmap is later used as the destination for a graphics operation, the change might or might not be reflected in the graphics context. If the pixmap is used both as the destination for a graphics operation and as a stipple or tile, the results are not defined.

     Some displays have hardware support for tiling or stippling with patterns of specific sizes. Tiling and stippling operations that restrict themselves to those sizes may run much faster than such operations with arbitrary size patterns. CLX provides functions to determine the best size for stipple or tile (see QUERY-BEST-STIPPLE and QUERY-BEST-TILE).

     tile
          Type PIXMAP.

 -- Function: gcontext-ts-x gcontext

     gcontext
          A GCONTEXT.

     Returns the ts-x attribute of the specified graphics context.

     The ts-x and ts-y attributes of a graphics context are the coordinates of the origin for tile pixmaps and the stipple.

     ts-x
          Type INT16.

 -- Function: gcontext-ts-y gcontext

     gcontext
          A GCONTEXT.

     Returns the ts-y attribute of the specified graphics context.

     The ts-x and ts-y attributes of a graphics context are the coordinates of the origin for tile pixmaps and the stipple.

     ts-y
          Type INT16.

 -- Function: query-best-stipple width height drawable

     width
     height
          Specifies the width and height of the desired stipple pattern.

     drawable
          A DRAWABLE.

     Returns the best-width and best-height for stipple pixmaps on the drawable.

     The drawable indicates the screen and possibly the window class and depth. An :INPUT-ONLY window cannot be specified as the drawable. The size is returned as width and height values.

     best-width
     best-height
          Type CARD16.

 -- Function: query-best-tile width height drawable

     width
     height
          Specifies the width and height of the desired tile pattern.

     drawable
          A DRAWABLE.

     Returns the best-width and best-height for tile pixmaps on the drawable.

     The drawable indicates the screen and possibly the window class and depth. An :INPUT-ONLY window cannot be specified as the drawable. The size is returned as width and height values.

     best-width
     best-height
          Type CARD16.

Copying Graphics Contexts
=========================

CLX provides functions to copy some or all attribute values from one graphics context to another. These functions are generally more efficient than using setf to copy GCONTEXT attributes individually.

 -- Function: copy-gcontext source destination

     source
          The source GCONTEXT.

     destination
          The destination GCONTEXT.

     Copies all the values of the attributes of the source graphics context into the destination graphics context. The source and destination graphics contexts must have the same root and depth.

 -- Function: copy-gcontext-components source destination &rest keys

     source
          The source GCONTEXT.

     destination
          The destination GCONTEXT.

     keys
          The remaining arguments are keywords, of type GCONTEXT-KEY, which specify which attributes of the graphics context are to be copied.

     Copies the values of the specified attributes of the source graphics context to the destination graphics context. The source and destination graphics contexts must have the same root and depth.

Destroying Graphics Contexts
============================

To destroy a graphics context, use FREE-GCONTEXT.

 -- Function: free-gcontext gcontext

     gcontext
          A GCONTEXT.

     Deletes the association between the assigned resource ID and the specified graphics context, and then destroys the graphics context.

Graphics Context Cache
======================

CLX provides a set of functions to control the automatic graphics context caching mechanism.

 -- Function: force-gcontext-changes gcontext

     gcontext
          A GCONTEXT.

     Forces any delayed changes to the specified graphics context to be sent out to the server.  Note that FORCE-GCONTEXT-CHANGES is called by all of the graphics functions.

 -- Macro: with-gcontext gcontext &key :arc-mode :background :cap-style :clip-mask :clip-ordering :clip-x :clip-y :dashes :dash-offset :exposures :fill-rule :fill-style :font :foreground :function :join-style :line-style :line-width :plane-mask :stipple :subwindow-mode :tile :ts-x :ts-y &allow-other-keys &body body

     Changes the indicated graphics context components to the specified values only within the dynamic extent of the body. WITH-GCONTEXT works on a per-process basis in a multiprocessing environment. The body is not surrounded by a WITH-DISPLAY form. If there is no local cache for the specified graphics context, or if some of the component states are unknown, WITH-GCONTEXT does the save and restore by creating a temporary graphics context and copying components to and from it using COPY-GCONTEXT-COMPONENTS.

     gcontext
          A GCONTEXT.

     :arc-mode
     :background
     :cap-style
     :clip-mask
     :clip-ordering
     :clip-x
     :clip-y
     :dashes
     :dash-offset
     :exposures
     :fill-rule
     :fill-style
     :font
     :foreground
     :function
     :join-style
     :line-style
     :line-width
     :plane-mask
     :stipple
     :subwindow-mode
     :tile
     :ts-x
     :ts-y
          These keyword arguments and associated values specify which graphics context components are to be changed. Any components not specified are left unmodified. See Creating Graphics Contexts, for more information.

     body
          The body of code which will have access to the altered graphics context.

Graphic Operations
******************

Once connected to an X server, a client can use CLX functions to perform graphic operations on drawables.

This section describes CLX functions to:

  * Operate on areas and planes

  * Draw points

  * Draw lines

  * Draw rectangles

  * Draw arcs

  * Draw text

Area and Plane Operations
=========================

CLEAR-AREA clears an area or an entire window to the background. Since pixmaps do not have backgrounds, they cannot be filled by using the functions described in the following paragraphs. Instead, you should use DRAW-RECTANGLE, which sets the pixmap to a known value. See Drawing Rectangles, for information on DRAW-RECTANGLE.

 -- Function: clear-area window &key (:x 0) (:y 0) :width :height :exposures-p

     window
          A WINDOW.

     :x
     :y
          Upper-left corner of the area to be cleared. These coordinates are relative to the window origin. Type is INT16.

     :width
          The width of the area to clear or NIL to clear to the remaining width of the window. Type is CARD16 or NULL.

     :height
          The height of the area to clear or NIL to clear to the remaining height of the window. Type is CARD16 or NULL.

     :exposures-p
          Specifies if :EXPOSURE events should be generated for the affected areas. Type BOOLEAN.

     Draws a rectangular area in the specified window with the background pixel or pixmap of the window. The :X and :Y coordinates are relative to the window origin, and specify the upper-left corner of the rectangular area that is to be cleared. A NIL or zero value for :HEIGHT or :WIDTH clears the remaining area (height - y or width - x). If the window has a defined background tile, the rectangle is tiled by using a plane-mask of all ones and a function of :COPY. If the window has background :NONE, the contents of the window are not changed. In either case, if :EXPOSURES-P is non-NIL, then one or more :EXPOSURE events are generated for regions of the rectangle that are either visible or are being retained in a backing store.

     To clear the entire area in a specified window, use (CLEAR-AREA window).

 -- Function: copy-area source gcontext source-x source-y width height destination destination-x destination-y

     source
          Source DRAWABLE.

     gcontext
          The graphics context to use during the copy operation.

     source-x
     source-y
          The x and y coordinates of the upper-left corner of the area in the source DRAWABLE. These coordinates are relative to the source DRAWABLE origin.  Type is INT16.

     width
     height
          The width and height of the area being copied. These apply to both the source and destination areas. Type is CARD16.

     destination
          The destination DRAWABLE.

     destination-x
     destination-y
          The x and y coordinates of the upper left corner of the area in the destination DRAWABLE. These coordinates are relative to the destination DRAWABLE origin. Type is INT16.

     Copies the specified rectangular area from the source DRAWABLE to the specified rectangular area of the destination DRAWABLE, combining them as specified in the supplied graphics context (gcontext). The x and y coordinates are relative to their respective drawable origin, with each pair specifying the upper left corner of the area.

     If either regions of the source area are obscured and have not been retained in backing store, or regions outside the boundaries of the source DRAWABLE are specified, those regions are not copied. Instead, the following occurs on all corresponding destination regions that are either visible or are retained in backing store:

       * If the destination rectangle is a window with a background other than :NONE, these corresponding regions of the destination are tiled, using plane-mask of all ones and function of BOOLE-1 (copy source), with that background.

       * If the exposures attribute of the graphics context is :ON, then :GRAPHICS-EXPOSURE events for all corresponding destination regions are generated (regardless of tiling or whether the destination is a window or a pixmap).

       * If exposures is :ON but no regions are exposed, a :NO-EXPOSURE event is generated.  Note that by default, exposures is :ON for new graphics contexts. See Graphics Contexts, for further information.

 -- Function: copy-plane source gcontext plane source-x source-y width height destination destination-x destination-y

     source
          The source DRAWABLE.

     gcontext
          The graphics context to use during the copy operation.

     plane
          Specifies the bit-plane of the source DRAWABLE. Exactly one bit must be set. Type is PIXEL.

     source-x
     source-y
          The x and y coordinates of the upper-left corner of the area in the source DRAWABLE. These coordinates are relative to the source DRAWABLE origin.  Type is INT16.

     width
     height
          The width and height of the area being copied. These apply to both the source and destination areas. Type is CARD16.

     destination
          The destination DRAWABLE.

     destination-x
     destination-y

          The x and y coordinates of the upper-left corner of the destination area in the destination DRAWABLE. These coordinates are relative to the destination DRAWABLE origin. Type is INT16.

     Uses a single bit plane of the specified rectangular area of the source DRAWABLE along with the specified graphics context (gcontext) to modify the specified rectangle area of the destination DRAWABLe. The drawables specified by the source and destination arguments must have the same root but need not have the same depth.

     Effectively, this operation forms a pixmap of the same depth as destination and with a size specified by the source area. It then uses the foreground and background from the graphics context (foreground where the bit-plane in source contains a one bit, background where the bit-plane in source contains a zero bit), and the equivalent of a COPY-AREA operation is performed with all the same exposure semantics. This can also be thought of as using the specified region of the source bit-plane as a stipple with a fillstyle of :OPAQUE-STIPPLED for filling a rectangular area of the destination.

Drawing Points
==============

The DRAW-POINT and DRAW-POINTS functions make use of the following graphics context components: function, plane-mask, foreground, subwindow-mode, clip-x, clip-y, clip-ordering, clip-region and clip-mask.

The DRAW-POINT function uses the foreground pixel and function components of the graphics context to draw a single point into the specified drawable, while DRAW-POINTS draws multiple points into the specified drawable. These functions are not affected by the tile or stipple in the graphics context.

 -- Function: draw-point drawable gcontext x y

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context for drawing the point.

     x
     y
          The x and y coordinates of the point drawn. Type is INT16.

     Combines the foreground pixel in the gcontext with the pixel in the drawable specified by the x and y coordinates.

 -- Function: draw-points drawable gcontext points &optional relative-p

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context for drawing the points.

     points
          A list of points to be drawn in the order listed. The first point is always relative to the drawable's origin; if relative-p, the rest of the points are drawn relative to the previous point, else they are drawn relative to the drawable's origin. Type is POINT-SEQ.

     relative-p
          Specifies the coordinate mode used for drawing the pixels either relative to the origin or to the previous point. Type BOOLEAN.

     Combines the foreground pixels in the graphics context with the pixels at each point in the drawable. The points are drawn in the order listed.

     DRAW-POINTS requires a mode argument, relative-p that indicates whether the points are relative to the destination origin or to the previous point. In either case, the first point is always relative to the destination origin. The rest of the points are relative either to the drawable's origin or to the previous point, depending on the value of relative-p.

Drawing Lines
=============

The DRAW-LINE, DRAW-LINES, and DRAW-SEGMENTS functions use the following graphics context components: background, cap-style, clip-x-origin, clip-y-origin, clip-mask, dash-list, dash-offset, fill-style, foreground, function, plane-mask, line-width, line-style, stipple, subwindow-mode, tile, ts-x-origin, and ts-y-origin.

The DRAW-LINES function also uses the join-style graphics context component.

 -- Function: draw-line drawable gcontext x1 y1 x2 y2 &optional relative-p

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context for drawing the line.

     x1
     y1
     x2
     y2
          The end points of the line.

     relative-p
          Specifies the coordinate mode used for drawing the line either relative to the origin or the previous point. In either case, the first point is always drawn relative to the drawable's origin.

     Draws a line from the point x1,y1 to the point x2,y2. When relative-p is true, the first point is relative to the destination origin but the second point is relative to the first point.  When relative-p is NIL, both points are relative to the destination origin.

 -- Function: draw-lines drawable gcontext points &key :relative-p :fill-p (:shape :complex)

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context for drawing the lines.

     points
          A list of points that define the lines. Type is POINT-SEQ.

     :relative-p
          The coordinate mode of the points.

     :fill-p
          When true, a filled polygon is drawn instead of a polyline.

     :shape
          A hint that allows the server to use the most efficient area fill algorithm. Either :CONVEX, :NON-CONVEX, or :COMPLEX.

     Draws a line between each pair of points in the points list. The lines are drawn in the order listed and join correctly at all intermediate points. The join-style graphics context component defines the type of joint to use. When the first and last points coincide, the first and last lines also join correctly to produce a hollow polygon.

     When :RELATIVE-P is true, the first point is always relative to the destination origin, but the rest are relative to the previous point. When :RELATIVE-P is NIL, the rest of the points are drawn relative to the destination origin.

     When :FILL-P is true, the polygon defined by the points list is filled. The :SHAPE keyword provides the server with a hint about how to fill the polygon. :SHAPE can be either :COMPLEX (by default), :CONVEX, or :NON-CONVEX.

     The :CONVEX operand is the simplest type of area and the fastest to fill. A fill area is convex if every straight line connecting any two interior points is entirely inside the area.  For example, triangles and rectangles are convex polygons.

     The :NON-CONVEX operand is for filling an area that is not convex and is also not self-intersecting. Filling this type of area is harder than filling a convex area, but easier than filling one that is self-intersecting. For example, the shape of the letter "T" is non-convex and non-self-intersecting.

     The :COMPLEX operand is the most general (and therefore the hardest) type of fill area. A complex fill area can be non-convex and self-intersecting. For example, draw the outline of a bow tie, without lifting your pencil or tracing over an edge twice. This shape is non-convex and intersects itself at the knot in the middle.

     NOTE: Unless you are sure that a shape is :CONVEX or :NON-CONVEX, it should always be drawn as a :COMPLEX shape. If :CONVEX or :NON-CONVEX is specified incorrectly, the graphics result is undefined.

 -- Function: draw-segments drawable gcontext segments

     drawable
          The destination DRAWABLE to receive the line segments.

     gcontext
          Specifies the graphics context for drawing the lines.

     segments
          The points list for the segments to draw. Type is SEQ.

     Draws multiple lines, not necessarily connected. segments is a sequence of the form {x1 y1 x2 y2}*, in which each subsequence specifies the end points of a line segment. Line segments are drawn in the order given by segments. Unlike DRAW-LINES, no joining is performed at coincident end points.

Drawing Rectangles
==================

The DRAW-RECTANGLE and DRAW-RECTANGLES functions draw hollow or filled outlines of the specified rectangle or rectangles as if a five-point polyline were specified for each rectangle, as follows:

     [x,y,] [x+width,y] [x+width,y+height] [x,y+height] [x,y]

DRAW-RECTANGLE and DRAW-RECTANGLES use the following graphics context components: background, function, plane-mask, foreground, subwindow-mode, cap-style, clip-x, clip-y, clip-ordering, clip-region and clip-mask, dash-list, dash-offset, fill-style, join-style, line-width, line-style, stipple, tile, ts-x-origin, and ts-y-origin.

 -- Function: draw-rectangle drawable gcontext x y width height &optional fill-p

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context for drawing the rectangle.

     x
     y
          The x and y coordinates that define the upper left corner of the rectangle. The coordinates are relative to the destination origin. Type is INT16.

     width
     height
          Specifies the width and height that define the outline of the rectangle. Type is CARD16.

     fill-p
          Specifies whether the rectangle is filled or not. Type BOOLEAN.

     Draws a rectangle defined by the x, y, width, and

     height arguments.

 -- Function: draw-rectangles drawable gcontext rectangles &optional fill-p

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context.

     rectangles
          A list specifying the upper left corner x and y, width and height of the rectangles. Type is RECT-SEQ.

     fill-p
          Specified if the rectangles are filled or not. Type is BOOLEAN.

     Draws the rectangles in the order listed in rectangles. For the specified rectangle or rectangles, no pixel is drawn more than once. The x and y coordinates of each rectangle are relative to the destination origin and define the upper left corner of the rectangle. If rectangles intersect, the intersecting pixels are drawn multiple times.

Drawing Arcs
============

DRAW-ARC draws a single circular or an elliptical arc, while DRAW-ARCS draws multiple circular or elliptical arcs. DRAW-ARC and DRAW-ARCS use the following graphics context components: arc-mode, background, cap-style, clip-x, clip-y, clip-mask, dash-list, dash-offset, fill-style, foreground, join-style, function, plane-mask, line-width, line-style, stipple, subwindow-mode, tile, ts-x-origin, and ts-y-origin.

 -- Function: draw-arc drawable gcontext x y width height angle1 angle2 &optional fill-p

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context for drawing the arc.

     x
     y
          The x and y coordinates of the arc rectangle relative to the origin of the drawable. Type is INT16.

     width
     height
          Specifies the width and height of the rectangle. These are the major and minor axes of the arc. Type is CARD16.

     angle1
          Specifies the start of the arc in radians. Type is ANGLE.

     angle2
          Specifies the direction and end point of the arc. Type is ANGLE.

     fill-p
          Specifies whether the arc is filled or not. Type BOOLEAN.

     Draws either a circular or an elliptical arc. Also, outlined or filled arcs can be drawn.  Each arc is specified by a rectangle (x, y, width, and height) and two angles (angle1 and angle2). The angles are signed integers in radians, with positive indicating counterclockwise motion and negative indicating clockwise motion. The start of the arc is specified by angle1, and the path and extent of the arc is specified by angle2 relative to the start of the arc. If the magnitude of angle2 is greater than 360 degrees, it is truncated to 360 degrees. The x and y coordinates of the rectangle are relative to the drawable's origin.

     For example, an arc specified as [x,y,width,height,angle1,angle2] has the origin of the major and minor axes at:

          [x+(width/2),y+(height/2)]

     The infinitely thin path describing the entire circle/ellipse intersects the horizontal axis at:

          [x,y+(height/2)] and [x+width,y+(height/2)]

     The intersection of the vertical axis is at:

          [x+(width/2),y] and [x+(width/2),y+height]

     These coordinates can be fractional; that is, they are not truncated to discrete coordinates. Note that the angle values are slightly different in CLX than in the X protocol specification.

     If fill-p is NIL, then only the outline of the arc is drawn. Otherwise, if fill-p is true, DRAW-ARC fills the area bounded by the arc outline and one or two line segments, depending on the arc-mode. If the arc-mode is :CHORD, the filled area is bounded by the arc outline and the line segment joining the arc end points. If the arc-mode is :PIE-SLICE, the filled area is bounded by the arc outline and the two line segments joining each arc end point with the center point.

 -- Function: draw-arcs drawable gcontext arcs &optional fill-p

     drawable
          Specifies the DRAWABLE where you want the arcs drawn.

     gcontext
          Specifies the graphics context for drawing the arc.

     arcs
          A sequence containing the width, height, angle1, and angle2 arguments defining the arcs. See DRAW-ARC for more detail. Type is ARC-SEQ.

     fill-p
          Specifies whether the arcs are filled or not. Type is BOOLEAN.

     Draws circular or elliptical, outlined or filled arcs. Each arc is specified by a rectangle and two angles. For a more detailed description, see DRAW-ARC.

     The arcs are filled in the order listed. For any given arc, no pixel is drawn more than once. If regions intersect, the intersecting pixels are drawn multiple times.

Drawing Text
============

CLX provides functions for drawing text using text fonts provided by the X server.  An X font is array of character bit maps indexed by integer codes. See Font and Characters, for a complete discussion of the CLX functions used to manage fonts and characters.

Since Common Lisp programs typically represent text as sequences of characters (that is, strings), CLX text functions must be prepared to convert a Common Lisp character into the integer code used to index the appropriate character bitmap in a given font. The :TRANSLATE argument to a text function is a function which performs this conversion. The default :TRANSLATE function handles all characters that satisfy GRAPHIC-CHAR-P by converting each character into its ASCII code. Note that the assumption made by the default :TRANSLATE function--that is, that an X font indexes bitmaps by ASCII codes--is often valid, but other encodings are possible. In general, a :TRANSLATE function can perform complex transformations. It can be used to convert non-character input, to handle non-ASCII character encodings, and to change the fonts used to access character bitmaps.  The complete behavior of a :TRANSLATE function is given below by describing a prototypical TRANSLATE-FUNCTION.

CLX offers two different ways to draw text--filled text and block text. The DRAW-GLYPH and DRAW-GLYPHS functions create filled text, in which each character image is treated as an area to be filled according to the fill-style of the given graphics context, without otherwise disturbing the surrounding background. In addition, filled text sends a complex type of server request which allows a series of font indices, font changes, and horizontal position changes to be compiled into a single request. Filled text functions use the following graphics context attributes: background, clip-mask, clip-x-origin, clip-y-origin, fill-style, font, foreground, function, plane-mask, stipple, subwindow-mode, tile, ts-x-origin, ts-y-origin.

Block text is a rendering style commonly used by display terminals, in which each character image appears in the foreground pixel inside a rectangular character cell drawn in the graphics context background pixel. The DRAW-IMAGE-GLYPH and DRAW-IMAGE-GLYPHS functions create block text. Block text functions use the following graphics context attributes: background, clip-mask, clip-x-origin, clip-y-origin, font, foreground, plane-mask, stipple, subwindow-mode, tile, ts-x-origin, ts-y-origin.

 -- Function: draw-glyph drawable gcontext x y element &key :translate :width (:size :default)

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context for drawing text.

     x
     y
          The left baseline position for the character drawn.

     element
          A character or other object to be translated into a font index.

     :translate
          A function to translate text to font indexes. Default is #'TRANSLATE-DEFAULT.

     :width
          The total pixel width of the character actually drawn, if known.

     :size
          Specifies the element size of the destination buffer given to :TRANSLATE (8, 16, or :DEFAULT).

     Draws a single character of filled text represented by the given element. The given x and y specify the left baseline position for the character. The first return value is true if the character is successfully translated and drawn, or NIL if the :TRANSLATE function did not translate it. The second return value gives the total pixel width of the character actually drawn, if known.

     Specifying a :WIDTH is a hint to improve performance. The :WIDTH is assumed to be the total pixel width of the character actually drawn. Specifying :WIDTH permits appending the output of subsequent calls to the same protocol request, provided gcontext has not been modified in the interim. If :WIDTH is not specified, appending of subsequent output might not occur (unless :TRANSLATE returns the character width).

     The :SIZE specifies the element size of the destination buffer given to :TRANSLATE (either 8, 16, or :DEFAULT). If :DEFAULT is specified, the size is based on the current font, if known; otherwise, 16 is used.

     output-p
          Type BOOLEAN.

     width
          Type INT32 or NULL.

 -- Function: draw-glyphs drawable gcontext x y sequence &key (:start 0) :end :translate :width (:size :default)

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context for drawing text.

     x
     y
          The left baseline position for the character drawn.

     sequence
          A sequence of characters or other objects to be translated into font indexes.

     :start
     :end
          Start and end indexes defining the elements to draw.

     :translate
          A function to translate text to font indexes. Default is #'TRANSLATE-DEFAULT.

     :width
          The total total pixel width of the character actually drawn, if known.

     :size
          The element size of the destination buffer given to :TRANSLATE (8, 16, or :DEFAULT).

     Draws the filled text characters represented by the given sequence. :START and :END define the elements of the sequence which are drawn. The given x and y specify the left baseline position for the first character. The first return value is NIL if all characters are successfully translated and drawn; otherwise, the index of the first untranslated sequence element is returned. The second return value gives the total pixel width of the characters actually drawn, if known.

     Specifying a :WIDTH is a hint to improve performance. The :WIDTH is assumed to be the total pixel width of the character sequence actually drawn. Specifying :WIDTH permits appending the output of subsequent calls to the same protocol request, provided gcontext has not been modified in the interim. If :WIDTH is not specified, appending of subsequent output might not occur (unless :TRANSLATE returns the character width).

     The :SIZE specifies the element size of the destination buffer given to :TRANSLATE (either 8, 16, or :DEFAULT). If :DEFAULT is specified, the size is based on the current font, if known; otherwise, 16 is used.

     new-start
          Type ARRAY-INDEX or NULL.

     width
          Type INT32 or NULL.

 -- Function: draw-image-glyph drawable gcontext x y element &key :translate :width (:size :default)

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context for drawing text.

     x
     y
          The left baseline position for the character drawn.

     element
          A character or other object to be translated into a font index.

     :translate
          A function to translate text to font indexes. Default is #'TRANSLATE-DEFAULT.

     :width
          The total pixel width of the character actually drawn, if known.

     :size
          Specifies the element size of the destination buffer given to :TRANSLATE (8, 16, or :DEFAULT).

     Draws a single character of block text represented by the given element. The given x and y specify the left baseline position for the character. The first return value is true if the character is successfully translated and drawn, or NIL if the :TRANSLATE function did not translate it. The :TRANSLATE function is allowed to return an initial font change. The second return value gives the total pixel width of the character actually drawn, if known.

     The :TRANSLATE function may not return a horizontal position change, since DRAW-IMAGE-GLYPH does not generate complex output requests.

     Specifying a :WIDTH is a hint to improve performance. The :WIDTH is assumed to be the total pixel width of the character actually drawn. Specifying :WIDTH permits appending the output of subsequent calls to the same protocol request, provided gcontext has not been modified in the interim. If :WIDTH is not specified, appending of subsequent output might not occur (unless :TRANSLATE returns the character width).

     The :SIZE specifies the element size of the destination buffer given to :TRANSLATE (either 8, 16, or :DEFAULT). If :DEFAULT is specified, the size is based on the current font, if known; otherwise, 16 is used.

     output-p
          Type BOOLEAN.

     width
          Type INT32 or NULL.

 -- Function: draw-image-glyphs drawable gcontext x y sequence &key (:start 0) :end :translate :width (:size :default)

     drawable
          The destination DRAWABLE.

     x
     y
          The left baseline position for the character drawn.

     gcontext
          The graphics context for drawing text.

     sequence
          A sequence of characters or other objects to be translated into font indexes.

     :start
     :end
          Start and end indexes defining the elements to draw.

     :translate
          A function to translate text to font indexes. Default is #'TRANSLATE-DEFAULT.

     :width
          The total total pixel width of the character actually drawn, if known.

     :size
          The element size of the destination buffer given to :TRANSLATE (8, 16, or :DEFAULT).

     Draws the block text characters represented by the given SEQUENCE. :START and :END define the elements of the sequence which are drawn. The given x and y specify the left baseline position for the first character. The first return value is NIL if all characters are successfully translated and drawn; otherwise, the index of the first untranslated sequence element is returned. The :TRANSLATE function is allowed to return an initial font change. The second return value gives the total pixel width of the characters actually drawn, if known.

     The :TRANSLATE function may not return a horizontal position change, since DRAW-IMAGE-GLYPHS does not generate complex output requests.

     Specifying a :WIDTH is a hint to improve performance. The :WIDTH is assumed to be the total pixel width of the character sequence actually drawn. Specifying :WIDTH permits appending the output of subsequent calls to the same protocol request, provided gcontext has not been modified in the interim. If :WIDTH is not specified, appending of subsequent output might not occur (unless :TRANSLATE returns the character width).

     The :SIZE specifies the element size of the destination buffer given to :TRANSLATE (either 8, 16, or :DEFAULT). If :DEFAULT is specified, the size will be based on the current font, if known; otherwise, 16 is used.

     new-start
          Type ARRAY-INDEX or NULL.

     width
          Type INT32 or NULL.

 -- Function: translate-function source source-start source-end font destination destination-start

     source
          A sequence of characters or other objects to be translated.

     source-start
          An array-index specifying the first source element to be translated.

     source-end
          An array-index specifying the end of the source subsequence to be translated.

     font
          The font indexed by translated source elements.

     destination
          A vector where translated source elements are stored.

     destination-start
          An array-index specifying the position to begin storing translated source elements.

     A function used as the :TRANSLATE argument for text functions. Converts elements of the source (sub)sequence into font indexes for the given font and stores them into the destination vector.

     The destination vector is created automatically by CLX. destination is guaranteed to have room for (- source-end source-start) integer elements, starting at destination-start. Elements of destination can be either CARD8 or CARD16 integers, depending on the context. font is the current font, if known, or NIL otherwise. Starting with the element at source-start, TRANSLATE-FUNCTION should translate as many elements of source as possible (up to the source-end element) into indexes in the current font, and store them into destination. The first return value should be the source index of the first untranslated element.

     The second return value indicates the changes which should be made to the current text output request before translating the remaining source elements. If no further elements need to be translated, the second return value should be NIL. If a horizontal motion is required before further translation, the second return value should be the change in x position. If a font change is required for further translation, the second return value should be the new font.

     If known, the pixel width of the translated text can be returned as the third value; this can allow for appending of subsequent output to the same protocol request, if no overall width has been specified at the higher level.

     first-not-done
          Type ARRAY-INDEX.

     to-continue
          Type INT16, FONT, or NULL.

     current-width
          Type INT32 or NULL.

Images
******

The X protocol provides for the transfer of images (two-dimensional arrays of pixel data) between a client program and a DRAWABLE. The format for image data can vary considerably. In order to present a uniform data representation for the manipulation of a variety of images, CLX defines a special IMAGE data type. Additional IMAGE subtypes -- IMAGE-XY and IMAGE-Z -- allow for the representation of an image either as a sequence of bit planes or as an array of pixels. CLX includes functions for accessing IMAGE objects; for transferring image data between IMAGE objects, DRAWABLES, and files; and also for direct transfer of raw image data.

Image Types
===========

The IMAGE data type is the base type for all IMAGE objects. IMAGE-XY and IMAGE-Z are subtypes of the IMAGE type which furnish accessors specialized for different image representations.

Basic Images
------------

The following paragraphs describe the CLX functions that can be used to access all types of IMAGE objects.

 -- Function: image-blue-mask image

     image
          An IMAGE object.

     Returns (and with setf) changes the mask that selects the pixel subfield for blue intensity values. The mask is non-NIL only for images for :DIRECT-COLOR or :TRUE-COLOR visual types.

     mask
          Type PIXEL or NULL.

 -- Function: image-depth image

     image
          An IMAGE object.

     Returns the depth (that is, the number of bits per pixel) for the image.

     depth
          Type CARD8.

 -- Function: image-green-mask image

     image
          An IMAGE object.

     Returns (and with setf) changes the mask that selects the pixel subfield for green intensity values. The mask is non-NIL only for images for :DIRECT-COLOR or :TRUE-COLOR visual types.

     mask
          Type PIXEL or NULL.

 -- Function: image-height image

     image
          An IMAGE object.

     Returns the height of the image in pixels.

     height
          Type CARD16.

 -- Function: image-name image

     image
          An IMAGE object.

     Returns and (with setf) changes the name string optionally associated with the image.

     name
          Type STRINGABLE or NULL.

 -- Function: image-plist image

     image
          An IMAGE object.

     Returns and (with setf) changes the image property list. The property list is a hook for added application extensions.

     plist
          Type LIST.

 -- Function: image-red-mask image

     image
          An IMAGE object.

     Returns (and with setf) changes the mask which selects the pixel subfield for red intensity values. The mask is non-NIL only for images for :DIRECT-COLOR or :TRUE-COLOR visual types.

     mask
          Type PIXEL or NULL.

 -- Function: image-width image

     image
          An IMAGE object.

     Returns the width of the image in pixels.

     width
          Type CARD16.

 -- Function: image-x-hot image

     image
          An IMAGE object.

     Returns and (with setf) changes the x position of the hot spot for an image used as a cursor glyph. The hot spot position is specified relative to the upper-left origin of the image.

     x-position
          Type CARD16 or NULL.

 -- Function: image-y-hot image

     image
          An IMAGE object.

     Returns and (with setf) changes the y position of the hot spot for an image used as a cursor glyph. The hot spot position is specified relative to the upper-left origin of the image.

     y-position
          Type CARD16 or NULL.

XY-Format Images
----------------

The IMAGE-XY subtype represents an image as a sequence of bitmaps, one for each plane of the image, in most-significant to least-significant bit order. The following paragraphs describe the additional CLX functions that can be used to access IMAGE-XY objects.

 -- Function: image-xy-bitmap-list image

     image
          An IMAGE-XY object.

     Returns and (with setf) changes the list of bitmap planes for the image.

     bitmaps
          Type LIST of BITMAP.

Z-Format Images
---------------

The IMAGE-Z subtype represents an image as a two-dimensional array of pixels, in scanline order. The following paragraphs describe the additional CLX functions that can be used to access IMAGE-Z objects.

 -- Function: image-z-bits-per-pixel image

     image
          An IMAGE-Z object.

     Returns and (with setf) changes the number of bits per data unit used to contain a pixel value for the image. Depending on the storage format for image data, this value can be larger than the actual image depth.

     pixel-data-size
          One of 1, 4, 8, 16, 24, or 32.

 -- Function: image-z-pixarray image

     image
          An IMAGE-Z object.

     Returns and (with setf) changes the two-dimensional array of pixel data for the image.

     pixarray
          Type PIXARRAY.

Image Functions
===============

The following paragraphs describe the CLX functions used to:

  * Create an IMAGE object.

  * Copy an image or a subimage.

  * Read an image from a DRAWABLE.

  * Display an image to a DRAWABLE.

 -- Function: create-image &key :bit-lsb-first-p :bits-per-pixel :blue-mask :byte-lsb-first-p :bytes-per-line :data :depth :format :green-mask :height :name :plist :red-mask :width :x-hot :y-hot Function

     :bit-lsb-first-p
          For a returned image, true if the order of bits in each :DATA byte is least-significant bit first.

     :bits-per-pixel
          One of 1, 4, 8, 16, 24, or 32.

     :blue-mask
          For :TRUE-COLOR or :DIRECT-COLOR images, a pixel mask.

     :byte-lsb-first-p
          For a returned image, true if the :DATA byte order is least-significant byte first.

     :bytes-per-line
          For a returned image, the number of :DATA bytes per scanline.

     :data
          Either a LIST of BITMAPS, a PIXARRAY, or an array of CARD8 bytes.

     :depth
          The number of bits per displayed pixel.

     :format
          One of :BITMAP, :XY-FORMAT, or :Z-FORMAT.

     :green-mask
          For :TRUE-COLOR or :DIRECT-COLOR images, a pixel mask.

     :height
          A CARD16 for the image height in pixels.

     :name
          An optional STRINGABLE for the image name.

     :plist
          An optional image property list.

     :red-mask
          For :TRUE-COLOR or :DIRECT-COLOR images, a pixel mask.

     :width
          A CARD16 for the image width in pixels.

     :x-hot
          For a CURSOR image, the x position of the hot spot.

     :y-hot
          For a cursor image, the y position of the hot spot.

     Creates an IMAGE object from the given :DATA and returns either an IMAGE, IMAGE-XY, or an IMAGE-Z, depending on the type of image :DATA. If the :DATA is a list, it is assumed to be a LIST of BITMAPS and an IMAGE-XY is created. If the :DATA is a PIXARRAY, an IMAGE-Z is created. Otherwise, the :DATA must be an array of bytes (CARD8), in which case a basic IMAGE object is created.

     If the :DATA is a list, each element must be a bitmap of equal size. :WIDTH and :HEIGHT default to the bitmap width -- (ARRAY-DIMENSION BITMAP 1) -- and the bitmap height -- (ARRAY-DIMENSION BITMAP 0) -- respectively. :DEPTH defaults to the number of bitmaps.

     If the :DATA is a PIXARRAY, :WIDTH and :HEIGHT default to the PIXARRAY width -- (ARRAY-DIMENSION PIXARRAY 1), and the pixarray height -- (ARRAY-DIMENSION PIXARRAY 0), respectively. :DEPTH defaults to (PIXARRAY-DEPTH :DATA). The :BITS-PER-PIXEL is rounded to a valid size, if necessary. By default, the :BITS-PER-PIXEL is equal to the :DEPTH.

     If the :DATA is an array of CARD8, the :WIDTH and :HEIGHT are required to interpret the image data correctly. The :BITS-PER-PIXEL defaults to the :DEPTH, and the :DEPTH defaults to 1. :BYTES-PER-LINE defaults to:

          (FLOOR (LENGTH :DATA) (* :BITS-PER-PIXEL :HEIGHT))

     The :FORMAT defines the storage format of image data bytes and can be one of the following values:

     :xy-pixmap
          The :DATA is organized as a set of bitmaps representing image bit planes, appearing in most-significant to least-significant bit order.

     :z-pixmap
          The :DATA is organized as a set of pixel values in scanline order.

     :bitmap
          Similar to :XY-PIXMAP, except that the :DEPTH must be 1, and 1 and 0 bits represent the foreground and background pixels, respectively.

     By default, the :FORMAT is :BITMAP if :DEPTH is 1; otherwise, :Z-PIXMAP.

          Type IMAGE.

 -- Function: copy-image image &key (:x 0) (:y 0) :width :height :result-type

     image
          An IMAGE object.

     :x
     :y
          CARD16 values defining the position of the upper-left corner of the subimage copied.

     :width
     :height
          CARD16 values defining the size of subimage copied.

     :result-type
          One of 'IMAGE-X, 'IMAGE-XY, or 'IMAGE-Z.

     Returns a new image, of the given :RESULT-TYPE, containing a copy of the portion of the image defined by :X, :Y, :WIDTH, and :HEIGHT. By default, :WIDTH is:

          (- (IMAGE-WIDTH image) :X)

     and :HEIGHT is:

          (- (IMAGE-HEIGHT image) :Y)

     If necessary, the new image is converted to the :RESULT-TYPE, that can be one of the following values:

     'image-x
          A basic IMAGE object is returned.

     'image-xy
          An IMAGE-XY is returned.

     'image-z
          An IMAGE-Z is returned.

     new-image
          Type IMAGE.

 -- Function: get-image drawable &key :x :y :width :height :plane-mask (:format :z-format) :result-type Function

     drawable
          A DRAWABLE.

     :x
     :y
          CARD16 values defining the upper-left DRAWABLE pixel returned. These arguments are required.

     :width
     :height
          CARD16 values defining the size of the image returned. These arguments are required.

     :plane-mask
          A pixel mask.

     :format
          Either :XY-PIXMAP or :Z-PIXMAP.

     :result-type
          One of 'IMAGE-X, 'IMAGE-XY, or 'IMAGE-Z.

     Returns an image containing pixel values from the region of the drawable given by :X, :Y, :WIDTH, and :HEIGHT. The bits for all planes selected by 1 bits in the :PLANE-MASK are returned as zero; the default :PLANE-MASK is all 1 bits. The :FORMAT of the returned pixel values may be either :XY-FORMAT or :Z-FORMAT.

     The :RESULT-TYPE defines the type of image object returned:

     'image-x
          A basic IMAGE object is returned.

     'image-xy
          An IMAGE-XY is returned.

     'image-z
          An IMAGE-Z is returned.

     By default, :RESULT-TYPE is 'IMAGE-Z if :FORMAT is :Z-FORMAT and 'IMAGE-XY if :FORMAT is :XY-FORMAT.

          Type IMAGE.

 -- Function: put-image drawable gcontext image &key (:src-x 0) (:src-y 0) :x :y :width :height :bitmap-p

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context used to display the image.

     image
          An IMAGE object.

     :src-x
     :src-y
          CARD16 values defining the upper-left position of the image region to display.

     :x
     :y
          The position in the drawable where the image region is displayed. These arguments are required.

     :width :height
          CARD16 values defining the size of the image region displayed.

     :bitmap-p
          If image is depth 1, then if true, foreground and background pixels are used to display 1 and 0 bits of the image.

     Displays a region of the image defined by :SRC-X, :SRC-Y, :WIDTH, and :HEIGHT on the destination drawable, with the upper-left pixel of the image region displayed at the drawable position given by :X and :Y. By default, :WIDTH is:

          (- (IMAGE-WIDTH image) :SRC-X)

     and :HEIGHT is:

          (- (IMAGE-HEIGHT image) :SRC-Y)

     The following attributes of the gcontext are used to display the IMAGE: clip-mask, clip-x, clip-y, function, plane-mask, and subwindow-mode.

     The :BITMAP-P argument applies only to images of depth 1. In this case, if :BITMAP-P is true or if the image is a basic IMAGE object created with :FORMAT :BITMAP, the image is combined with the foreground and background pixels of the GCONTEXT. 1 bits of the image are displayed in the foreground pixel and 0 bits are displayed in the background pixel.

Image Files
===========

CLX provides functions that allow images to be written to a file in a standard X format. The following paragraphs describe the CLX functions used to:

  * Read an image from a file.

  * Write an image to a file.

 -- Function: read-bitmap-file pathname

     pathname
          An image file pathname.

     Reads an image file in standard X format and returns an IMAGE object. The returned image can have depth greater than one.

     image
          Type IMAGE.

 -- Function: write-bitmap-file pathname image &optional name

     pathname
          An image file pathname.

     image
          An IMAGE object.

     name
          A STRINGABLE image name.

     Writes the image to an image file in standard X format. The image can have depth greater than one. The name is an image identifier written to the file; the default name is (OR (IMAGE-NAME image) 'IMAGE).

Direct Image Transfer
=====================

For cases where the IMAGE representation is not needed, CLX provides functions to read and display image data directly.
 -- Function: get-raw-image drawable &key :data (:start 0) :x :y :width :height :plane-mask (:format :z-format) (:result-type '(vector card8))

     drawable
          A DRAWABLE.

     :data
          An optional SEQUENCE of CARD8.

     :start
          The index of the first :DATA element modified.

     :x
     :y
          CARD16 values defining the size of the IMAGE returned. These arguments are required.

     :width
     :height
          CARD16 values defining the size of the image returned.These arguments are required.

     :plane-mask
          A pixel mask.

     :format
          Either :XY-PIXMAP or :Z-PIXMAP. This argument is required.

     :result-type
          The type of image data sequence to return.

     Returns a sequence of image data from the region of the drawable given by :X, :Y, :WIDTH, and :HEIGHT. If :DATA is given, it is modified beginning with the element at the :START index and returned. The depth and visual type ID of the drawable are also returned.

     The bits for all planes selected by 1 bits in the :PLANE-MASK are returned as zero; the default :PLANE-MASK is all 1 bits. The :FORMAT of the returned pixel values may be either :XY-FORMAT or :Z-FORMAT. The :RESULT-TYPE defines the type of image data returned.

     The calling program is responsible for handling the byte-order and bit-order returned by the server for the drawable's display (see DISPLAY-BYTE-ORDER and DISPLAY-IMAGE-LSB-FIRST-P).

     data
          Type SEQUENCE or CARD8.

     depth
          Type CARD8.

     visual
          Type CARD29.

 -- Function: put-raw-image drawable gcontext data &key (:start 0) :depth :x :y :width :height (:left-pad 0) :format

     drawable
          The destination DRAWABLE.

     gcontext
          The graphics context used to display the image.

     data
          A sequence of integers.

     :start
          The index of the first element of data displayed.

     :depth
          The number of bits per pixel displayed. This argument is required.

     :x
     :y
          The position in the drawable where the image region is displayed. These arguments are required.

     :width
     :height
          CARD16 values defining the size of the image region displayed. These arguments are required.

     :left-pad
          A CARD8 specifying the number of leading bits to discard for each image scanline.

     :format
          One of :BITMAP, :XY-PIXMAP, or :Z-PIXMAP.

     Displays a region of the image data defined by :START, :LEFT-PAD, :WIDTH, and :HEIGHT on the destination drawable, with the upper-left pixel of the image region displayed at the drawable position given by :X and :Y.

     The :FORMAT can be either :XY-PIXMAP, :Z-PIXMAP, or :BITMAP. If :XY-PIXMAP or :Z-PIXMAP formats are used, :DEPTH must match the depth of the destination drawable. For :XY-PIXMAP, the data must be in XY format. For :Z-PIXMAP, the data must be in Z format for the given :DEPTH.

     If the :FORMAT is :BITMAP, the :DEPTH must be 1. In this case, the image is combined with the foreground and background pixels of the gcontext. 1 bits of the image are displayed in the foreground pixel and 0 bits are displayed in the background pixel.

     The :LEFT-PAD must be zero for :Z-PIXMAP format. For :BITMAP and :XY-PIXMAP formats, the :LEFT-PAD must be less than the bitmap-scanline-pad for the drawable's display (see display-bitmap-format). The first :LEFT-PAD bits in every scanline are to be ignored by the server; the actual image begins that many bits into the data.

     The following attributes of the gcontext are used to display the IMAGE: clip-mask, clip-x, clip-y, function, plane-mask, and subwindow-mode.

     The calling program is responsible for handling the byte-order and bit-order required by the server for the drawable's display (see DISPLAY-BYTE-ORDER and DISPLAY-IMAGE-LSB-FIRST-P).

Font and Characters
*******************

An X server maintains a set of fonts used in the text operations requested by client programs. An X font is an array of character bit maps (or glyphs) indexed by integer codes. In fact, font glyphs can also represent cursor shapes or other images and are not limited to character images. X supports both linear and matrix encoding of font indexes.  With linear encoding, a font index is interpreted as a single 16-bit integer index into a one-dimensional array of glyphs. With matrix encoding, a font index is interpreted as a pair of 8-bit integer indexes into a two-dimensional array of glyphs. The type of index encoding used is font-dependent.

In order to access or use a font, a client program must first open it using the OPEN-FONT function, sending a font name string as an identifier. OPEN-FONT creates a CLX FONT object used to refer to the font in subsequent functions. Afterward, calling OPEN-FONT with the same font name returns the same FONT object. When a font is no longer in use, a client program can call CLOSE-FONT to destroy the FONT object.

A font has several attributes which describe its geometry and its glyphs. CLX provides functions to return the attributes of a font, as well functions for accessing the attributes of individual font glyphs. Glyph attributes are referred to as character attributes, since characters are the most common type of font glyphs. A font also has a property list of values recorded by the X server. However, the set of possible font properties and their values are not standardized and are implementation-dependent. Typically, CLX maintains a cache of font and character attributes, in order to minimize server requests. However, the font cache mechanism is implementation-dependent and cannot be controlled by the client. In some cases, CLX may create a pseudo-font object solely for the purpose of accessing font attributes. A pseudo-font is represented by a special type of FONT object that cannot be used in a GCONTEXT. If necessary, CLX can automatically convert a pseudo-font into a true font, if the name of the pseudo-font is known.

The set of available fonts is server-dependent; that is, font names are not guaranteed to be portable from one server to the next. However, the public X implementation from MIT includes a set of fonts that are typically available with most X servers.

The following paragraphs describe CLX functions to:

  * Open and close fonts.

  * List available fonts.

  * Access font attributes.

  * Access character attributes.

  * Return the size of a text string.

Opening Fonts
=============

The following paragraphs discuss the CLX functions for opening and closing fonts.

 -- Function: open-font display name

     display
          A DISPLAY object.

     name
          A font name string.

     Opens the font with the given name and returns a FONT object. The name string should contain only ISO Latin-1 characters; case is not significant.

     font
          Type FONT.

 -- Function: close-font font

     font
          A FONT object.

     Deletes the association between the resource ID and the font. The font is freed when no other server resource references it. The font can be unloaded by the X server if this is the last reference to the font by any client. In any case, the font should never again be referenced because its resource ID is destroyed. This might not generate a protocol request if the font is reference-counted locally or if it is a pseudo-font.

 -- Function: discard-font-info fonts

     font
          A FONT object.

     Discards any state that can be re-obtained with OPEN-FONT. This is simply a performance hint for memory-limited systems.

Listing Fonts
=============

The following paragraphs describe CLX functions that return fonts or font names that match a given pattern string. Such pattern strings should contain only ISO Latin-1 characters; case is not significant. The following pattern characters can be used for wildcard matching:

#\*
     Matches any sequence of zero or more characters.

#\?
     Matches any single character.

For example, the pattern "T?mes Roman" matches the name "Times Roman" but not the name "Thames Roman". However, the pattern "T*mes Roman" matches both names.

 -- Function: font-path display &key (:result-type 'list)

     display
          A DISPLAY object.

     :result-type
          Specifies the type of resulting sequence.

     Returns a LIST (by default) of names containing the current search path for fonts. With setf, this function sets the search path for font lookup. There is only one search path per server, not one per client. The interpretation of the names is server-dependent, but they are intended to specify directories to be searched in the order listed.

     Setting the path to the empty list restores the default path defined for the server. Note that as a side-effect of executing this request, the server is guaranteed to flush all cached information about fonts for which there are currently no explicit resource IDs allocated.

     paths
          Type SEQUENCE of either STRING or PATHNAME.

 -- Function: list-font-names display pattern &key (:max-fonts 65535) (:result-type 'list)

     display
          A DISPLAY object.

     pattern
          A string used to match font names. Only font names that match the pattern are returned.

     :max-fonts
          The maximum number of font names returned. Default is 65535.

     :result-type
          The type of sequence to return. Default is 'LIST.

     Returns a sequence of strings containing the font names that match the pattern. The fonts available are determined by the font search path; see FONT-PATH). The maximum number of font names returned is determined by :MAX-FONTS.

     font-name
          Type SEQUENCE of STRING.

 -- Function: list-fonts display pattern &key (:max-fonts 65535) (:result-type 'list)

     display
          A DISPLAY object.

     pattern
          A string used to match font names. Only fonts whose name matches the pattern are returned.

     :max-fonts
          The maximum number of fonts returned. Default is 65535.

     :result-type
          The type of sequence to return. Default is 'LIST.

     Returns a sequence of pseudo-fonts corresponding to the available fonts whose names match the pattern. The fonts available are determined by the font search path; see FONT-PATH). The maximum number of FONT objects returned is determined by :MAX-FONTS.

     font
          Type SEQUENCE of FONT.

Font Attributes
===============

The following paragraphs describe the CLX functions used to access font attributes.

 -- Function: font-all-chars-exist-p font

     exists-p
          Type BOOLEAN.

     Returns true if glyphs exist for all indexes in the range returned by FONT-MIN-CHAR and FONT-MAX-CHAR. Returns NIL if an index in the range corresponds to empty glyph.

     font
          A FONT object.

 -- Function: font-ascent font

     ascent
          Type INT16.

     Returns the vertical ascent of the font used for interline spacing. The ascent defines the nominal distance in pixels from the baseline to the bottom of the previous line of text.  Some font glyphs may actually extend beyond the font ascent.

     font
          A FONT object.

 -- Function: font-default-char font

     index
          Type CARD16.

     Returns the index of the glyph drawn when an invalid or empty glyph index is specified.  If the default index specifies an invalid or empty glyph, an invalid or empty index has no effect.

     font
          A FONT object.

 -- Function: font-descent font

     descent
          Type INT16.

     Returns the vertical descent of the font used for interline spacing. The descent defines the nominal distance in pixels from the baseline to the top of the next line of text. Some font glyphs may actually extend beyond the font descent.

     font
          A FONT object.

 -- Function: font-direction font

     direction
          Type DRAW-DIRECTION.

     Returns the nominal drawing direction for the font. The font drawing direction is only a hint that indicates whether the char-width of most font glyphs is positive (:LEFT-TO-RIGHT direction) or negative (:RIGHT-TO-LEFT direction). Note that X does not provide any direct support for vertical text.

     font
          A FONT object.

 -- Function: font-display font

     font
          A FONT object.

     Returns the DISPLAY object associated with the specified font.

     display
          Type DISPLAY.

 -- Function: font-equal font-1 font-2

     font-1
     font-2
          The FONT objects.

     Returns true if the two arguments refer to the same server resource and NIL if they do not.

 -- Function: font-id font

     font
          A FONT object.

     Returns the unique resource ID assigned to the specified font.

     id
          Type RESOURCE-ID.

 -- Function: font-max-byte1 font

     font
          A FONT object.

     Returns zero if the font uses linear index encoding. Otherwise, if the font uses matrix index encoding, a value between 1 and 255 is returned that specifies the maximum value for the most significant byte of font indexes.

     max-byte1
          Type CARD8.

 -- Function: font-max-byte2 font

     font
          A FONT object.

     Returns zero if the font uses linear index encoding. Otherwise, if the font uses matrix index encoding, a value between 1 and 255 is returned that specifies the maximum value for the least significant byte of font indexes.

     max-byte2
          Type CARD8.

 -- Function: font-max-char font

     font
          A FONT object.

     Returns the maximum valid value used for linear encoded indexes. This function is not meaningful for fonts that use matrix index encoding.

     index
          Type CARD16.

 -- Function: font-min-byte1 font

     font
          A FONT object.

     Returns zero if the font uses linear index encoding. Otherwise, if the font uses matrix index encoding, a value between 1 and 255 is returned that specifies the minimum value for the most significant byte of font indexes.

     min-byte1
          Type CARD8.

 -- Function: font-min-byte2 font

     font
          A FONT object.

     Returns zero if the font uses linear index encoding. Otherwise, if the font uses matrix index encoding, a value between 1 and 255 is returned that specifies the minimum value for the least significant byte of font indexes.

     min-byte2
          Type CARD8.

 -- Function: font-min-char font

     font
          A FONT object.

     Returns the minimum valid value used for linear encoded indexes. This function is not meaningful for fonts that use matrix index encoding.

     index
          Type CARD16.

 -- Function: font-name font

     font
          A FONT object.

     Returns the name of the font, or NIL if font is a pseudo-font.

     name
          Type STRING or NULL.

 -- Function: font-p font

     Returns true if the argument is a FONT object and NIL otherwise.

     font-p
          Type BOOLEAN.

 -- Function: font-plist font

     font
          A FONT object.

     Returns and (with setf) sets the property list for the specified font. This function provides a hook where extensions can add data.

     plist
          Type LIST.

 -- Function: font-properties font

     font
          A FONT object.

     Returns the list of font properties recorded by the X server. The returned list is a property list of keyword/value pairs. The set of possible font property keywords is implementation-dependent.

     properties
          Type LIST.

 -- Function: font-property font name

     font
          A FONT object.

     name
          A font property keyword.

     Returns the value of the font property specified by the name keyword. The property value, if it exists, is returned as an uninterpreted 32-bit integer.

     property
          Type INT32 or NULL.

 -- Function: max-char-ascent font

     font
          A FONT object.

     Returns the maximum CHAR-ASCENT value for all characters in font.

     ascent
          Type INT16.

 -- Function: max-char-attributes font

     font
          A FONT object.

     Returns the maximum CHAR-ATTRIBUTES value for all characters in font.

     attributes
          Type INT16.

 -- Function: max-char-descent font

     font
          A FONT object.

     Returns the maximum CHAR-DESCENT value for all characters in font.

     descent
          Type INT16.

 -- Function: max-char-left-bearing font

     font
          A FONT object.

     Returns the maximum CHAR-LEFT-BEARING value for all characters in font.

     left-bearing
          Type INT16.

 -- Function: max-char-right-bearing font

     font
          A FONT object.

     Returns the maximum CHAR-RIGHT-BEARING value for all characters in font.

     right-bearing
          Type INT16.

 -- Function: max-char-width font

     font
          A FONT object.

     Returns the maximum CHAR-WIDTH value for all characters in font.

     width
          Type INT16.

 -- Function: min-char-ascent font

     font
          A FONT object.

     Returns the minimum CHAR-ASCENT for all characters in font.

     ascent
          Type INT16.

 -- Function: min-char-attributes font

     font
          A FONT object.

     Returns the minimum CHAR-ATTRIBUTES for all characters in font.

     attributes
          Type INT16.

 -- Function: min-char-descent font

     font
          A FONT object.

     Returns the minimum CHAR-DESCENT for all characters in font.

     descent
          Type INT16.

 -- Function: min-char-left-bearing font

     font
          A FONT object.

     Returns the minimum CHAR-LEFT-BEARING for all characters in font.

     left-bearing
          Type INT16.

 -- Function: min-char-right-bearing font

     font
          A FONT object.

     Returns the minimum CHAR-RIGHT-BEARING for all characters in font.

     right-bearing
          Type INT16.

 -- Function: min-char-width font

     font
          A FONT object.

     Returns the minimum CHAR-WIDTH for all characters in font.

     width
          Type INT16.

Chracter Attributes
===================

The following paragraphs describe the CLX functions used to access the attributes of individual font glyphs.

 -- Function: char-ascent font index

     font
          A FONT object.

     index
          An INT16 font index.

     Returns the vertical distance in pixels from the baseline to the top of the given font glyph. Returns NIL if the index is invalid or specifies an empty glyph, or if the font is a pseudo-font.

     ascent
          Type INT16 or NULL.

 -- Function: char-attributes font index

     font
          A FONT object.

     index
          An INT16 font index.

     Returns font-specific attributes of the given glyph. The interpretation of such attributes is server-dependent. Returns NIL if the index is invalid or specifies an empty glyph, or if the font is a pseudo-font.

     attributes
          Type INT16 or NULL.

 -- Function: char-descent font index

     font
          A FONT object.

     index
          An INT16 font index.

     Returns the vertical distance in pixels from the baseline to the bottom of the given font glyph. Returns NIL if the index is invalid or specifies an empty glyph, or if the font is a pseudo-font.

     descent
          Type INT16 or NULL.

 -- Function: char-left-bearing font index

     font
          A FONT object.

     index
          An INT16 font index.

     Returns the left side bearing of the given font glyph. If DRAW-GLYPH is called with horizontal position x, the leftmost pixel of the glyph is drawn at the position (+ x left-bearing). Returns NIL if the index is invalid or specifies an empty glyph, or if the font is a pseudo-font.

     left-bearing
          Type INT16 or NULL.

 -- Function: char-right-bearing font index

     font
          A font object.

     index
          An INT16 font index.

     Returns the right side bearing of the given font glyph. If nDRAW-GLYPH is called with horizontal position x, the rightmost pixel of the glyph is drawn at the position (+ x rightbearing). Returns NIL if the index is invalid or specifies an empty glyph, or if the font is a pseudo-font.

     right-bearing
          Type INT16 or NULL.

 -- Function: char-width font index

     font
          A FONT object.

     index
          An INT16 font index.

     Returns the width of the given font glyph. The width is defined to be equal to (- rightbearing left-bearing). Returns NIL if the index is invalid or specifies an empty glyph, or if the font is a pseudo-font.

     width
          Type INT16 or NULL.

Querying Text Size
==================

CLX defines functions to return the size of text drawn in a specified font. See Drawing Text, for a description of the :TRANSLATE function used by the functions in the following paragraphs.

 -- Function: text-extents font sequence &key (:start 0) :end :translate

     font
          The font (or GCONTEXT) used for measuring characters.

     sequence
          A sequence of characters or other objects to be translated into font indexes.

     :start
     :end
          Start and end indexes defining the elements to draw.

     :translate
          A function to translate text to font indexes. Default is #'TRANSLATE-DEFAULT.

     Returns the complete geometry of the given sequence when drawn in the given font. The font can be a GCONTEXT, in which case the font attribute of the given graphics context is used. :START and :END define the elements of the sequence which are used.

     The returned width is the total pixel width of the translated character sequence. The returned ascent and descent give the vertical ascent and descent for characters in the translated sequence. The returned left gives the left bearing of the leftmost character. The returned right gives the right bearing of the rightmost character. The returned font-ascent and font-descent give the maximum vertical ascent and descent for all characters in the font. If :TRANSLATE causes font changes, then font-ascent and font-descent will be the maximums over all fonts used. The direction returns the preferred draw direction for the font. If :TRANSLATE causes font changes, then the direction will be NIL. The first-not-done value returned is NIL if all elements of the sequence were successfully translated; otherwise the index of the first untranslated element is returned.

     width
          Type INT32.

     ascent
          Type INT16.

     descent
          Type INT16.

     left
          Type INT32.

     right
          Type INT32.

     font-ascent
          Type INT16.

     direction
          Type DRAW-DIRECTION.

     first-not-done
          Type ARRAY-INDEX or NULL.

 -- Function: text-width font sequence &key (:start 0) :end :translate

     font
          The font (or GCONTEXT) used for measuring characters.

     sequence
          A sequence of characters or other objects to be translated into font indexes.

     :start

     :end
          Start and end indexes defining the elements to draw.

     :translate
          A function to translate text to font indexes. Default is #'TRANSLATE-DEFAULT.

     Returns the total pixel width of the given sequence when drawn in the given font. The font can be a GCONTEXT, in which case the font attribute of the given graphics context is used. :START and :END define the elements of the sequence which are used. The second value returned is NIL if all elements of the sequence were successfully translated; otherwise the index of the first untranslated element is returned.

     width
          Type INT32.

     first-not-done
          Type ARRAY-INDEX or NULL.

Colors
******

Colormaps and Colors
====================

In X, a color is defined by a set of three numeric values, representing intensities of red, green, and blue. Red, green, and blue are referred to as the primary hues. A colormap is a list of colors, each indexed by an integer pixel value. Each entry in a colormap is called a color cell. Raster graphics displays store pixel values in a special screen hardware memory. As the screen hardware scans this memory, it reads each pixel value, looks up the color in the corresponding cell of a colormap, and displays the color on its screen.

The colormap abstraction applies to all classes of visual types supported by X, including those for screens which are actually monochrome. For example, :GRAY-SCALE screens use colormaps in which colors actually specify the monochrome intensity. A typical black-and-white monochrome display has a :STATIC-GRAY screen with a two-cell colormap.

The following list describes how pixel values and colormaps are handled for each visual class.

:direct-color
     A pixel value is decomposed into separate red, green, and blue subfields. Each subfield indexes a separate colormap. Entries in all colormaps can be changed.

:gray-scale
     A pixel value indexes a single colormap that contains monochrome intensities. Colormap entries can be changed.

:pseudo-color
     A pixel value indexes a single colormap that contains color intensities. Colormap entries can be changed.

:static-color
     Same as :PSEUDO-COLOR, except that the colormap entries are predefined by the hardware and cannot be changed.

:static-gray
     Same as :GRAY-SCALE, except that the colormap entries are predefined by the hardware and cannot be changed.

:true-color
     Same as :DIRECT-COLOR, except that the colormap entries are predefined by the hardware and cannot be changed. Typically, each of the red, green, and blue colormaps provides a (near) linear ramp of intensity.

CLX provides functions to create colormaps, access and modify colors and color cells, and install colormaps in screen hardware.

Color Functions
===============

A color is represented by a CLX color object, in which each of the red, green, and blue values is specified by an RGB-VAL -- a floating point number between 0.0 and 1.0.  (see Data Types). The value 0.0 represents the minimum intensity, while 1.0 represents the maximum intensity. CLX automatically converts RGB-VAL values into 16-bit integers when sending colors to an X server. The X server, in turn, scales 16-bit color values to match the actual intensity range supported by the screen.

Colors used on :GRAY-SCALE screens must have the same value for each of red, green, and blue. Only one of these values is used by screen hardware to determine intensity; however, CLX does not define which of red, green, or blue is actually used.

The following paragraphs describe the CLX functions used to create, access, and modify colors.

 -- Function: make-color &key (:blue 1.0) (:green 1.0) (:red 1.0) &allow-other-keys

     :blue
     :green
     :red
          RGB-VAL values that specify the saturation for each primary.

     Creates, initializes, and returns a new COLOR object with the specified values for red, green, and blue.

     color
          Type COLOR.

 -- Function: color-blue color

     color
          A COLOR object.

     Returns and (with setf) sets the value for blue in the color.

     blue-intensity
          Type RGB-VAL.

 -- Function: color-green color

     color
          A COLOR object.

     Returns and (with setf) sets the value for green in the color.

     green-intensity
          Type RGB-VAL.

 -- Function: color-p color

     Returns non-NIL if the argument is a COLOR object and NIL otherwise.

     color-p
          Type BOOLEAN.

 -- Function: color-red color

     color
          A COLOR object.

     Returns and (with setf) sets the value for red in the color.

     red-intensity
          Type RGB-VAL.

 -- Function: color-rgb color

     color
          A COLOR object.

     Returns the values for red, green, and blue in the color.

     red
     green
     blue
          Type RGB-VAL.

Colormap Functions
==================

A colormap is represented in CLX by a COLORMAP object. A CLX program can create and manipulate several COLORMAP objects. However, the colors contained in a COLORMAP are made visible only when the COLORMAP is installed. Each window is associated with a COLORMAP that is used to translate window pixels into colors (see WINDOW-COLORMAP). However, a window will appear in its true colors only if its associated COLORMAP is installed.

The total number of colormaps that can be installed depends on the screen hardware.  Most hardware devices allow exactly one COLORMAP to be installed at any time. That is, SCREEN-MIN-INSTALLED-MAPS and SCREEN-MAX-INSTALLED-MAPS are both equal to 1.  Installing a new COLORMAP can cause a previously installed COLORMAP to be uninstalled. It is important to remember that the set of installed COLORMAPS is a hardware resource shared cooperatively among all client programs connected to an X server.

A CLX program can control the contents of COLORMAPS by allocating color cells in one of two ways: read-only or read-write. Allocating a read-only color cell establishes a color value for a specified pixel value that cannot be changed. However, read-only color cells can be shared among all client programs. Read-only allocation is the best strategy for making use of limited COLORMAP hardware in a multi-client environment.

Alternatively, allocating a read-write color cell allows a client the exclusive right to set the color value stored in the cell. A cell allocated read-write by one client cannot be allocated by another client, not even as a read-only cell. Note that read-write allocation is not allowed for screens whose visual type belongs to one of the :STATIC-GRAY, :STATIC-COLOR, or :TRUE-COLOR classes. For screens of these classes, COLORMAP cells cannot be modified.

Two entries of the default colormap, typically containing the colors black and white, are automatically allocated read-only. The pixel values for these entries can be returned by the functions SCREEN-BLACK-PIXEL and SCREEN-WHITE-PIXEL. Applications that need only two colors and also need to operate on both monochrome and color screens should always use these pixel values. The names black and white are intended to reflect relative intensity levels and need not reflect the actual colors displayed for these pixel values.

Each screen has a default COLORMAP, which is initially installed. By conventions, clients should allocate only read-only cells from the default COLORMAP.

Creating Colormaps
------------------

CLX provides functions for creating and freeing new COLORMAP objects.

 -- Function: create-colormap visual window &optional alloc-p

     visual
          A VISUAL type ID.

     window
          A WINDOW.

     alloc-p
          Specifies whether COLORMAP cells are permanently allocated read-write.

     Creates and returns a colormap of the specified visual type for the screen containing the window. The visual type must be one of those supported by the screen.

     Initial color cell values are undefined for visual types belonging to the :GRAY-SCALE, :PSEUDO-COLOR, and :DIRECT-COLOR classes. Color cell values for visual types belonging to the :STATIC-GRAY, :STATIC-COLOR, and :TRUE-COLOR classes have initial values defined by the visual type. However, X does not define the set of possible visual types or their initial color cell values.

     If alloc-p is true, all colormap cells are permanently allocated read-write and cannot be freed by FREE-COLORS. It is an error for alloc-p to be true when the visual type belongs to the :STATIC-GRAY, :STATIC-COLOR, or :TRUE-COLOR classes.

     colormap
          Type COLORMAP.

 -- Function: copy-colormap-and-free colormap

     colormap
          A COLORMAP.

     Creates and returns a new COLORMAP by copying, then freeing, allocated cells from the specified colormap.

     All color cells allocated read-only or read-write in the original COLORMAP have the same color values and the same allocation status in the new-colormap. The values of unallocated color cells in the new-colormap are undefined. After copying, all allocated color cells in the original COLORMAP are freed, as if FREE-COLORS was called. The unallocated cells of the original COLORMAP are not affected.

     If alloc-p was true when the original COLORMAP was created, then all color cells of the new-colormap are permanently allocated read-write, and all the color cells of the original COLORMAP are freed.

     new-colormap
          Type COLORMAP.

 -- Function: free-colormap colormap

     colormap
          A COLORMAP.

     Destroys the colormap and frees its server resource. If the colormap is installed, it is uninstalled. For any window associated with the colormap, the window is assigned a NIL COLORMAP, and a :COLORMAP-NOTIFY event is generated. The colors displayed for a window with a NIL COLORMAP are undefined.

     However, this function has no effect if the colormap is a screen default COLORMAP.

Installing Colormaps
--------------------

The following paragraphs describe the CLX functions to install and uninstall colormaps and to return the set of installed colormaps.

Initially, the default COLORMAP for a screen is installed (but is not in the required list).

 -- Function: install-colormap colormap

     colormap
          A COLORMAP.

     Installs the colormap. All windows associated with this colormap immediately display with true colors. As a side-effect, additional colormaps might be implicitly uninstalled by the server.

     If the specified colormap is not already installed, a :COLORMAP-NOTIFY event is generated on every window associated with this colormap. In addition, for every other colormap that is implicitly uninstalled, a :COLORMAP-NOTIFY event is generated on every associated window.

 -- Function: installed-colormaps window &key (:result-type 'list)

     window
          A WINDOW.

     :result-type
          A sub-type of SEQUENCE that indicates the type of sequence to return.

     Returns a sequence containing the installed COLORMAPS for the screen of the specified window. The order of the colormaps is not significant.

     colormap
          Type SEQUENCE of COLORMAP.

 -- Function: uninstall-colormap colormap

     colormap
          A COLORMAP.

     Uninstalls the colormap. However, the colormap is not actually uninstalled if this would reduce the set of installed colormaps below the value of SCREEN-MIN-INSTALLED-MAPS. If the colormap is actually uninstalled, a :COLORMAP-NOTIFY event is generated on every associated window.

Allocating Colors
-----------------

The following paragraphs describe the functions for allocating read-only and read-write color cells, allocating color planes, and freeing color cells.

 -- Function: alloc-color colormap color

     colormap
          A COLORMAP.

     color
          A COLOR object or a STRINGABLE containing a color name.

     Returns a pixel for a read-only color cell in the colormap. The color in the allocated cell is the closest approximation to the requested color possible for the screen hardware. The other values returned give both the approximate color stored in the cell and the exact color requested.

     The requested color can be either a COLOR object or a STRINGABLE containing a color name.  If a color name is given, a corresponding color value is looked up (see LOOKUP-COLOR) and used. Color name strings must contain only ISO Latin-1 characters; case is not significant.

     pixel
          Type PIXEL.

     screen-color
     exact-color
          Type COLOR.

 -- Function: alloc-color-cells colormap colors &key (:planes 0) :contiguous-p (:result-type 'list)

     colormap
          A COLORMAP.

     colors
          A positive number defining the length of the pixels sequence returned.

     :planes
          A non-negative number defining the length of the masks sequence returned.

     :contiguous-p
          If true, the masks form contiguous sets of bits.

     :result-type
          A subtype of SEQUENCE that indicates the type of sequences returned.

     Returns a SEQUENCE of pixels for read-write color cells in the colormap. The allocated cells contain undefined color values. The visual type class of the COLORMAP must be either :GRAY-SCALE, :PSEUDO-COLOR, or :DIRECT-COLOR.

     The colors argument and the :PLANES argument define the number of pixels and the number of masks returned, respectively. The number of colors must be positive, and the number of planes must be non-negative. A total of (* colors (EXPT 2 planes)) color cells are allocated. The pixel values for the allocated cells can be computed by combining the returned pixels and masks.

     The length of the returned masks sequence is equal to :PLANES. Each mask of the returned masks sequence defines a single bitplane. None of the masks have any 1 bits in common. Thus, by selectively combining masks with LOGIOR, (EXPT 2 planes) distinct combined plane masks can be computed.

     The length of the returned pixels sequence is equal to colors. None of the pixels have any 1 bits in common with each other or with any of the returned masks. By combining pixels and plane masks with LOGIOR, (* colors (EXPT 2 planes)) distinct pixel values can be produced.

     If the colormap class is :GRAY-SCALE or :PSEUDO-COLOR, each mask will have exactly one bit set. If the COLORMAP class is :DIRECT-COLOR, each mask will have exactly three bits set.  If :CONTIGUOUS-P is true, combining all masks with LOGIOR produces a plane mask with either one set of contiguous bits (for :GRAY-SCALE and :PSEUDO-COLOR) or three sets of contiguous bits (for :DIRECT-COLOR).

     pixels
     mask
          Type SEQUENCE of PIXELS.

 -- Function: alloc-color-planes colormap colors &key (:reds 0) (:greens 0) (:blues 0) :contiguous-p (:result-type 'list)

     colormap
          A COLORMAP.

     colors
          A positive number defining the length of the pixels sequence returned.

     :planes
          A non-negative number defining the length of the masks sequence returned.

     :contiguous-p
          If true, then the masks form contiguous sets of bits.

     :result-type
          A subtype of SEQUENCE that indicates the type of sequences returned.

     Returns a SEQUENCE of pixels for read-write color cells in the colormap. The allocated cells contain undefined color values. The visual type class of the colormap must be either :GRAY-SCALE, :PSEUDO-COLOR, or :DIRECT-COLOR.

     The colors argument defines the number of pixels returned. The :REDS, :GREENS, and :BLUES arguments define the number of bits set in the returned red, green, and blue masks, respectively. The number of colors must be positive, and the number of bits for each mask must be non-negative. A total of (* colors (EXPT 2 (+ reds greens blues))) color cells are allocated. The pixel values for the allocated cells can be computed by combining the returned pixels and masks.

     Each mask of the returned masks defines a pixel subfield for the corresponding primary.  None of the masks have any 1 bits in common. By selectively combining subsets of the red, green, and blue masks with LOGIOR, (EXPT 2 (+ reds greens blues) distinct combined plane masks can be computed.

     The length of the returned pixels SEQUENCE is equal to colors. None of the pixels have any 1 bits in common with each other or with any of the returned masks. By combining pixels and plane masks with LOGIOR, (* colors (EXPT 2 (+ reds greens blues)) distinct pixel values can be produced.

     If :CONTIGUOUS-P is true, each of returned masks consists of a set of contiguous bits. If the COLORMAP class is :DIRECT-COLOR, each returned mask lies within the pixel subfield for its primary.

     pixels
          Type SEQUENCE of PIXEL.

     red-mask
     green-mask
     blue-mask
          Type PIXEL.

 -- Function: free-colors colormap pixels &optional (plane-mask 0)

     colormap
          A COLORMAP.

     pixels
          A SEQUENCE of pixel values.

     plane-mask
          A pixel value with no bits in common with any of the pixels.

     Frees a set of allocated color cells from the colormap. The pixel values for the freed cells are computed by combining the given pixels sequence and :PLANE-MASK. The total number of cells freed is:

          (* (LENGTH pixels) (EXPT 2 (LOGCOUNT plane-mask)))

     The :PLANE-MASK must not have any bits in common with any of the given pixels. The pixel values for the freed cells are produced by using LOGIOR to combine each of the given pixels with all subsets of the :PLANE-MASK.

     Note that freeing an individual pixel allocated by ALLOC-COLOR-PLANES may not allow it to be reused until all related pixels computed from the same plane mask are also freed.

     A single error is generated if any computed pixel is invalid or if its color cell is not allocated by the client. Even if an error is generated, all valid pixel values are freed.

Finding Colors
--------------

A CLX program can ask the X server to return the colors stored in allocated color cells. The server also maintains a dictionary of color names and their associated color values. CLX provides a function to look up the values for common colors by names such as "red", "purple", and so forth. The following paragraphs describe the CLX functions for returning the color values associated with color cells or with color names.

 -- Function: lookup-color colormap name

     colormap
          A COLORMAP.

     name
          A STRINGABLE color name.

     Returns the color associated by the X server with the given color name. The name must contain only ISO Latin-1 characters; case is not significant. The first value returned is the closest approximation to the requested color possible on the screen hardware. The second value returned is the true color value for the requested color.

     screen-color
     exact-color
          Type COLOR.

 -- Function: query-colors colormap pixels &key (:result-type 'list)

     colormap
          A COLORMAP.

     pixels
          A SEQUENCE of PIXEL values.

     :result-type
          A subtype of SEQUENCE that indicates the type of sequences returned.

     Returns a SEQUENCE of the colors contained in the allocated cells of the colormap specified by the given pixels. The values returned for unallocated cells are undefined.

     colors
          Type SEQUENCE of COLOR.

Changing Colors
---------------

The following paragraphs describe the CLX functions to change the colors in colormap cells.

 -- Function: store-color colormap pixel color &key (:red-p t) (:green-p t) (:blue-p t)

     colormap
          A COLORMAP.

     pixel
          A PIXEL.

     color
          A color OBJECT or a STRINGABLE containing a color name.

     :red-p
     :green-p
     :blue-p
          BOOLEAN values indicating which color components to store.

     Changes the contents of the colormap cell indexed by the pixel. Components of the given color are stored in the cell. The :RED-P, :GREEN-P, and :BLUE-P arguments indicate which components of the given color are stored.

     The color can be either a COLOR object or a STRINGABLE containing a color name. If a color name is given, a corresponding color value is looked up (see LOOKUP-COLOR) and used.  Color name strings must contain only ISO Latin-1 characters; case is not significant.

 -- Function: store-colors colormap pixel-colors &key (:red-p t) (:green-p t) (:blue-p t)

     colormap
          A COLORMAP.

     pixel-colors
          A list of the form ({pixel color}*).

     :red-p
     :green-p
     :blue-p
          BOOLEAN values indicating which color components to store.

     Changes the contents of multiple colormap cells. pixel-colors is a list of the form ({ pixel color}*), indicating a set of pixel values and the colors to store in the corresponding cells. The :RED-P, :GREEN-P, and :BLUE-P arguments indicate which components of the given colors are stored.

     Each color can be either a COLOR object or a STRINGABLE containing a color name. If a color name is given, a corresponding color value is looked up (see LOOKUP-COLOR) and used.  Color name strings must contain only ISO Latin-1 characters; case is not significant.

Colormap Attributes
-------------------

The complete set of colormap attributes is discussed in the following paragraphs.

 -- Function: colormap-display colormap

     colormap
          A COLORMAP.

     Returns the DISPLAY object associated with the specified colormap.

     display
          Type DISPLAY.

 -- Function: colormap-equal colormap-1 colormap-2

     colormap-1
     colormap-2
          A COLORMAP.

     Returns true if the two arguments refer to the same server resource and NIL if they do not.

 -- Function: colormap-id colormap

     colormap
          A COLORMAP.

     Returns the unique ID assigned to the specified colormap.

     id
          Type RESOURCE-ID.

 -- Function: colormap-p colormap

     Returns non-NIL if the argument is a COLORMAP and NIL otherwise.

     map-p
          Type BOOLEAN.

 -- Function: colormap-plist colormap

     colormap
          A COLORMAP.

     Returns and (with setf) sets the property list for the specified colormap. This function provides a hook where extensions can add data.

     colormap-p
          Type BOOLEAN.

Cursors
*******

A cursor is a visible shape that appears at the current position of the pointer device. The cursor shape moves with the pointer to provide continuous feedback to the user about the current location of the pointer. Each window can have a cursor attribute that defines the appearance of the pointer cursor when the pointer position lies within the window. See WINDOW-CURSOR.

A cursor image is composed of a source bitmap, a mask bitmap, a hot spot, a foreground color, and a background color. Either 1-bit pixmaps or font glyphs can be used to specify source and mask bitmaps. The source bitmap identifies the foreground and background pixels of the cursor image; the mask bitmap identifies which source pixels are actually drawn. The mask bitmap thus allows a cursor to assume any shape. The hot spot defines the position within the cursor image that is displayed at the pointer position.

In CLX, a cursor is represented by a CURSOR object. This section describes the CLX functions to:

  * Create and free cursor objects

  * Change cursor colors

  * Inquire the best cursor size

  * Access cursor attributes

Creating Cursors
================

The following paragraphs describe the CLX functions used to create and free CURSOR objects.

 -- Function: create-cursor &key :source :mask :x :y :foreground :background

     :source
          The source pixmap. This argument is required.

     :mask
          The mask pixmap.

     :x
     :y
          The hot spot position in the :SOURCE. This argument is required.

     :foreground
          A COLOR object specifying the foreground color. This argument is required.

     :background
          A COLOR object specifying the background color. This argument is required.

     Creates and returns a cursor. :X and :Y define the position of the hot spot relative to the origin of the :SOURCE. :FOREGROUND and :BACKGROUND colors must be specified, even if the server only has a :STATIC-GRAY or :GRAY-SCALE screen. The :SOURCE, :X, and :Y arguments must also be specified.

     The cursor image is drawn by drawing a pixel from the :SOURCE bitmap at every position where the corresponding bit in the :MASK bitmap is 1. If the corresponding :SOURCE bit is 1, a pixel is drawn in the :FOREGROUND color; otherwise, a pixel is drawn in the :BACK-GROUND color. If the :MASK is omitted, all :SOURCE pixels are drawn. If given, the :MASK must be the same size as the :SOURCE.

     An X server may not be able to support every cursor size. A server is free to modify any component of the cursor to satisfy hardware or software limitations.

     The :SOURCE and :MASK can be freed immediately after the cursor is created. Subsequent drawing in the :SOURCE or :MASK pixmap has an undefined effect on the cursor.

     cursor
          Type CURSOR.

 -- Function: create-glyph-cursor &key :source-font :source-char :mask-font (:mask-char 0) :foreground :background

     :source-font
          The source font. This is a required argument.

     :source-char
          An index specifying a glyph in the source font. This is a required argument.

     :mask-font
          The mask font.

     :mask-char
          An index specifying a glyph in the mask font.

     :foreground
          A COLOR object specifying the foreground color. This is a required argument.

     :background
          A COLOR object specifying the background color. This is a required argument.

     Creates and returns a cursor defined by font glyphs. The source bitmap is defined by the :SOURCE-FONT and :SOURCE-CHAR. The mask bitmap is defined by the :MASK-FONT and :MASK-CHAR. It is an error if the :SOURCE-CHAR and :MASK-CHAR are not valid indexes for the :SOURCE-FONT and :MASK-FONT, respectively. The hot spot position is defined by the "character origin" of the source glyph, that is, the position [- char-left-bearing, char-ascent] relative to the upper left corner of the source glyph bitmap.

     Source and mask bits are compared after aligning the character origins of the source and mask glyphs. The source and mask glyphs need not have the same size or character origin position. If the :MASK-FONT is omitted, all source pixels are drawn.

     An X server may not be able to support every cursor size. A server is free to modify any component of the cursor to satisfy hardware or software limitations.

     Either of the :SOURCE-FONT or :MASK-FONT can be closed after the cursor is created.

     cursor
          Type CURSOR.

 -- Function: free-cursor cursor

     cursor
          A CURSOR object.

     Destroys the CURSOR object. Cursor server resources are freed when no other references remain.

Cursor Functions
================

The following paragraphs describe the CLX functions used to operate on CURSOR objects.

 -- Function: query-best-cursor width height display

     display
          A DISPLAY object.

     width
     height
          The requested cursor size.

     Returns the cursor size closest to the requested width and height that is best suited to the display. The width and height returned define the largest cursor size supported by the X server. Clients should always be prepared to limit cursor sizes to those supported by the server.

     width
     height
          Type CARD16.

 -- Function: recolor-cursor cursor foreground background

     cursor
          A CURSOR object.

     foreground
          A COLOR object specifying the new foreground color.

     background
          A COLOR object specifying the new background color.

     Changes the color of the specified cursor. If the cursor is displayed on a screen, the change is visible immediately.

Cursor Attributes
=================

The complete set of cursor attributes is discussed in the following paragraphs.

 -- Function: cursor-display cursor

     cursor
          A CURSOR object.

     Returns the DISPLAY object associated with the specified cursor.

     display
          Type DISPLAY.

 -- Function: cursor-equal cursor-1 cursor-2

     cursor-1
     cursor-2
          CURSOR objects.

     Returns true if the two arguments refer to the same server resource and NIL if they do not.

 -- Function: cursor-id cursor

     cursor
          A CURSOR object.

     Returns the unique resource ID that has been assigned to the specified cursor.

     id
          Type RESOURCE-ID.

 -- Function: cursor-p cursor

     cursor-p
          Type BOOLEAN.

     Returns true if the argument is a CURSOR object and NIL otherwise.

 -- Function: cursor-plist cursor

     cursor
          A CURSOR object.

     Returns and (with setf) sets the property list for the specified cursor. This function provides a hook where extensions can add data.

     plist
          A property list.

Atoms, Properties and Selections
********************************

Atoms
=====

In X, an atom is a unique ID used as the name for certain server resources -- properties and selections.

In CLX, an atom is represented by a keyword symbol. For convenience, CLX functions also allow atoms to be specified by strings and non-keyword symbols. XATOM is a CLX data type that permits either string or symbol values. A string is equivalent to the XATOM given by (INTERN string 'KEYWORD). A symbol is equivalent to the XATOM given by ( INTERN (SYMBOL-NAME symbol) 'KEYWORD). The symbol name string of an XATOM must consist only of ISO Latin characters. Note that the case of XATOM strings is important; the XATOM "Atom" is not the same as the XATOM "ATOM".

Certain atoms are already predefined by every X server. Predefined atoms are designed to represent common names that are likely to be useful for many client applications.  Note that these atoms are predefined only in the sense of having XATOM and CARD29 values, not in the sense of having required semantics. No interpretation is placed on the meaning or use of an atom by the server. The XATOM objects predefined by CLX are listed below.

:ARC   :ITALIC_ANGLE   :STRING
:ATOM   :MAX_SPACE   :SUBSCRIPT_X
:BITMAP   :MIN_SPACE   :SUBSCRIPT_Y
:CAP_HEIGHT   :NORM_SPACE   :SUPERSCRIPT_X
:CARDINAL   :NOTICE   :SUPERSCRIPT_Y
:COLORMAP   :PIXMAP   :UNDERLINE_POSITION
:COPYRIGHT   :POINT   :UNDERLINE_THICKNESS
:CURSOR   :POINT_SIZE   :VISUALID
:CUT_BUFFER0   :PRIMARY   :WEIGHT
:CUT_BUFFER1   :QUAD_WIDTH   :WINDOW
:CUT_BUFFER2   :RECTANGLE   :WM_CLASS
:CUT_BUFFER3   :RESOLUTION   :WM_CLIENT_MACHINE
:CUT_BUFFER4   :RESOURCE_MANAGER   :WM_COMMAND
:CUT_BUFFER5   :RGB_BEST_MAP   :WM_HINTS
:CUT_BUFFER6   :RGB_BLUE_MAP   :WM_ICON_NAME
:CUT_BUFFER7   :RGB_COLOR_MAP  :WM_ICON_SIZE
:DRAWABLE   :RGB_DEFAULT_MAP   :WM_NAME
:END_SPACE   :RGB_GRAY_MAP   :WM_NORMAL_HINTS
:FAMILY_NAME   :RGB_GREEN_MAP  :WM_SIZE_HINTS
:FONT   :RGB_RED_MAP   :WM_TRANSIENT_FOR
:FONT_NAME   :SECONDARY   :WM_ZOOM_HINTS
:FULL_NAME   :STRIKEOUT_ASCENT   :X_HEIGHT
:INTEGER   :STRIKEOUT_DESCENT

When creating a new atom, the following conventions should be obeyed in order to minimize the conflict between atom names:

  * Symbol names beginning with an underscore should be used for atoms that are private to a particular vendor or organization. An additional prefix should identify the organization.

  * Symbol names beginning with two underscores should be used for atoms that are private to a single application or end user.

CLX provides functions to convert between an XATOM and its corresponding ID integer.  The data type of an atom ID is CARD29. The XATOM representation is usually sufficient for most CLX programs. However, it is occasionally useful to be able to convert an atom ID returned in events or properties into its corresponding XATOM.

 -- Function: atom-name display atom-id

     display
          A DISPLAY object.

     atom-id
          A CARD29.

     Returns the atom keyword for the atom-id on the given display server.

     atom-name
          Type KEYWORD.

 -- Function: find-atom display atom-name

     display
          A DISPLAY object.

     atom-name
          An XATOM.

     Returns the atom ID for the given atom-name, if it exists. If no atom of that name exists for the display server, NIL is returned.

     atom-id
          Type CARD29 or NULL.

 -- Function: intern-atom display atom-name

     display
          A DISPLAY object.

     atom-name
          An XATOM.

     Creates an atom with the given name and returns its atom ID. The atom can survive the interning client; it exists until the last server connection has been closed and the server resets itself.

     atom-id
          Type CARD29 or NULL.

Properties
==========

For each window, an X server can record a set of properties. Properties are a general mechanism for clients to associate arbitrary data with a window, and for clients to communicate window data to each other via the server. No interpretation is placed on property data by the server itself.

A property consists of a name, a type, a data format, and data. The name of a property is given by an atom. The property type is another atom used to denote the intended interpretation of the property data. The property formats specifies whether the property data should be treated as a set of 8-, 16-, or 32-bit elements. The property format must be specified so that the X server can communicate property data with the correct byte order.

CLX provides functions to:

  * Create or change a property

  * Return property data

  * List window properties

  * Delete a property

 -- Function: change-property window property data type format &key (:mode :replace) (:start 0) :end :transform

     window
          A WINDOW.

     property
          A property name XATOM.

     data
          A sequence of property data elements.

     type
          The property type XATOM.

     format
          One of 8, 16, or 32.

     :mode
          One of :REPLACE, :APPEND, or :PREPEND.

     :start
     :end
          Specify the subsequence of previous data replaced when :MODE is :REPLACE.

     :transform
          A function that transforms each data element into a data value to store.

     Creates a new window property or changes an existing property. A :PROPERTY-NOTIFY event is generated for the window.

     If the :MODE is :REPLACE, the new data, type, and format replace any previous values.  The subsequence of previous data elements that are replaced is defined by the :START and :END indexes.

     If the :MODE is :PREPEND or :APPEND, no previous data is changed, but the new data is added at the beginning or the end, respectively. For these modes, if the property already exists, the new type and format must match the previous values.

     The :TRANSFORM, if given, is a function used to compute the actual property data stored.  The :TRANSFORM, which must accept a single data element and return a single transformed data element, is called for each data element. If the data is a string, the default :TRANSFORM function transforms each character into its ASCII code; otherwise, the default is to store the data unchanged.

 -- Function: delete-property window property

     window
          A WINDOW.

     property
          A property name XATOM.

     Deletes the window property. If the property already exists, a :PROPERTY-NOTIFY event is generated for the window.

 -- Function: get-property window property &key :type (:start 0) :end :delete-p (:result-type 'list) :transform

     window
          A WINDOW.

     property
          A property name XATOM.

     :type
          The requested type XATOM or NIL.

     :start
     :end
          Specify the subsequence of property data returned.

     :transform
          A function that transforms each data element into a data value to return.

     :delete-p
          If true, the existing property can be deleted.

     :result-type
          The type of data sequence to return. Default is 'LIST.

     Returns a subsequence of the data for the window property. The :START and :END indexes specify the property data elements returned. The :TRANSFORM function is called for elements of the specified subsequence to compute the data sequence returned. The property type and format are also returned. The final return value gives the actual number of data bytes (not elements) following the last data element returned.

     If the property does not exist, the returned data and type are NIL and the returned format and bytes-after are zero.

     If the given :TYPE is non-NIL but does not match the actual property type, then the data returned is NIL, the type and format returned give the actual property values, and the bytes-after returned gives the total number of bytes (not elements) in the property data.

     If the given :TYPE is NIL or if it matches the actual property type, then:

       * The data returned is the transformed subsequence of the property data.

       * The type and format returned give the actual property values.

       * The bytes-after returned gives the actual number of data bytes (not elements) following the last data element returned.

     In this case, the :DELETE-P argument is also examined. If :DELETE-P is true and bytes-after is zero, the property is deleted and a :PROPERTY-NOTIFY event is generated for the window.

     data
          Type SEQUENCE.

     type
          Type XATOM.

     format
          Type (MEMBER 8 16 32).

     bytes-after
          Type CARD32.

 -- Function: list-properties window &key (:result-type 'list)

     window
          A WINDOW.

     :result-type
          The type of sequence to return. Default is 'LIST.

     Returns a sequence containing the names of all window properties.

     properties
          Type SEQUENCE of KEYWORD.

 -- Function: rotate-properties window properties &optional (delta 1)

     window
          A WINDOW.

     properties
          A sequence of XATOM values.

     delta
          The index interval between source and destination elements of properties.

     Rotates the values of the given window properties. The value of property i in the given sequence is changed to the value of the property at index (MOD (+ i delta) (LENGTH properties)). This function operates much like the ROTATEF macro in Common Lisp.

     If (MOD delta (LENGTH properties)) is non-zero, a :PROPERTY-NOTIFY event is generated on the window for each property, in the same order as they appear in the properties sequence.

Selections
==========

A selection is an atom used to identify data that can be shared among all client programs connected to an X server. Unlike properties, the data represented by a selection is stored by some client program, not by the server.

The data named by a selection is associated with a client window, which is referred to as the selection owner. The server always knows which window is the owner of a selection.  Selections can be created freely by clients using INTERN-ATOM to create an atom. CLX provides functions to inquire or change the owner of a selection and to convert a selection.

Conversion is the key to the use of selections for inter-client communication. Suppose Client A wants to paste the contents of the data named by selection S into his window WA. Client A calls CONVERT-SELECTION on selection atom S, sending a conversion request to the server. The server, in turn, sends a :SELECTION-REQUEST event to the current owner of S, which is window WB belonging to Client B. The :SELECTION-REQUEST event contains the requestor window (WA), the selection atom (S), an atom identifying a requested data type, and the name of a property of WA into which the value of S will be stored.

Since WB is the owner of S, it must be associated with the data defined by Client B as the value of S. When WB gets the :SELECTION-REQUEST event, Client B is expected to convert the value of S to the requested data type (if possible) and store the converted value in the given requestor property. Client B is then expected to send a :SELECTION-NOTIFY event to the requestor window WA, informing the requestor that the converted value for S is ready. Upon receiving the :SELECTION-NOTIFY event, Client A can call GET-PROPERTY to retrieve the converted value and to paste it into WA.

NOTE: Clients using selections must always be prepared to handle :SELECTION-REQUEST events and/or :SELECTION-NOTIFY events. There is no way for a client to ask not to receive these types of events.

Type atoms used in selection conversion can represent arbitrary client-defined interpretations of the selection data. For example, if the value of selection S is a text string, Client A might request its typeface by requesting conversion to the :FONT type. A type ATOM can also represent a request to the selection owner to perform some action as a side-effect of conversion (for example, :DELETE). Some of the predefined atoms of an X server are intended to be used as selection types (for example, :COLORMAP, :BITMAP, :STRING, and so forth) However, X does not impose any requirements on the interpretation of type atoms.

When multiple clients negotiate for ownership of a selection, certain race conditions might be possible. For example, two clients might each receive a user command to assert ownership of the :PRIMARY selection, but the order in which the server processes these client requests is unpredictable. As a result, the ownership request initiated most recently by the user might be incorrectly overridden by the other earlier ownership request. To prevent such anomalies, the server records a last-changed timestamp for each change of selection ownership.

Although inter-client communication via selections is rather complex, it offers important benefits. Since selection communication is mediated by an X server, clients can share data even though they are running on different hosts and using different networking protocols. Data storage and conversion is distributed among clients so that the server is not required to provide all possible data types or to store multiple forms of selection data.

Certain predefined atoms are used as standard selections, as described in the X11 Inter-client Communications Conventions Manual. Some of the standard selections covered by these conventions are:

:primary
     The primary selection. The main vehicle for inter-client cut and paste operations.

:secondary
     The secondary selection. In some environments, clients can use this as an auxiliary to :PRIMARY.

:clipboard
     Analogous to akill ring. Represents the most recently deleted data item.

 -- Function: convert-selection selection type requestor &optional property time

     selection
          The XATOM for the selection name.

     type
          The XATOM for the requested data type.

     requestor
          The WINDOW to receive the converted selection value.

     property
          The XATOM for the requestor property to receive the converted value.

     time
          A TIMESTAMP.

     Requests that the value of the selection be converted to the specified type and stored in the given property of the requestor window.

     If the selection has an owner, the X server sends a :SELECTION-REQUEST event to the owner window. Otherwise, if no owner exists, the server generates on the requestor a :SELECTION-NOTIFY event containing a NIL property atom.

     The given property specifies the requestor property that will receive the converted value. If the property is omitted, the selection owner will define a property to use. The time furnishes a timestamp representing the time of the conversion request; by default, the current server time is used.

     NOTE: Standard conventions for inter-client communication require that both the requestor property and the time must be specified. If possible, the time should be the time of a user event which initiated the conversion. Alternatively, a timestamp can be obtained by calling CHANGE-PROPERTY to append zero-length data to some property; the timestamp in the resulting :PROPERTY-NOTIFY event can then be used.

 -- Function: selection-owner display selection &optional time

     display
          A DISPLAY.

     selection
          The XATOM for the selection name.

     time
          A TIMESTAMP.

     Returns and (with setf) changes the owner and the last-changed time for the selection. If the owner is NIL, no owner for the selection exists. When the owner window for a selection is destroyed, the selection owner is set to NIL without affecting the last-changed time.

     The time argument is used only when changing the selection owner. If the time is NIL, the current server time is used. If the time is earlier than the current last-changed time of the selection or if the time is later than the current server time, the owner is not changed. Therefore, a client should always confirm successful change of ownership by immediately calling SELECTION-OWNER. If the change in ownership is successful, the last-changed time of the selection is set to the specified time.

     If the change in ownership is successful and the new owner is different from the previous owner, and if the previous owner is not NIL, a :SELECTION-CLEAR event is generated for the previous owner window.

     NOTE: Standard conventions for inter-client communication require that a non-nil time must be specified. If possible, the time should be the time of a user event which initiated the change of ownership. Alternatively, a timestamp can be obtained by calling change-property to append zero-length data to some property; the timestamp in the resulting :PROPERTY-NOTIFY event can then be used.

     owner
          Type WINDOW or NULL.

Events and Input
****************

A client application uses CLX functions to send requests to an X server over a display connection returned by the OPEN-DISPLAY function. In return, the X server sends back replies and events. Replies are synchronized with specific requests and return requested server information. Events typically occur asynchronously. Device events are generated by user input from both the keyboard and pointer devices. Other events are side-effects of the requests sent by CLX functions. The types of events returned by an X server are summarized below.

Device Events

Keyboard
     :KEY-PRESS :KEY-RELEASE

Pointer
     :BUTTON-PRESS :BUTTON-RELEASE :ENTER-NOTIFY :LEAVE-NOTIFY :MOTION-NOTIFY

Side-Effect Events

Client communication
     :CLIENT-MESSAGE :PROPERTY-NOTIFY :SELECTION-CLEAR :SELECTION-NOTIFY :SELECTION-REQUEST

Color map state
     :COLORMAP-NOTIFY

Exposure
     :EXPOSURE :GRAPHICS-EXPOSURE :NO-EXPOSURE

Input focus
     :FOCUS-IN :FOCUS-OUT

Keyboard and pointer state
     :KEYMAP-NOTIFY :MAPPING-NOTIFY

Structure control
     :CIRCULATE-REQUEST :CONFIGURE-REQUEST :MAP-REQUEST

Window state
     :RESIZE-REQUEST :CIRCULATE-NOTIFY :CONFIGURE-NOTIFY :CREATE-NOTIFY :DESTROY-NOTIFY :GRAVITY-NOTIFY :MAP-NOTIFY :REPARENT-NOTIFY :UNMAP-NOTIFY :VISIBILITY-NOTIFY

Client programs can override the server's normal distribution of events by grabbing the pointer or the keyboard. Grabbing causes events from the pointer or keyboard device to be reported to a single specified window, rather than to their ordinary destinations. It can also cause the server to freeze the grabbed device, sending queued events only when explicitly requested by the grabbing client. Two kinds of grabs are possible:

  * Active -- Events are immediately grabbed.

  * Passive -- Events are grabbed later, as soon as a specified device event occurs.

Grabbing an input device is performed rarely and usually only by special clients, such as window managers.

This section describes the CLX functions used to:

  * Select events (see Selecting Events)

  * Process an event on the event queue (see Processing Events)

  * Manage the event queue (see Managing the Event Queue)

  * Send events to other applications (see Sending Events)

  * Read and change the pointer position (see Pointer Position)

  * Manage the keyboard input focus (see Managing Input Focus)

  * Grab pointer and keyboard events (see Grabbing the Pointer)

  * Release queued events (see Releasing Queued Events)

This section also contains a detailed description of the content of each type of event.

Selecting Events
================

A client selects which types of events it receives from a specific window. The window event-mask attribute, set by the client, determines which event types are selected (see WINDOW-EVENT-MASK in Window Attributes). Most types of events are received by a client only if they are selected for some window.

In the X protocol, an event-mask is represented as a bit string. CLX also allows an event mask to be defined by a list of EVENT-MASK-CLASS keywords. The functions MAKE-EVENT-KEYS and MAKE-EVENT-MASK can be used to convert between these two forms of an event-mask. In general, including an EVENT-MASK-CLASS keyword in an event-mask causes one or more related event types to be selected. The following table describes the event types selected by each EVENT-MASK-CLASS keyword.

Event Mask Keyword   Event Types Selected
:BUTTON-1-MOTION
:MOTION-NOTIFY when :BUTTON-1 is down
:BUTTON-2-MOTION
:MOTION-NOTIFY when :BUTTON-2 is down
:BUTTON-3-MOTION
:MOTION-NOTIFY when :BUTTON-3 is down
:BUTTON-4-MOTION
:MOTION-NOTIFY when :BUTTON-4 is down
:BUTTON-5-MOTION
:MOTION-NOTIFY when :BUTTON-5 is down
:BUTTON-MOTION
:MOTION-NOTIFY when any pointer button is down
:BUTTON-PRESS
:BUTTON-PRESS
:BUTTON-RELEASE
:BUTTON-RELEASE
:COLORMAP-CHANGE
:COLORMAP-NOTIFY
:ENTER-WINDOW
:ENTER-NOTIFY
:EXPOSURE
:EXPOSURE
:FOCUS-CHANGE
:FOCUS-IN :FOCUS-OUT
:KEY-PRESS
:KEY-PRESS
:KEY-RELEASE
:KEY-RELEASE
:KEYMAP-STATE
:KEYMAP-NOTIFY
:LEAVE-WINDOW
:LEAVE-NOTIFY
:OWNER-GRAB-BUTTON
Pointer events while button is grabbed
:POINTER-MOTION
:MOTION-NOTIFY
:POINTER-MOTION-HINT
Single :MOTION-NOTIFY only
:PROPERTY-CHANGE
:PROPERTY-NOTIFY
:RESIZE-REDIRECT
:RESIZE-REQUEST
:STRUCTURE-NOTIFY
:CIRCULATE-NOTIFY :CONFIGURE-NOTIFY :DESTROY-NOTIFY :GRAVITY-NOTIFY :MAP-NOTIFY :REPARENT-NOTIFY :UNMAP-NOTIFY
:SUBSTRUCTURE-REDIRECT
:CIRCULATE-REQUEST :CONFIGURE-REQUEST :MAP-REQUEST
:VISIBILITY-CHANGE
:VISIBILITY-NOTIFY

Some types of events do not have to be selected to be received and therefore are not represented in an event-mask. For example, the COPY-PLANE and COPY-AREA functions cause :GRAPHICS-EXPOSURE and :NO-EXPOSURE events to be reported, unless exposures are turned :OFF in the graphics context (see COPY-AREA and COPY-PLANE in Area and Plane Operations, and GCONTEXT-EXPOSURES in paragraph 5.4.6, Exposures).  Also, :SELECTION-CLEAR, :SELECTION-REQUEST, :SELECTION-NOTIFY and :CLIENT-MESSAGE events can be received at any time, but they are generally sent only to clients using selections (see Client Communications Events). :MAPPING-NOTIFY is always sent to clients when the keyboard mapping is changed.

Any client can select events for any window. A window maintains a separate event-mask for each interested client. In general, multiple clients can select for the same events on a window. After the X server generates an event, it sends it to all clients which selected it. However, the following restrictions apply to sharing window events among multiple clients. For a given window:

  * Only one client at a time can include :SUBSTRUCTURE-REDIRECT in its event-mask

  * Only one client at a time can can include :BUTTON-PRESS in its event-mask

  * Only one client at a time can include :RESIZE-REDIRECT in its event-mask

Processing Events
=================

Events received by a CLX client are stored in an event queue until they are read and processed. Events are processed by handler functions.

 -- Function: handler-function &rest event-slots &key :display :event-key :send-event-p &allow-other-keys

     :display
          A DISPLAY for the connection that returned the event.

     :event-key
          An EVENT-KEY keyword specifying the event type.

     :send-event-p
          If true, the event was sent from another application using the SEND-EVENT function.

     The arguments to a handler function are keyword-value pairs that describe the contents of an event. The actual event-slots passed depend on the event type, except that :DISPLAY, :EVENT-KEY, and :SEND-EVENT-P are given for all event types. The keyword symbols used for each event type are event slot names defined by the DECLARE-EVENT macro and are described in Declaring Event Types.

     If a handler returns non-NIL, the event is considered processed and can be removed from the event queue. Otherwise, if a handler function returns NIL, the event can remain in the event queue for later processing.

     handled-p
          Type BOOLEAN.

 -- Function: process-event display &key :handler :timeout :peek-p :discard-p (:force-output-p t)

     display
          A DISPLAY.

     :handler
          A handler function or a sequence of handler functions.

     :timeout
          Specifies the timeout delay in seconds.

     :peek-p
          If NIL, events are removed from the event queue after processing.

     :discard-p
          If true, unprocessed events are discarded.

     :force-output-p
          If true, buffered output requests are sent.

     Invokes :HANDLER on each queued event until :HANDLER returns non-NIL. Then, the non-NIL :HANDLER value is returned by PROCESS-EVENT. If :HANDLER returns NIL for each event in the event queue, PROCESS-EVENT waits for another event to arrive. If timeout is non-NIL and no event arrives within the specified timeout interval (given in seconds), PROCESS-EVENT returns NIL; if timeout is NIL, PROCESS-EVENT will not return until :HANDLER returns non-NIL. PROCESS-EVENT may wait only once on network data, and therefore timeout prematurely.

     If :FORCE-OUTPUT-P is true, PROCESS-EVENT first invokes DISPLAY-FORCE-OUTPUT to send any buffered requests. If :PEEK-P is true, a processed event is not removed from the queue. If :DISCARD-P is true, unprocessed events are removed from the queue; otherwise, unprocessed events are left in place.

     If :HANDLER is a sequence, it is expected to contain handler functions for each event type.  The sequence index of the handler function for a particular event type is given by ( POSITION EVENT-KEY *EVENT-KEY-VECTOR*).

     handled-p
          Type BOOLEAN.

 -- Macro: event-case display &key :timeout :peek-p :discard-p (:force-output-p t) &body clauses

     display
          A DISPLAY.

     :handler
          A handler function or a sequence of handler functions.

     :timeout
          Specifies the timeout delay, in seconds.

     :peek-p
          If NIL, events are removed from the event queue after processing.

     :discard-p
          If true, unprocessed events are discarded.

     :force-output-p
          If true, buffered output requests are sent.

     clauses
          Code to process specified event types.

     Executes the matching clause for each queued event until a clause returns non-NIL. The non-NIL clause value is then returned. Each of the clauses is a list of the form (event-match [event-slots] &rest forms), where:

       * event-match -- Either an EVENT-KEY, a list of EVENT-KEYS, otherwise, or T. It is an error for the same key to appear in more than one clause.

       * event-slots -- If given, a list of (non-keyword) event slot symbols defined for the specified event type(s). See Declaring Event Types.

       * forms -- A list of forms that process the specified event type(s). The value of the last form is the value returned by the clause.

     A clause matches an event if the EVENT-KEY is equal to or a member of the event-match, or if the event-match is T or OTHERWISE. If no T or OTHERWISE clause appears, it is equivalent to having a final clause that returns NIL. If event-slots is given, these symbols are bound to the value of the corresponding event slot in the clause forms. Each element of event-slots can also be a list of the form (event-slot-keyword variable), in which case the variable symbol is bound to the value of the event slot specified by the event-slot-keyword.

     If every clause returns NIL for each event in the event queue, EVENT-CASE waits for another event to arrive. If :TIMEOUT is non-NIL and no event arrives within the specified timeout interval (given in seconds), EVENT-CASE returns NIL; if :TIMEOUT is NIL, EVENT-CASE will not return until a clause returns non-NIL. EVENT-CASE may wait only once on network data and therefore timeout prematurely.

     If :FORCE-OUTPUT-P is true, EVENT-CASE first invokes DISPLAY-FORCE-OUTPUT to send any buffered requests. If :PEEK-P is true, a processed event is not removed from the queue. If :DISCARD-P is true, unprocessed events are removed from the queue; otherwise, unprocessed events are left in place.

     handled-p
          Type BOOLEAN.

 -- Macro: event-cond display &key :timeout :peek-p :discard-p (:force-output-p t) &body clauses

     handled-p
          Type BOOLEAN.

     Similar to EVENT-CASE except that each of the clauses is a list of the form (event-match [event-slots] test-form &rest forms). Executes the test-form of the clause that matches each queued event until a test-form returns non-NIL. The body forms of the clause are then executed. The values returned by the last clause body form are then returned by EVENT-COND.

     When a test-form returns true and :PEEK-P is NIL, or when a test-form returns NIL and :DISCARD-P is true, the matching event is removed from the event queue before the body forms are executed.

     display
          A DISPLAY.

     :handler
          A handler function or a sequence of handler functions.

     :timeout
          Specifies the timeout delay in seconds.

     :peek-p
          If NIL, events are removed from the event queue after processing.

     :discard-p
          If true, unprocessed events are discarded.

     :force-output-p
          If true, buffered output requests are sent.

     clauses
          Code to process specified event types.

Managing the Event Queue
========================

The following paragraphs describe CLX functions and macros used to:

  * Put a new event on the event queue

  * Discard the current event

  * Return the current length of the event queue

  * Gain exclusive access to the event queue for a client process

 -- Function: queue-event display event-key &rest event-slots &key :append-p &allow-other-keys

     display
          A DISPLAY.

     event-key
          Specifies the type of event placed in the queue.

     event-slots
          Keyword-value pairs that describe the contents of an event.

     :append-p
          If true, the event is placed at the tail of the queue; otherwise, the event is placed at the head of the queue.

     Places an event of the type given by event-key into the event queue. When :APPEND-P is true, the event is placed at the tail of the queue; otherwise, the event is placed at the head of the queue. The actual event-slots passed depend on the event type. The keyword symbols used for each event type are event slot names defined by the DECLARE-EVENT macro and are described in Declaring Event Types.

 -- Function: discard-current-event display

     display
          A DISPLAY.

     Discards the current event for the display. Returns NIL when the event queue is empty; otherwise, returns T. This function provides extra flexibility for discarding events, but it should be used carefully; use EVENT-COND instead, if possible. Typically, DISCARD-CURRENT-EVENT is called inside a handler function or a clause of an EVENT-CASE form and is followed by another call to PROCESS-EVENT, EVENT-CASE, or EVENT-COND.

     discarded-p
          Type BOOLEAN.

 -- Function: event-listen display &optional (timeout 0)

     display
          A DISPLAY.

     timeout
          The number of seconds to wait for events.

     Returns the number of events queued locally. If the event queue is empty, EVENT-LISTEN waits for an event to arrive. If timeout is non-NIL and no event arrives within the specified timeout interval (given in seconds), EVENT-LISTEN returns NIL; if timeout is NIL, EVENT-LISTEN will not return until an event arrives.

     event-count
          Type (or null integer).

 -- Macro: with-event-queue display &body body

     display
          A DISPLAY.

     body
          Forms to execute.

     Executes the body in a critical region in which the executing client process has exclusive access to the event queue.

Sending Events
==============

A client can send an event to a window. Clients selecting this window event will receive it just like any other event sent by the X server.

 -- Function: send-event window event-key event-mask &rest event-slots &key :propagate-p :display &allow-other-keys

     window
          The destination WINDOW for the event.

     event-key
          An EVENT-KEY defining the type of event to send.

     event-mask
          Specifies the event types that receiving clients must select.

     event-slots
          Keyword-value pairs that describe the contents of an event.

     :propagate-p
          If true, the event can be propagated to ancestors of the destination window.

     :display
          A DISPLAY.

     Sends an event specified by the event-key and event-slots to the given destination window. Any active grabs are ignored. The event-slots passed depend on the event type. The keyword symbols used for each event type are event slot names defined by the DECLARE-EVENT macro and are described in Declaring Event Types.

     If the window is :POINTER-WINDOW, the destination window is replaced with the window containing the pointer. If the window is :INPUT-FOCUS, the destination window is replaced with the descendant of the focus window that contains the pointer or (if no such descendant exists) the focus window. The :DISPLAY keyword is only required if the window is :POINTER-WINDOW or :INPUT-FOCUS.

     The event-key must be one of the core events, or one of the events defined by an extension, so the server can send the event with the correct byte-order. The contents of the event are otherwise unaltered and unchecked by the server, except that the SEND-EVENT-P event slot is set to true.

     If the event-mask is NIL, the event is sent to the client that created the destination window with an event-mask of 0; if that client no longer exists, no event is sent. Otherwise, the event is sent to every client selecting any of the event types specified by event-mask on the destination window.

     If :PROPAGATE-P is true and no clients have selected any of the event types in event-mask on the destination window, the destination is replaced with the closest ancestor of window for which some client has selected a type in event-mask and no intervening window has that type in its do-not-propagate mask. If no such window exists, or if the window is an ancestor of the focus window and :INPUT-FOCUS was originally specified as the destination, the event is not sent to any clients. Otherwise, the event is reported to every client selecting on the final destination any of the types specified in event-mask.

Pointer Position
================

The CLX functions affecting pointer position are discussed in the following paragraphs.

 -- Function: query-pointer window

     window
          A WINDOW specifying the coordinate system for the returned position.

     Returns the current pointer coordinates relative to the given window. If QUERY-POINTER returns NIL for same-screen-p, the pointer is not on the same screen as the window. In this case, QUERY-POINTER returns a value of NIL for child and a value of zero for x and y. If QUERY-POINTER returns true for same-screen-p, the returned x and y are relative to the origin of window. The child is the child of the window containing the pointer, if any. The state-mask returned gives the current state of the modifier keys and pointer buttons. The returned root is the root window currently containing the pointer. The returned root-x and root-y specify the pointer coordinates relative to root.

     x
          Type INT16.

     y
          Type INT16.

     same-screen-p
          Type BOOLEAN.

     child
          Type WINDOW or NULL.

     state-mask
          Type CARD16.

     root-x
          Type INT16.

     root-y
          Type INT16.

     root
          Type WINDOW.

 -- Function: global-pointer-position display

     display
          A DISPLAY.

     Returns the root window currently containing the display pointer and the current position of the pointer relative to the root.

     root-x
          Type INT16.

     root-y
          Type INT16.

     root
          Type WINDOW.

 -- Function: pointer-position window

     window
          A WINDOW specifying the coordinate system for the returned position.

     Returns the current pointer coordinates relative to the given window. If POINTER-POSITION returns NIL for same-screen-p, the pointer is not on the same screen as the window.  In this case, POINTER-POSITION returns a value of NIL for child and a value of zero for x and y. If POINTER-POSITION returns true for same-screen-p, the returned x and y are relative to the origin of window.

     x
          Type INT16.

     y
          Type INT16.

     same-screen-p
          Type BOOLEAN.

     child
          Type WINDOW or NULL.

 -- Function: motion-events window &key :start :stop (:result-type 'list)

     window
          The WINDOW containing the returned motion events.

     :start
     :stop
          TIMESTAMP values for the time interval for returned motion events.

     :result-type
          The form of the returned motion events.

     Many X server implementations maintain a more precise history of pointer motion between event notifications. The pointer position at each pointer hardware interrupt can be stored into a buffer for later retrieval.This is called the motion history buffer. A paint program, for example, may want to have a precise history of where the pointer traveled, even though for most other applications this amount of detail is grossly excessive.

     The MOTION-EVENTS function returns all events in the motion history buffer that fall between the specified :START and :STOP timestamps (inclusive) and have coordinates that lie within the specified window (including borders) at its present placement. If the :START time is later than the :STOP time or if the :START time is in the future, no events are returned.

     motion-events
          Type (repeat-seq (int16 x) (int16 y) (timestamp time)).

 -- Function: warp-pointer destination destination-x destination-y

     destination
          The WINDOW into which the pointer is moved.

     destination-x
     destination-y
          The new position of the pointer relative to the destination.

     Moves the pointer to the given coordinates relative to the destination window.  WARP-POINTER should be rarely be used since the user should normally be in control of the pointer position. WARP-POINTER generates events just as if the user had instantaneously moved the pointer from one position to another.

     WARP-POINTER cannot move the pointer outside the confine-to window of an active pointer grab; an attempt to do so only moves the pointer as far as the closest edge of the confine-to window.

 -- Function: warp-pointer-relative display x-offset y-offset

     display
          A DISPLAY.

     x-offset
     y-offset
          The offsets used to adjust the pointer position.

     Moves the pointer by the given offsets. This function should rarely be used since the user should normally be in control of the pointer position. WARP-POINTER-RELATIVE generates events just as if the user had instantaneously moved the pointer from one position to another.

     WARP-POINTER-RELATIVE cannot move the pointer outside the confine-to window of an active pointer grab; an attempt to do so only moves the pointer as far as the closest edge of the confine-to window.

 -- Function: warp-pointer-if-inside destination destination-x destination-y source source-x source-y &optional (source-width 0) (source-height 0)

     destination
          The WINDOW into which the pointer is moved.

     destination-x
     destination-y
          The new position of the pointer relative to the destination.

     source
          The WINDOW that must currently contain the pointer.

     source-x
     source-y
     source-width
     source-height
          The source rectangle that must currently contain the pointer.

     Moves the pointer to the given position relative to the destination window. However, the move can only take place if the pointer is currently contained in a visible portion of the specified rectangle of the source window. If source-height is zero, it is replaced with the current height of source window minus source-y. If source-width is zero, it is replaced with the current width of source window minus source-x.

     WARP-POINTER-IF-INSIDE generates events just as if the user had instantaneously moved the pointer from one position to another. WARP-POINTER-IF-INSIDE cannot move the pointer outside the confine-to window of an active pointer grab; an attempt to do so only moves the pointer as far as the closest edge of the confine-to window.

 -- Function: warp-pointer-relative-if-inside x-offset y-offset source source-x source-y &optional (source-width 0) (source-height 0)

     x-offset
     y-offset
          The offsets used to adjust the pointer position.

     source
          The WINDOW that must currently contain the pointer.

     source-x
     source-y
     source-width
     source-height
          The source rectangle that must currently contain the pointer.

     Moves the pointer by the given offsets. However, the move can only take place if the pointer is currently contained in a visible portion of the specified rectangle of the source window. If source-height is zero, it is replaced with the current height of source-window minus source-y. If source-width is zero, it is replaced with the current width of source-window minus source-x.

     WARP-POINTER-RELATIVE-IF-INSIDE generates events just as if the user had instantaneously moved the pointer from one position to another. WARP-POINTER-RELATIVE-IF-INSIDE cannot move the pointer outside the confine-to window of an active pointer grab; an attempt to do so only moves the pointer as far as the closest edge of the confine-to window.

Managing Input Focus
====================

CLX provides the SET-FOCUS-INPUT and FOCUS-INPUT functions to set and get the keyboard input focus window.

 -- Function: set-input-focus display focus revert-to &optional time

     display
          A DISPLAY.

     focus
          The new input focus WINDOW.

     revert-to
          The focus WINDOW when focus is no longer viewable.

     time
          A TIMESTAMP.

     Changes the keyboard input focus and the last-focus-change time. The function has no effect if the specified time is earlier than the current last-focus-change time or is later than the current server time; otherwise, the last-focus-change time is set to the specified time. The SET-INPUT-FOCUS function causes the X server to generate :FOCUS-IN and :FOCUS-OUT events.

     If :NONE is specified as the focus, all keyboard events are discarded until a new focus window is set. In this case, the revert-to argument is ignored.

     If a window is specified as the focus argument, it becomes the keyboard's focus window.  If a generated keyboard event would normally be reported to this window or one of its inferiors, the event is reported normally; otherwise, the event is reported with respect to the focus window.

     If :POINTER-ROOT is specified as the focus argument, the input focus window is set to the root window of the screen containing the pointer when each keyboard event occurs. In this case, the revert-to argument is ignored.

     The specified focus window must be viewable at the time of the request. If the focus window later becomes not viewable, the new focus window depends on the revert-to argument. If revert-to is specified as :PARENT, the focus reverts to the parent (or the closest viewable ancestor) and the new revert-to value is take to be :NONE. If revert-to is :POINTER-ROOT or :NONE, the focus reverts to that value. When the focus reverts, :FOCUS-IN and :FOCUS-OUT events are generated, but the last-focus-change time is not affected.

 -- Function: input-focus display

     display
          A DISPLAY.

     Returns the focus window, :POINTER-ROOT, or :NONE, depending on the current state of the focus window. revert-to returns the current focus revert-to state.

     focus
          Type (OR WINDOW (MEMBER :NONE :POINTER-ROOT)).

     revert-to
          Type (OR WINDOW (MEMBER :NONE :POINTER-ROOT :PARENT)).

Grabbing the Pointer
====================

CLX provides the GRAB-POINTER and UNGRAB-POINTER functions for grabbing and releasing pointer control.

 -- Function: grab-pointer window event-mask &key :owner-p :sync-pointer-p :sync-keyboard-p :confine-to :cursor :time

     window
          The WINDOW grabbing the pointer.

     event-mask
          A POINTER-EVENT-MASK.

     :owner-p
          If true, all client windows receive pointer events normally.

     :sync-pointer-p
          Indicates whether the pointer is in synchronous or asynchronous mode.

     :sync-keyboard-p
          Indicates whether the keyboard is in synchronous or asynchronous mode.

     :confine-to
          A WINDOW to which the pointer is confined.

     :cursor
          A CURSOR.

     :time
          A TIMESTAMP. A NIL value means the current server time is used.

     Actively grabs control of the pointer. Further pointer events are only reported to the grabbing client. The request overrides any active pointer grab by this client.

     If :OWNER-P is NIL, all generated pointer events are reported with respect to window, and are only reported if selected by event-mask. If :OWNER-P is true, and if a generated pointer event would normally be reported to this client, it is reported normally; otherwise the event is reported with respect to the window, and is only reported if selected by event-mask. For either value of :OWNER-P, unreported events are simply discarded.

     If :SYNC-POINTER-P is NIL, pointer event processing continues normally (asynchronously); if the pointer is currently frozen by this client, then processing of pointer events is resumed. If :SYNC-POINTER-P is true (indicating a synchronous action), the pointer (as seen via the protocol) appears to freeze, and no further pointer events are generated by the server until the grabbing client issues a releasing ALLOW-EVENTS request. Actual pointer changes are not lost while the pointer is frozen; they are simply queued for later processing.

     If :SYNC-KEYBOARD-P is NIL, keyboard event processing is unaffected by activation of the grab. If :SYNC-KEYBOARD-P is true, the keyboard (as seen via the protocol) appears to freeze, and no further keyboard events are generated by the server until the grabbing client issues a releasing ALLOW-EVENTS request. Actual keyboard changes are not lost while the keyboard is frozen; they are simply queued for later processing.

     If :CURSOR is specified, it is displayed regardless of what window the pointer is in.  Otherwise, the normal cursor for the window is displayed.

     If a :CONFINE-TO window is specified, the pointer is restricted to stay within that window.  The :CONFINE-TO window does not need to have any relationship to the window. If the pointer is not initially in the :CONFINE-TO window, it is warped automatically to the closest edge (with :ENTER/:LEAVE-EVENTS generated normally) just before the grab activates.  If the :CONFINE-TO window is subsequently reconfigured, the pointer is warped automatically as necessary to keep it contained in the window.

     GRAB-POINTER generates :ENTER-NOTIFY and :LEAVE-NOTIFY events. GRAB-POINTER can fail with a status of:

       * :ALREADY-GRABBED if the pointer is actively grabbed by some other client

       * :FROZEN if the pointer is frozen by an active grab of another client

       * :NOT-VIEWABLE if the window or the :CONFINE-TO window is not viewable, or if the :CONFINE-TO window lies completely outside the boundaries of the root window.

       * :INVALID-TIME if the specified time is earlier than the last-pointer-grab time or later than the current server time. Otherwise, the last-pointer-grab time is set to the specified time, with current-time replaced by the current server time, and a value of :SUCCESS is returned by GRAB-POINTER.

     grab-status
          One of :ALREADY-GRABBED, :FROZEN, :INVALID-TIME, :NOT-VIEWABLE, or :SUCCESS.

 -- Function: ungrab-pointer display &key :time

     display
          A DISPLAY.

     :time
          A TIMESTAMP.

     Releases the pointer if this client has it actively grabbed (from either GRAB-POINTER, GRAB-BUTTON, or from a normal button press), and releases any queued events. The request has no effect if the specified :TIME is earlier than the last-pointer-grab time or is later than the current server time. An UNGRABPOINTER is performed automatically if the event window or :CONFINE-TO window for an active pointer grab becomes not viewable.

     This request generates :ENTER-NOTIFY and :LEAVE-NOTIFY events.

 -- Function: change-active-pointer-grab display event-mask &optional cursor time

     display
          A DISPLAY.

     event-mask
          A POINTER-EVENT-MASK.

     cursor
          A CURSOR or NIL.

     time
          A TIMESTAMP.

     Changes the specified dynamic parameters if the pointer is actively grabbed by the client and the specified time is no earlier than the last-pointer-grab time and no later than the current server time. The interpretation of event-mask and cursor are as in GRAB-POINTER.  CHANGE-ACTIVE-POINTER-GRAB has no effect on the passive parameters of a GRAB-BUTTON.

Grabbing a Button
=================

CLX provides the GRAB-BUTTON and UNGRAB-BUTTON functions for passively grabbing and releasing pointer control.

 -- Function: grab-button window button event-mask &key (:modifiers 0) :owner-p :sync-pointer-p :sync-keyboard-p :confine-to :cursor

     window
          A WINDOW.

     button
          The button (type CARD8) pressed or :ANY.

     event-mask
          A POINTER-EVENT-MASK.

     :modifiers
          A MODIFIER-MASK.

     :owner-p
          If true, all client windows receive pointer events normally.

     :sync-pointer-p
          Indicates whether the pointer is handled in a synchronous or asynchronous fashion.

     :sync-keyboard-p
          Indicates whether the keyboard is in synchronous or asynchronous mode.

     :confine-to
          A WINDOW to which the pointer is confined.

     :cursor
          A CURSOR.

     This request establishes a passive grab. If the specified button is pressed when the specified modifier keys are down (and no other buttons or modifier keys are down), and:

       * window contains the pointer

       * The :CONFINE-TO window (if any) is viewable

       * These constraints are not satisfied for any ancestor of window

     then:

       * The pointer is actively grabbed as described with GRAB-POINTER

       * The last-pointer-grab time is set to the time that the button was pressed (as transmitted in the :BUTTON-PRESS event)

       * The :BUTTON-PRESS event is reported

     The interpretation of the remaining arguments is the same as with GRAB-POINTER. The active grab is terminated automatically when all buttons are released (independent of the state of modifier keys).

     A zero modifier mask is equivalent to issuing the request for all possible modifier-key combinations (including the combination of no modifiers). It is not required that all specified modifiers have currently assigned keycodes. A button of :ANY is equivalent to issuing the request for all possible buttons. Otherwise, it is not required that the specified button currently be assigned to a physical button.

 -- Function: ungrab-button window button &key (:modifiers 0)

     window
          A WINDOW.

     button
          The button (type CARD8) that is released or :ANY.

     :modifiers
          A MODIFIER-MASK.

     Releases the passive button/key combination on the specified window if it was grabbed by this client. A zero modifier mask is equivalent to issuing the request for all possible modifier combinations including the combination of no modifiers. A button of :ANY is equivalent to issuing the request for all possible buttons. This has no effect on an active grab.

Grabbing the Keyboard
=====================

CLX provides the GRAB-KEYBOARD and UNGRAB-KEYBOARD functions for actively grabbing and releasing control of the keyboard.

 -- Function: grab-keyboard window &key :owner-p :sync-pointer-p :sync-keyboard-p :time

     window
          A WINDOW.

     :owner-p
          If true, all client windows receive keyboard input normally.

     :sync-pointer-p
          Indicates whether the pointer is in synchronous or asynchronous mode.

     :sync-keyboard-p
          Indicates whether the keyboard is in synchronous or asynchronous mode.

     :time
          A TIMESTAMP.

     Actively grabs control of the keyboard. Further key events are reported only to the grabbing client. The request overrides any active keyboard grab by this client.  GRAB-KEYBOARD generates :FOCUS-IN and :FOCUS-OUT events.

     If :OWNER-P is NIL, all generated key events are reported with respect to window. If :OWNER-P is true, then a generated key event that would normally be reported to this client is reported normally; otherwise the event is reported with respect to the window.  Both :KEY-PRESS and :KEY-RELEASE events are always reported, independent of any event selection made by the client.

     If :SYNC-KEYBOARD-P is NIL, keyboard event processing continues normally (asynchronously); if the keyboard is currently frozen by this client, then processing of keyboard events is resumed. If :SYNC-KEYBOARD-P is true, the keyboard (as seen via the protocol) appears to freeze, and no further keyboard events are generated by the server until the grabbing client issues a releasing ALLOW-EVENTS request. Actual keyboard changes are not lost while the keyboard is frozen; they are simply queued for later processing.

     If :SYNC-POINTER-P is NIL, pointer event processing is unaffected by activation of the grab. If :SYNC-POINTER-P is true, the pointer (as seen via the protocol) appears to freeze, and no further pointer events are generated by the server until the grabbing client issues a releasing ALLOW-EVENTS request. Actual pointer changes are not lost while the pointer is frozen; they are simply queued for later processing.

     The grab can fail with a status of:

       * :ALREADY-GRABBED if the keyboard is actively grabbed by some other client

       * :FROZEN if the keyboard is frozen by an active grab from another client

       * :NOT-VIEWABLE if window is not viewable

       * :INVALID-TIME if the specified time is earlier than the last-keyboard-grab time or later than the current server time. Otherwise, GRAB-KEYBOARD returns a status of :SUCCESS and last-keyboard-grab time is set to the specified time, with current-time replaced by current server time.

     grab-status
          One of :ALREADY-GRABBED, :FROZEN, :INVALID-TIME, :NOT-VIEWABLE, or :SUCCESS.

 -- Function: ungrab-keyboard display &key :time

     display
          A DISPLAY.

     :time
          A TIMESTAMP.

     Releases the keyboard if this client has it actively grabbed (from either GRAB-KEYBOARD or GRAB-KEY), and releases any queued events. The request has no effect if the specified time is earlier than the last-keyboard-grab time or is later than the current server time.  An UNGRAB-KEYBOARD is performed automatically if the event window for an active keyboard grab becomes not viewable.

Grabbing a Key
==============

The following paragraphs describe the functions used for passively grabbing and releasing the keyboard.

 -- Function: grab-key window key &key (:modifiers 0) :owner-p :sync-pointer-p :sync-keyboard-p :time

     window
          A WINDOW.

     key
          The key (type CARD8) to be grabbed or :ANY.

     :modifiers
          A MODIFIER-MASK.

     :owner-p
          If true, all client windows receive keyboard input normally.

     :sync-pointer-p
          Indicates whether the pointer is in synchronous or asynchronous mode.

     :sync-keyboard-p
          Indicates whether the keyboard is in synchronous or asynchronous mode.

     :time
          A TIMESTAMP.

     This request establishes a passive grab on the keyboard. If the specified key (which can also be a modifier key) is pressed (whether or not any specified modifier keys are down), and either of the following is true:

       * window is an ancestor of (or is) the focus window

       * window is a descendant of the focus window and contains the pointer

       * These constraints are not satisfied for any ancestor of window, then the following occurs:

            * The keyboard is actively grabbed as described in GRAB-KEYBOARD

            * The last-keyboard-grab time is set to the time that the key was pressed (as transmitted in the :KEY-PRESS event)

            * The :KEY-PRESS event is reported

     The interpretation of the remaining arguments is as for GRAB-KEYBOARD. The active grab is terminated automatically when the specified key has been released, independent of the state of the modifier keys.

     A zero modifier mask is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all specified modifiers have currently assigned keycodes. A key of :ANY is equivalent to issuing the request for all possible keycodes. Otherwise, the key must be in the range specified by DISPLAY-MIN-KEYCODE and DISPLAY-MAX-KEYCODE in the connection setup.

 -- Function: ungrab-key window key &key (:modifiers 0)

     window
          A WINDOW.

     key
          The key (type CARD8) to be released or :ANY.

     :modifiers
          A MODIFIER-MASK.

     Releases the key combination on the specified window if it was grabbed by this client. A zero modifier mask of :ANY is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A key of :ANY is equivalent to issuing the request for all possible keycodes. UNGRAB-KEY has no effect on an active grab.

Event Types
===========

The following paragraphs contain detailed descriptions of the contents of each event type. In CLX, events are not actually represented by structures, but rather by lists of keyword values passed to handler functions or by values bound to symbols within the clauses of EVENT-CASE and EVENT-COND forms. Nevertheless, it is convenient to describe event contents in terms of slots and to identify the components of events with slot name symbols. In fact, CLX uses the DECLARE-EVENT macro to define event slot symbols and to map these symbols to specific event data items returned by the X server (see Declaring Event Types).

The following paragraphs describe each event type, listing its EVENT-KEY keyword symbol and its slot name symbols. An event keyword symbol identifies a specific event type.  An event keyword symbol can be given as an argument to SEND-EVENT or to an event handler function; it can also appear in the event-match form of an EVENT-CASE clause. An event slot name symbol identifies a specific event data item. Event slot names appear as keywords with associated values among the arguments passed to SEND-EVENT or to an event handler function; as non-keyword symbols, they can also be in the event-slots form of an EVENT-CASE clause.

In certain cases, more than one name symbol is defined for the same event slot. For example, in :KEY-PRESS events, the symbols window and event-window both refer to the same event data item.

Keyboard and Pointer Events
---------------------------

The keyboard and pointer events are: :KEY-PRESS :KEY-RELEASE, :BUTTON-PRESS, :BUTTON-RELEASE, :MOTION-NOTIFY, :ENTER-NOTIFY, and :LEAVE-NOTIFY.

 -- Event Type: :key-press
 -- Event Type: :key-release
 -- Event Type: :button-press
 -- Event Type: :button-release

     Selected by :KEY-PRESS, :KEY-RELEASE, :BUTTON-PRESS, or :BUTTON-RELEASE.

     :KEY-PRESS, and :KEY-RELEASE events are generated when a key or pointer button changes state. Note that :KEY-PRESS and :KEY-RELEASE are generated for all keys, even those mapped to modifiers. All of these event types have the same slots. The window containing the pointer at the time of the event is referred to as the source window. The event window is the window to which the event is actually reported. The event window is found by starting with the source window and looking up the hierarchy for the first window on which any client has selected interest in the event (provided no intervening window prohibits event generation by including the event type in its do-not-propagate-mask). The actual window used for reporting can be modified by active grabs and, in the case of keyboard events, can be modified by the focus window.

     A :BUTTON-PRESS event has the effect of a temporary GRAB-BUTTON. When a pointer button is pressed and no active pointer grab is in progress, the ancestors of the source window are searched from the root down, looking for a passive grab to activate. If no matching passive grab on the button exists, then an active grab is started automatically for the client receiving the :BUTTON-PRESS event, and the last-pointer-grab time is set to the current server time. The effect is essentially equivalent to calling GRAB-BUTTON with the following arguments:

     window
          The event window.

     button
          The button that was pressed.

     event-mask
          The client's selected pointer events on the event window.

     :MODIFIERS
          0

     :OWNER-P
          T if the client has :OWNER-GRAB-BUTTON selected on the event window; otherwise NIL.

     :SYNC-POINTER-P
          NIL

     :SYNC-KEYBOARD-P
          NIL

     :CONFINE-TO
          NIL

     :CURSOR
          NIL

     The :BUTTON-PRESS grab is terminated automatically when all buttons are released. The functions UNGRAB-POINTER and CHANGE-ACTIVE-POINTER-GRAB can both be used to modify the :BUTTON-PRESS grab.

     window

     event-window
          Type WINDOW.

          The window receiving the event.

     code
          Type CARD8.

          The code argument varies with the event type. For :KEY-PRESS and :KEY-RELEASE, code is the keycode (see Keyboard Encodings). For :BUTTON-PRESS and :BUTTON-RELEASE, code is the pointer button number.

     x
          Type INT16.

          If event-window is on the same screen as root, then x and y are the pointer coordinates relative to the event-window; otherwise x and y are zero.

     y
          Type INT16.

          If event-window is on the same screen as root, then x and y are the pointer coordinates relative to the event-window; otherwise x and y are zero.

     state
          Type CARD16.

          A mask that gives the state of the buttons and modifier keys just before the event.

     time
          Type CARD32.

          A timestamp for the moment when the event occurred.

     root
          Type WINDOW.

          The root window of the source window.

     root-x
          Type INT16.

          The x coordinate of the pointer position relative to root at the time of the event.

     root-y
          Type INT16.

          The y coordinate of the pointer position relative to root at the time of the event.

     child
          Type (OR NULL WINDOW).

          If the source window is an inferior of the event-window, child is set to the child of event-window that is an ancestor of (or is) the source window; otherwise, it is set to NIL.

     same-screen-p
          Type BOOLEAN.

          True if event-window and root are on the same screen.

 -- Event Type: :motion-notify

     Selected by: :BUTTON-1-MOTION, :BUTTON-2-MOTION, :BUTTON-3-MOTION, :BUTTON-4-MOTION, :BUTTON-5-MOTION, :BUTTON-MOTION, or :POINTER-MOTION.

     The :MOTION-NOTIFY event is generated when the pointer moves. A :MOTION-NOTIFY event has the same slots as :BUTTON-PRESS :BUTTON-RELEASE, :KEY-PRESS, and :KEY-RELEASE events, with the exception that the code slot is replaced by the hint-p slot. As with these other events, the event window for :MOTION-NOTIFY is found by starting with the source window and looking up the hierarchy for the first window on which any client has selected interest in the event (provided no intervening window prohibits event generation by including :MOTION-NOTIFY in its do-not-propagate-mask).The actual window used for reporting can be modified by active grabs.

     :MOTION-NOTIFY events are generated only when the motion begins and ends in the window. The granularity of motion events is not guaranteed, but a client selecting for motion events is guaranteed to get at least one event when the pointer moves and comes to rest. Selecting :POINTER-MOTION generates :MOTION-NOTIFY events regardless of the state of the pointer buttons. By selecting some subset of :BUTTON[1-5]-MOTION instead, :MOTION-NOTIFY events are only received when one or more of the specified buttons are pressed. By selecting :BUTTON-MOTION, :MOTION-NOTIFY events are only received when at least one button is pressed. If :POINTER-MOTION-HINT is also selected, the server is free to send only one :MOTION-NOTIFY, until either the key or button state changes, the pointer leaves the event window, or the client calls QUERY-POINTER or MOTION-EVENTS.

     hint-p
          Type BOOLEAN.

          True if the event is a hint generated by selecting :POINTER-MOTION-HINT.

 -- Event Type: :enter-notify
 -- Event Type: :leave-notify

     Selected by: :ENTER-WINDOW or :LEAVE-WINDOW.

     If pointer motion or a window hierarchy change causes the pointer to be in a different window than before, :ENTER-NOTIFY and :LEAVE-NOTIFY events are generated instead of a :MOTION-NOTIFY event. All :ENTER-NOTIFY and :LEAVE-NOTIFY events caused by a hierarchy change are generated after any hierarchy event (:UNMAP-NOTIFY, :MAP-NOTIFY, :CONFIGURE-NOTIFY, :GRAVITY-NOTIFY, or :CIRCULATE-NOTIFY) caused by that change, but the ordering of :ENTER-NOTIFY and :LEAVE-NOTIFY events with respect to :FOCUS-OUT, :VISIBILITY-NOTIFY, and :EXPOSURE events is not constrained by the X protocol. An :ENTER-NOTIFY or :LEAVE-NOTIFY event can also be generated when a client application calls CHANGE-ACTIVE-POINTER-GRAB, GRAB-POINTER, or UNGRAB-POINTER.

     window
     event-window
          Type WINDOW.

          The window receiving the event.

     x
          Type INT16.

          The final pointer position. If event-window is on the same screen as root, then x and y are the pointer coordinates relative to the event-window; otherwise x and y are zero.

     y
          Type INT16.

          The final pointer position. If event-window is on the same screen as root, then x and y are the pointer coordinates relative to the event-window; otherwise x and y are zero.

     mode
          Type (MEMBER :NORMAL :GRAB :UNGRAB).

          Events caused when the pointer is actively grabbed have mode :GRAB. Events caused when an active pointer grab deactivates have mode :UNGRAB. In all other cases, mode is :NORMAL.

     kind
          Type (MEMBER :ANCESTOR :VIRTUAL :INFERIOR :NONLINEAR :NONLINEAR-VIRTUAL).

          When the pointer moves from window A to window B, and A is an inferior of B:

            * :LEAVE-NOTIFY with kind :ANCESTOR is generated on A

            * :LEAVE-NOTIFY with kind :VIRTUAL is generated on each window between A and B exclusive (in that order)

            * :ENTER-NOTIFY with kind :INFERIOR is generated on B

          When the pointer moves from window A to window B, and B is an inferior of A:

            * :LEAVE-NOTIFY with kind :INFERIOR is generated on A

            * :ENTER-NOTIFY with kind :VIRTUAL is generated on each window between A and B exclusive (in that order)

            * :ENTER-NOTIFY with kind :ANCESTOR is generated on B

          When the pointer moves from window A to window B, with window C being their least common ancestor:

            * :LEAVE-NOTIFY with kind :NONLINEAR is generated on A

            * :LEAVE-NOTIFY with kind :NONLINEAR-VIRTUAL is generated on each window between A and C exclusive (in that order)

            * :ENTER-NOTIFY with kind :NONLINEAR-VIRTUAL is generated on each window between C and B exclusive (in that order)

            * :ENTER-NOTIFY with kind :NONLINEAR is generated on B

          When the pointer moves from window A to window B, on different screens:

            * :LEAVE-NOTIFY with kind :NONLINEAR is generated on A

            * If A is not a root window, :LEAVE-NOTIFY with kind :NONLINEAR-VIRTUAL is generated on each window above A up to and including its root (in order)

            * If B is not a root window, :ENTER-NOTIFY with kind :NONLINEAR-VIRTUAL is generated on each window from B's root down to but not including B (in order)

            * :ENTER-NOTIFY with kind :NONLINEAR is generated on B

          When a pointer grab activates (but after any initial warp into a confine-to window, and before generating any actual :BUTTON-PRESS event that activates the grab), with G the GRAB-WINDOW for the grab and P the window the pointer is in, then :ENTER-NOTIFY and :LEAVE-NOTIFY events with mode :GRAB are generated (as for :NORMAL above) as if the pointer were to suddenly warp from its current position in P to some position in G. However, the pointer does not warp, and the pointer position is used as both the initial and final positions for the events.

          When a pointer grab deactivates (but after generating any actual :BUTTON-RELEASE event that deactivates the grab), with G the GRAB-WINDOW for the grab and P the window the pointer is in, then :ENTER-NOTIFY and :LEAVE-NOTIFY events with mode :UNGRAB are generated (as for :NORMAL above) as if the pointer were to suddenly warp from from some position in G to its current position in P.  However, the pointer does not warp, and the current pointer position is used as both the initial and final positions for the events.

     focus-p
          Type BOOLEAN.

          If event-window is the focus window or an inferior of the focus window, then focus-p is T; otherwise, focus-p is NIL.

     state
          Type CARD16.

          A mask that gives the state of the buttons and modifier keys just before the event.

     time
          Type CARD32.

          A timestamp for the moment when the event occurred.

     root
          Type WINDOW.

          The root window containing the final pointer position.

     root-x
          Type INT16.

          The x coordinate of the pointer position relative to root at the time of the event.

     root-y
          Type INT16.

          The y coordinate of the pointer position relative to root at the time of the event.

     child
          Type (OR NULL WINDOW).

          In a :LEAVE-NOTIFY event, if a child of the event-window contains the initial position of the pointer, the child slot is set to that child; otherwise, the child slot is NIL. For an :ENTER-NOTIFY event, if a child of the event-window contains the final pointer position, the child slot is set to that child; otherwise, the child slot is NIL.

     same-screen-p
          Type BOOLEAN.

          True if event-window and root are on the same screen.

Input Focus Events
------------------

The input focus events are :FOCUS-IN and :FOCUS-OUT.

 -- Event Type: :focus-in
 -- Event Type: :focus-out

     Selected by: :FOCUS-CHANGE.

     :FOCUS-IN and :FOCUS-OUT events are generated when the input focus changes. All :FOCUS-OUT events caused by a window :UNMAP are generated after any :UNMAP-NOTIFY event, but the ordering of :FOCUS-OUT with respect to generated :ENTER-NOTIFY, :LEAVE-NOTIFY, :VISIBILITY-NOTIFY, and :EXPOSE events is not constrained.

     window
     event-window
          Type WINDOW.

          For :FOCUS-IN, the new input focus window. For :FOCUS-OUT, the previous input focus window.

     mode
          Type (member :normal :while-grabbed :grab :ungrab).

          Events generated by SET-INPUT-FOCUS when the keyboard is not grabbed have mode :NORMAL. Events generated by SET-INPUT-FOCUS when the keyboard is grabbed have mode :WHILE-GRABBED. Events generated when a keyboard grab activates have mode :GRAB, and events generated when a keyboard grab deactivates have mode :UNGRAB.

     kind
          Type (MEMBER :ANCESTOR :VIRTUAL :INFERIOR :NONLINEAR :NONLINEAR-VIRTUAL :POINTER :POINTER-ROOT :NONE).

          When the focus moves from window A to window B, and A is an inferior of B, with the pointer in window P:

            * :FOCUS-OUT with kind :ANCESTOR is generated on A

            * :FOCUS-OUT with kind :VIRTUAL is generated on each window between A and B exclusive (in that order)

            * :FOCUS-IN with kind :INFERIOR is generated on B

            * If P is an inferior of B, but P is not A or an inferior of A or an ancestor of A, :FOCUS-IN with kind :POINTER is generated on each window below B down to and including P (in order)

          When the focus moves from window A to window B, and B is an inferior of A, with the pointer in window P:

            * If P is an inferior of A, but P is not A or an inferior of B or an ancestor of B, :FOCUS-OUT with kind :POINTER is generated on each window from P up to but not including A (in order)

            * :FOCUS-OUT with kind :INFERIOR is generated on A

            * :FOCUS-IN with kind :VIRTUAL is generated on each window between A and B exclusive (in that order)

            * :FOCUS-IN with kind :ANCESTOR is generated on B

          When the focus moves from window A to window B, with window C being their least common ancestor, and with the pointer in window P:

            * If P is an inferior of A, :FOCUS-OUT with kind :POINTER is generated on each window from P up to but not including A (in order)

            * :FOCUS-OUT with kind :NONLINEAR is generated on A

            * :FOCUS-OUT with kind :NONLINEAR-VIRTUAL is generated on each window between A and C exclusive (in that order)

            * :FOCUS-IN with kind :NONLINEAR-VIRTUAL is generated on each window between C and B exclusive (in that order)

            * :focus-in with kind :NONLINEAR is generated on B

            * If P is an inferior of B, :FOCUS-IN with kind :POINTER is generated on each window below B down to and including P (in order)

          When the focus moves from window A to window B, on different screens, with the pointer in window P:

            * If P is an inferior of A, :FOCUS-OUT with kind :POINTER is generated on each window from P up to but not including A (in order)

            * :FOCUS-OUT with kind :NONLINEAR is generated on A

            * If A is not a root window, :FOCUS-OUT with kind :NONLINEAR-VIRTUAL is generated on each window above A up to and including its root (in order)

            * If B is not a root window, :FOCUS-IN with kind :NONLINEAR-VIRTUAL is generated on each window from B's root down to but not including B (in order)

            * :FOCUS-IN with kind :NONLINEAR is generated on B

            * If P is an inferior of B, :FOCUS-IN with kind :POINTER is generated on each window below B down to and including P (in order)

          When the focus moves from window A to :POINTER-ROOT (or :NONE), with the pointer in window P:

            * If P is an inferior of A, :FOCUS-OUT with kind :POINTER is generated on each window from P up to but not including A (in order)

            * :FOCUS-OUT with kind :NONLINEAR is generated on A

            * If A is not a root window, :FOCUS-OUT with kind :NONLINEAR-VIRTUAL is generated on each window above A up to and including its root (in order)

            * :FOCUS-IN with kind :POINTER-ROOT (or :NONE) is generated on all root windows

            * If the new focus is :POINTER-ROOT, :FOCUS-IN with kind :POINTER is generated on each window from P's root down to and including P (in order)

          When the focus moves from :POINTER-ROOT (or :NONE) to window A, with the pointer in window P:

            * If the old focus is :POINTER-ROOT, :FOCUS-OUT with kind :POINTER is generated on each window from P up to and including P's root (in order)

            * :FOCUS-OUT with kind :POINTER-ROOT (or :NONE) is generated on all root windows

            * If A is not a root window, :FOCUS-IN with kind :NONLINEAR-VIRTUAL is generated on each window from A's root down to but not including A (in order)

            * :FOCUS-IN with kind :NONLINEAR is generated on A

            * If P is an inferior of A, :FOCUS-IN with kind :POINTER is generated on each window below A down to and including P (in order)

          When the focus moves from :POINTER-ROOT to :NONE (or vice versa), with the pointer in window P:

            * If the old focus is :POINTER-ROOT, :FOCUS-OUT with kind :POINTER is generated on each window from P up to and including P's root (in order)

            * :FOCUS-OUT with kind :POINTER-ROOT (or :NONE) is generated on all root windows

            * :FOCUS-IN with kind :NONE (or :POINTER-ROOT) is generated on all root windows

            * If the new focus is :POINTER-ROOT, :FOCUS-IN with kind :POINTER is generated on each window from P's root down to and including P (in order)

     When a keyboard grab activates (but before generating any actual :KEY-PRESS event that activates the grab), with G the GRAB-WINDOW for the grab and F the current focus, then :FOCUS-IN and :FOCUS-OUT events with mode :GRAB are generated (as for :NORMAL above) as if the focus were to change from F to G.

     When a keyboard grab deactivates (but after generating any actual :KEY-RELEASE event that deactivates the grab), with G the GRAB-WINDOW for the grab and F the current focus, then :FOCUS-IN and :FOCUS-OUT events with mode :UNGRAB are generated (as for :NORMAL above) as if the focus were to change from G to F.

Keyboard and Pointer State Events
---------------------------------

The keyboard and pointer state events are :KEYMAP-NOTIFY and :MAPPING-NOTIFY.

 -- Event Type: :keymap-notify

     Selected by: :KEYMAP-STATE.

     The :KEYMAP-NOTIFY event returns the current state of the keyboard. :KEYMAP-NOTIFY is generated immediately after every :ENTER-NOTIFY and :FOCUS-IN.

     window
     event-window
          Type WINDOW.

          The window receiving an :ENTER-NOTIFY or :FOCUS-IN event.

     keymap
          Type (BIT-VECTOR 256).

          A bit-vector containing the logical state of the keyboard. Each bit set to 1 indicates that the corresponding key is currently pressed. The vector is represented as 32 bytes. For n from 0 to 7, byte n (from 0) contains the bits for keys 8n to 8n+7, with the least significant bit in the byte representing key 8n.

 -- Event Type: :mapping-notify

     The X server reports :MAPPING-NOTIFY events to all clients. There is no mechanism to express disinterest in this event. The X server generates this event type whenever a client application calls one of the following:

       * SET-MODIFIER-MAPPING to indicate which keycodes to use as modifiers (the status reply must be :MAPPING-SUCCESS)

       * CHANGE-KEYBOARD-MAPPING to change the keyboard mapping

       * SET-POINTER-MAPPING to set the pointer mapping (the status reply must be :MAPPING-SUCCESS)

     request
          Type (member :modifier :keyboard :pointer).

          Indicates the kind of change that occurred--:MODIFIER for a successful SET-MODIFIER-MAPPING, :KEYBOARD for a successful CHANGE-KEYBOARD-MAPPING, and :POINTER for a successful SET-POINTER-MAPPING.

     start
          Type CARD8.

          If request is :KEYBOARD, then start and count indicate the range of altered keycodes.

     count
          Type CARD8.

          If request is :KEYBOARD, then start and count indicate the range of altered keycodes.

Exposure Events
---------------

The X server cannot guarantee that a window's content is preserved when the window is obscured or reconfigured. X requires client applications to be capable of restoring the contents of a previously-invisible window region whenever it is exposed.  Therefore, the X server sends events describing the exposed window and its exposed region. For a simple window, a client can choose to redraw the entire content whenever any region is exposed. For a complex window, a client can redraw only the exposed region.

 -- Event Type: :exposure

     Selected by: :EXPOSURE.

     An :EXPOSURE event is sent when redisplay is needed for a window region whose content has been lost. Redisplay is needed when one of the following occurs:

       * A region is exposed for a window and the X server has no backing store for the region

       * A region of a viewable window is obscured and the X server begins to honor the window's backing-store attribute of :ALWAYS or :WHEN-MAPPED

       * The X server begins to honor an unviewable window's backing-store attribute of :ALWAYS or :WHEN-MAPPED.

     The regions needing redisplay are decomposed into an arbitrary set of rectangles, and an :EXPOSURE event is generated for each rectangle. For a given action causing :EXPOSURE events, the set of events for a given window are guaranteed to be reported contiguously.

     :EXPOSURE events are never generated for :INPUT-ONLY windows.

     All :EXPOSURE events caused by a hierarchy change are generated after any hierarchy event (:UNMAP-NOTIFY, :MAP-NOTIFY, :CONFIGURE-NOTIFY,:GRAVITY-NOTIFY, or :CIRCULATE-NOTIFY) caused by that change. All :EXPOSURE events on a given window are generated after any :VISIBILITY-NOTIFY event on that window, but it is not required that all :EXPOSURE events on all windows be generated after all visibility events on all windows. The ordering of :EXPOSURE events with respect to :FOCUS-OUT, :ENTER-NOTIFY, and :LEAVE-NOTIFY events is not constrained.

     window
     event-window
          Type WINDOW.

          The window needing redisplay.

     x
          Type CARD16.

          The position of the left edge of the region to redisplay, relative to the event-window.

     y
          Type CARD16.

          The position of the top edge of the region to redisplay, relative to the event-window.

     width
          Type CARD16.

          The width of the region to redisplay.

     height
          Type CARD16.

          The height of the region to redisplay.

     count
          Type CARD16.

          If count is zero, then no more :EXPOSURE events for this window follow. If count is nonzero, then at least that many more :EXPOSURE events for this window follow (and possibly more).

 -- Event Type: :graphics-exposure

     A :GRAPHICS-EXPOSURE event is generated by a call to COPY-AREA or COPY-PLANE when the exposures attribute of the graphics context is :ON. A :GRAPHICS-EXPOSURE event reports a destination region whose content cannot be computed because the content of the corresponding source region has been lost. For example, the missing source region may be obscured or may lie outside the current source drawable size. For a given action causing :GRAPHICS-EXPOSURE events, the set of events for a given destination are guaranteed to be reported contiguously.

     drawable
     event-window
          Type DRAWABLE.

          The destination drawable for the COPY-AREA or COPY-PLANE function.

     x
          Type CARD16.

          The position of the left edge of the destination region, relative to the drawable.

     y
          Type CARD16.

          The position of the top edge of the destination region, relative to the drawable.

     width
          Type CARD16.

          The width of the destination region.

     height
          Type CARD16.

          The height of the destination region.

     count
          Type CARD16.

          If count is zero then no more :GRAPHICS-EXPOSURE events for the drawable follow. If count is nonzero then at least that many more :GRAPHICS-EXPOSURE events for the drawable follow (and possibly more).

     major
          Type CARD8.

          The major opcode for the graphics request generating the event (62 for COPY-AREA, 63 for COPY-PLANE).

     minor
          Type CARD16.

          The minor opcode for the graphics request generating the event (0 for both COPY-AREA and COPY-PLANE).

 -- Event Type: :no-exposure

     A :NO-EXPOSURE event is generated by a call to COPY-AREA or COPY-PLANE when the exposures attribute of the graphics context is :ON. If no :GRAPHICS-EXPOSURE events are generated, then a single :NO-EXPOSURE event is sent.

     drawable
     event-window
          Type DRAWABLE.

          The destination drawable for the COPY-AREA or COPY-PLANE function.

     major
          Type CARD8.

          The major opcode for the graphics request generating the event (62 for COPY-AREA, 63 for COPY-PLANE).

     minor
          Type CARD16.

          The minor opcode for the graphics request generating the event (0 for both COPY-AREA and COPY-PLANE).

Window State Events
-------------------

The following paragraphs describe the events that can be received when a window becomes:

  * Created

  * Destroyed

  * Invisible

  * Mapped

  * Moved

  * Reparented

  * Resized

  * Restacked

  * Unmapped

  * Visible

 -- Event Type: :circulate-notify

     Selected by: :STRUCTURE-NOTIFY on a window or :SUBSTRUCTURE-NOTIFY on its parent.

     A :CIRCULATE-NOTIFY event is generated whenever a window is actually restacked as a result of a client application calling CIRCULATE-WINDOW-UP or CIRCULATE-WINDOW-DOWN.

     event-window
          Type WINDOW.

          The window receiving the event.

     window
          Type WINDOW.

          The window that was restacked.

     place
          Type (MEMBER :TOP :BOTTOM).

          If place is :TOP, the window is now on top of all siblings. Otherwise, it is below all siblings.

 -- Event Type: :configure-notify

     Selected by: :STRUCTURE-NOTIFY on a window or :SUBSTRUCTURE-NOTIFY on its parent.

     The :CONFIGURE-NOTIFY event is generated when the position or size of a window actually changes as a result of a client application setting its x, y, width, height, or border-width attributes.

     event-window
          Type WINDOW.

          The window receiving the event.

     window
          Type WINDOW.

          The window that was moved or resized.

     x
          Type INT16.

          x and y specify the new upper-left corner position of the window relative to its parent.

     y
          Type INT16.

          x and y specify the new upper-left corner position of the window relative to its parent.

     width
          Type CARD16.

          width and height specify the new size of the window interior.

     height
          Type CARD16.

          width and height specify the new size of the window interior.

     border-width
          Type CARD16.

          The new window border width.

     above-sibling
          Type (OR NULL WINDOW).

          The sibling immediately below the window. If above-sibling is NIL, then the window is below all of its siblings.

     override-redirect-p
          Type BOOLEAN.

          override-redirect-p is true if the override-redirect attribute of the window is :ON; otherwise, it is NIL. See WINDOW-OVERRIDE-REDIRECT in Window Attributes.

     The X server can report :CREATE-NOTIFY events to clients wanting information about creation of windows. The X server generates this event whenever a client application creates a window by calling CREATE-WINDOW.

     To receive this event type in a client application, you setf the :SUBSTRUCTURE-NOTIFY as the event-mask in the parent window's event-mask slot.

 -- Event Type: :create-notify

     Selected by: :SUBSTRUCTURE-NOTIFY.

     The :CREATE-NOTIFY event is generated when a window is created and is sent to the parent window.

     parent
     event-window
          Type WINDOW.

          The parent window receiving the event.

     window
          Type WINDOW.

          The new window created.

     x
          Type INT16.

          x and y specify the initial upper-left corner position of the window relative to the parent.

     y
          Type INT16.

          x and y specify the initial upper-left corner position of the window relative to the parent.

     width
          Type CARD16.

          width and height specify the initial size of the window interior.

     height
          Type CARD16.

          width and height specify the initial size of the window interior.

     border-width
          Type CARD16.

          The initial window border width.

     override-redirect-p
          Type BOOLEAN.

          override-redirect-p is true if the override-redirect attribute of the window is :ON; otherwise, it is NIL. See WINDOW-OVERRIDE-REDIRECT in Window Attributes.

 -- Event Type: :destroy-notify

     Selected by: :STRUCTURE-NOTIFY on a window or :SUBSTRUCTURE-NOTIFY on its parent.

     The :DESTROY-NOTIFY event is generated when a window is destroyed. The ordering of the :DESTROY-NOTIFY events is such that for any given window, :DESTROY-NOTIFY is generated on all inferiors of a window before :DESTROY-NOTIFY is generated on the window. The ordering among siblings and across subhierarchies is not otherwise constrained.

     event-window
          Type WINDOW.

          The window receiving the event.

     window
          Type WINDOW.

          The window that was destroyed.

 -- Event Type: :gravity-notify

     Selected by: :STRUCTURE-NOTIFY on a window or :SUBSTRUCTURE-NOTIFY on its parent.

     The X server can report :GRAVITY-NOTIFY events to clients wanting information about when a window is moved because of a change in the size of its parent. The X server generates this event whenever a client application actually moves a child window as a result of resizing its parent by calling WITH-STATE with the appropriate arguments set.

     event-window
          Type WINDOW.

          The window receiving the event.

     window
          Type WINDOW.

          The window that was moved.

     x
          Type INT16.

          x and y specify the new upper-left corner position of the window relative to its parent.

     y
          Type INT16.

          x and y specify the new upper-left corner position of the window relative to its parent.

 -- Event Type: :map-notify

     Selected by: :STRUCTURE-NOTIFY on a window or :SUBSTRUCTURE-NOTIFY on its parent.

     The X server can report :MAP-NOTIFY events to clients wanting information about which windows are mapped. The X server generates this event type whenever a client application changes the window's state from unmapped to mapped by calling MAP-WINDOW or MAP-SUBWINDOW.

     To receive this event type, you SETF :STRUCTURE-NOTIFY as the event-mask on the window's EVENT-MASK slot. You can also receive this event type by setfing the :SUBSTRUCTURE-NOTIFY event-mask on the parent window.

     event-window
          Type WINDOW.

          The window receiving the event.

     window
          Type WINDOW.

          The window that was mapped.

     override-redirect-p
          Type BOOLEAN.

          override-redirect-p is true if the override-redirect attribute of the window is :ON; otherwise, it is NIL. See WINDOW-OVERRIDE-REDIRECT in Window Attributes.

 -- Event Type: :reparent-notify
     Selected by: :STRUCTURE-NOTIFY on a window or :SUBSTRUCTURE-NOTIFY on its old or new parent.

     The :REPARENT-NOTIFY event is generated when a window is reparented.

     event-window
          Type WINDOW.

          The window receiving the event.

     window
          Type WINDOW.

          The window that was reparented.

     parent
          Type WINDOW.

          The new parent of the window.

     x
          Type INT16.

          x and y specify the upper-left corner position of the window relative to its new parent.

     y
          Type INT16.

          x and y specify the upper-left corner position of the window relative to its new parent.

     override-redirect-p
          Type BOOLEAN.

          override-redirect-p is true if the override-redirect attribute of the window is :ON; otherwise, it is NIL. See WINDOW-OVERRIDE-REDIRECT in Window Attributes.

 -- Event Type: :unmap-notify

     Selected by: :STRUCTURE-NOTIFY on a window or :SUBSTRUCTURE-NOTIFY on its parent.

     The :UNMAP-NOTIFY event is generated when a mapped window is unmapped.

     event-window
          Type WINDOW.

          The window receiving the event.

     window
          Type WINDOW.

          The window that was unmapped.

     configure-p
          Type BOOLEAN.

          configure-p is true if the window has a win-gravity attribute of :UNMAP, and the event was generated because window's parent was resized.

 -- Event Type: :visibility-notify

     Selected by: :VISIBILITY-CHANGE.

     The :VISIBILITY-NOTIFY event is sent when the visibility of a window changes.  :VISIBILITY-NOTIFY events are never generated on :INPUT-ONLY windows. For the purposes of this event, the visibility of the window is not affected by its subwindows.

     All :VISIBILITY-NOTIFY events caused by a hierarchy change are generated after any hierarchy event caused by that change (for example, :UNMAP-NOTIFY, :MAP-NOTIFY, :CONFIGURE-NOTIFY, :GRAVITY-NOTIFY, or :CIRCULATE-NOTIFY). Any :VISIBILITY-NOTIFY event on a given window is generated before any :EXPOSURE events on that window, but it is not required that all :VISIBILITY-NOTIFY events on all windows be generated before all :EXPOSURE events on all windows. The ordering of :VISIBILITY-NOTIFY events with respect to :FOCUS-OUT, :ENTER-NOTIFY, and :LEAVE-NOTIFY events is not constrained.

     window
     event-window
          Type WINDOW.

          The window that changed in visibility.

     state
          Type (MEMBER :UNOBSCURED :PARTIALLY-OBSCURED :FULLY-OBSCURED).

          When the window was either unviewable or it was viewable and at least partially obscured, and the window changed to viewable and completely unobscured, then state is :UNOBSCURED.

          When the window was either unviewable or it was viewable and completely obscured, and the window changed to viewable and partially obscured, then state is :PARTIALLY-OBSCURED.

          When the window was either unviewable or it was at least partially visible, and the window changed to viewable and completely obscured, then state is :FULLY-OBSCURED.

Structure Control Events
------------------------

The following paragraphs describe events used to redirect client requests that reconfigure, restack, or map a window. Structure control events are typically used only by window managers and not by ordinary client applications. Structure control events report redirected requests, allowing a window manager to modify the requests before they are actually performed. However, if the override-redirect attribute of a window is :ON, then no requests are redirected and no structure control events are generated.

 -- Event Type: :circulate-request

     The :CIRCULATE-REQUEST event is generated when a client application calls CIRCULATE-WINDOW-UP or CIRCULATE-WINDOW-DOWN with a window that has the override-redirect attribute :OFF. The window argument specifies the window to be restacked, and place specifies what the new position in the stacking order should be (either :TOP or :BOTTOM).

     Selected by: :SUBSTRUCTURE-REDIRECT on parent.

     parent
     event-window
          Type WINDOW.

          The window receiving the event. The receiving client must have selected :SUBSTRUCTURE-REDIRECT on this window.

     window
          Type WINDOW.

          The window to be restacked.

     place
          Type (member :top :bottom).

          The new stacking priority requested for window.

 -- Event Type: :colormap-notify
     Selected by: :COLORMAP-CHANGE.

     The :COLORMAP-NOTIFY event is generated with new-p T when the colormap associated with a window is changed, installed, or uninstalled.

     window
     event-window
          Type WINDOW.

          The window receiving the event.

     colormap
          Type (or null colormap).

          The colormap attribute of the window.

     new-p
          Type BOOLEAN.

          If new-p is true, then the window's colormap attribute has changed to the given colormap. Otherwise, the window's colormap attribute has not, but the colormap has been installed or uninstalled.

     installed-p
          Type BOOLEAN.

          If installed-p is true, then the colormap is currently installed.

 -- Event Type: :configure-request

     Selected by::SUBSTRUCTURE-REDIRECT on parent.

     The :CONFIGURE-REQUEST event is generated when a client program sets the x, y, width, height, border-width or stacking priority attributes of a window that has the override-redirect attribute :OFF.

     parent
     event-window
          Type WINDOW.

          The window receiving the event. The receiving client must have selected :SUBSTRUCTURE-REDIRECT on this window.

     window
          Type WINDOW.

          The window to be reconfigured.

     x
          Type INT16.

          x and y specify the requested upper-left corner position of the window relative to the parent. If either x or y is not specified in the value-mask, then it is set to the current window position.

     y
          Type INT16.

          x and y specify the requested upper-left corner position of the window relative to the parent. If either x or y is not specified in the value-mask, then it is set to the current window position.

     width
     height
          Type CARD16.

          width and height specify the requested size of the window interior. If either width or height is not specified in the value-mask, then it is set to the current window size.

     border-width
          Type CARD16

          The requested window border width. If border-width is not specified in the value-mask, then it is set to the current window border-width.

     stack-mode
          Type (member :above :below :top-if :bottom-if :opposite).

          stack-mode and above-sibling specify the requested stacking priority of the window. If stack-mode is not specified in the value-mask, then it is set to :ABOVE.

     above-sibling
          Type (OR NULL WINDOW).

          stack-mode and above-sibling specify the requested stacking priority of the window. If above-sibling is not specified in the value-mask, then it is set to NIL.

     value-mask
          Type MASK16.

          Specifies the changed window attributes contained in the redirected client request. Each 1 bit specifies that the corresponding attribute was changed.

 -- Event Type: :map-request

     Selected by: :SUBSTRUCTURE-REDIRECT on parent.

     The :MAP-REQUEST event is generated when a client application maps a window that has the override-redirect attribute :OFF.

     parent
     event-window
          Type WINDOW.

          The window receiving the event. The receiving client must have selected :SUBSTRUCTURE-REDIRECT on this window.

     window
          Type WINDOW.

          The window to be mapped.

 -- Event Type: :resize-request

     Selected by: :RESIZE-REDIRECT.

     The :RESIZE-REQUEST event is generated when a client program sets the width or height attributes of a window that has the override-redirect attribute :OFF.

     window
     event-window
          Type WINDOW.

          The window to be resized.

     width
     height
          Type CARD16.

          width and height specify the requested size of the window interior. If either width or height was unchanged in the client request, then it is set to the current window size.

Client Communications Events
----------------------------

The client communications events discussed in the following paragraphs are: :CLIENT-MESSAGE, :PROPERTY-NOTIFY, :SELECTION-CLEAR, :SELECTION-REQUEST, and :SELECTION-NOTIFY.

 -- Event Type: :client-message

     The :CLIENT-MESSAGE event is generated exclusively by client calls to SEND-EVENT. The X server places no interpretation on the type or content of data sent in a :CLIENT-MESSAGE. A client can neither select :CLIENT-MESSAGE events nor avoid receiving them.

     window
     event-window
          Type WINDOW.

          The window receiving the event.

     type
          Type KEYWORD.

          An xatom keyword that specifies the type of client message. Interpretation of the type is determined solely by agreement between the sending and receiving clients.

     format
          Type (MEMBER 8 16 32).

          An integer that specifies whether data should be viewed as a sequence of 8-bit, 16-bit, or 32-bit quantities.

     data
          Type (sequence integer).

          The data content of the client message. data always consists of 160 bytes -- depending on format, either 20 8-bit values, 10 16-bit values or 5 32-bit values. The amount of this data actually used by a particular client message depends on the type.

 -- Event Type: :property-notify
     Selected by: :PROPERTY-CHANGE.

     The :PROPERTY-NOTIFY event is generated when a window property is changed or deleted.

     window
     event-window
          Type WINDOW.

          The window receiving the event.

     atom
          Type KEYWORD.

          The property that was changed or deleted.

     state
          Type (member :new-value :deleted).

          state is :NEW-VALUE if the property was changed using CHANGE-PROPERTY or ROTATE-PROPERTIES, even if zero-length data was added or if all or part of the property was replaced with identical data. state is :DELETED if the property was deleted using DELETE-PROPERTY or GET-PROPERTY.

     time
          Type TIMESTAMP.

          The server time when the property was changed or deleted.

 -- Event Type: :selection-clear

     The :SELECTION-CLEAR event is reported to the previous owner of a selection when the owner of the selection is changed. The selection owner is changed by a client using setf.  A client can neither select :SELECTION-CLEAR events nor avoid receiving them.

     window
     event-window
          Type WINDOW.

          The window losing ownership of the selection.

     selection
          Type KEYWORD.

          The name of the selection.

     time
          Type TIMESTAMP.

          The last-change time recorded for the selection.

 -- Event Type: :selection-notify

     The :SELECTION-NOTIFY event is sent to a client calling CONVERT-SELECTION.  :SELECTION-NOTIFY reports the result of the client request to return the current value of a selection into a particular form. :SELECTION-NOTIFY is sent using SEND-EVENT by the owner of the selection or (if no owner exists) by the X server. A client can neither select :SELECTION-NOTIFY events nor avoid receiving them.

     NOTE: Standard conventions for inter-client communication require the following additional steps in processing a :SELECTION-NOTIFY event:

      1. The client receiving this event should call GET-PROPERTY to return the converted selection value.

      2. After receiving the selection value, the property should then be deleted (either by using the :DELETE-P argument to GET-PROPERTY or by calling DELETE-PROPERTY).

     window
     event-window
          Type WINDOW.

          The requestor window given in the call to CONVERT-SELECTION.

     selection
          Type KEYWORD.

          The selection to be converted.

     target
          Type KEYWORD.

          An XATOM specifying the type of the converted selection value. This is the same target type given in the call to CONVERT-SELECTION.

     property
          Type (or null keyword).

          The window property containing the converted selection. If the property is NIL, then either the selection has no owner or the owner could not perform the conversion to the target type.

     time
          Type TIMESTAMP.

          The timestamp from the client call to CONVERT-SELECTION.

 -- Event Type: :selection-request

     The :SELECTION-REQUEST event is reported to the owner of a selection when a client calls CONVERT-SELECTION. This event requests the selection owner to convert the current value of a selection into a specified form and to return it to the requestor. A client can neither select :SELECTION-REQUEST events nor avoid receiving them.

     The selection owner should respond to a :SELECTION-REQUEST event by performing the following steps:

      1. Convert the current selection value to the target type.

      2. Store the converted selection value in the property. If property is NIL, then the owner should choose the property.

      3. Call SEND-EVENT to send a :SELECTION-NOTIFY event to the requestor containing the property with the converted value. If the selection could not be converted to the target type, then a NIL property should be sent. The :SELECTION, :TARGET, and :TIME arguments to SEND-EVENT should be the same as those received in the :SELECTION-REQUEST event. The event-mask argument to SEND-EVENT should be NIL; that is, the :SELECTION-NOTIFY event should be sent to client that created the requestor.

     NOTE: Standard conventions for inter-client communication require the following additional steps in processing a :SELECTION-REQUEST event:

      1. The property used to store the selection value must belong to the requestor.

      2. If the property is NIL, the target type ATOM should be used as the property name.

      3. If the window did not actually own the selection at the given time, the request should be refused, just as if it could not be converted to the target type.

     window
     event-window
          Type WINDOW.

          The selection owner receiving the event.

     requestor
          Type WINDOW.

          The window requesting the converted selection.

     selection
          Type KEYWORD.

          The selection to be converted.

     target
          Type KEYWORD.

          An XATOM specifying the type of the converted selection value.

     property
          Type (or null keyword).

          A requestor window property.

     time
          Type TIMESTAMP.

          The timestamp sent in the client CONVERT-SELECTION request.

Declaring Event Types
---------------------

CLX uses the DECLARE-EVENT macro to define the event slot symbols that access the contents of X events. Most client applications do not need to use DECLARE-EVENT because the declarations for all core X events are already defined by CLX.  Programmers using extensions to the X protocol can use DECLARE-EVENT to allow CLX to handle new event types returned by an extended X server.

 -- Macro: declare-event event-codes &rest slot-declarations

     Defines a mapping between event slot symbols and the data items in event messages received from an X server.

     The event-codes argument gives the event type keyword for the event described. If several event types share the same slots, then event-codes can be a list of event type keywords. slot-declarations is a list containing an element for each event data item. The order of slot-declarations corresponds to the order of event data items defined by the X protocol.

     Each element of slot-declarations is a list of the form (type slot-name*), where type is a Common Lisp type specifier and slot-name is a slot name symbol. The effect of such a list is to declare that the next data items in the event have the given data type and are associated with the given slot-name symbols. slot-name can also be a list of slot name symbols; in this case, each symbol in the list is an alias that refers to the same event data item.

     event-codes
          An event type keyword or a list of event type keywords.

     slot-declarations
          A list of clauses defining event slot symbols.

Releasing Queued Events
=======================

A client grabbing the keyboard or pointer can freeze the reporting of events on that device. When an input device is thus frozen, the server queues events until explicitly requested to release them by the grabbing client. CLX programs can use the ALLOW-EVENTS function to release queued events from a frozen input device.

 -- Function: allow-events display mode &optional time

     display
          A DISPLAY.

     mode
          One of: :ASYNC-POINTER, :SYNC-POINTER, :REPLY-POINTER, :ASYNC-KEYBOARD, :SYNC-KEYBOARD, :REPLAY-KEYBOARD, :ASYNC-BOTH, :SYNC-BOTH.

     time
          A TIMESTAMP.

     Releases some queued events if the client has caused a device to freeze. The request has no effect if the time is earlier than the last-grab time of the most recent active grab for the client, or if the time is later than the current server time. If time is NIL, the current server time is used. The effect of this function depends on the specified mode.

       * :ASYNC-POINTER -- If the pointer is frozen by the client, pointer event processing continues normally. If the pointer is frozen twice by the client on behalf of two separate grabs, :ASYNC-POINTER releases events for both grabs. :ASYNC-POINTER has no effect if the pointer is not frozen by the client, but the pointer need not be grabbed by the client.

       * :SYNC-POINTER -- If the pointer is frozen and actively grabbed by the client, pointer event processing continues normally until the next :BUTTON-PRESS or :BUTTON-RELEASE event is reported to the client, at which time the pointer again appears to freeze. However, if the reported event causes the pointer grab to be released, the pointer does not freeze. :SYNC-POINTER has no effect if the pointer is not frozen by the client, or if the pointer is not grabbed by the client.

       * :REPLAY-POINTER -- If the pointer is actively grabbed by the client and is frozen as the result of an event having been sent to the client (either from the activation of a GRAB-BUTTON, or from a previous ALLOW-EVENTS with mode :SYNC-POINTER, but not from a GRAB-POINTER), the pointer grab is released and that event is completely reprocessed, but this time ignoring any passive grabs at or above (towards the root) the GRAB-WINDOW of the grab just released. The request has no effect if the pointer is not grabbed by the client, or if the pointer is not frozen as the result of an event.

       * :ASYNC-KEYBOARD -- If the keyboard is frozen by the client, keyboard event processing continues normally. If the keyboard is frozen twice by the client on behalf of two separate grabs, :ASYNC-KEYBOARD releases events for both grabs. :ASYNC-KEYBOARD has no effect if the keyboard is not frozen by the client, but the keyboard need not be grabbed by the client.

       * :SYNC-KEYBOARD -- If the keyboard is frozen and actively grabbed by the client, keyboard event processing continues normally until the next :KEY-PRESS or :KEY-RELEASE event is reported to the client, at which time the keyboard again appears to freeze. However if the reported event causes the keyboard grab to be released, the keyboard does not freeze. :SYNC-KEYBOARD has no effect if the keyboard is not frozen by the client, or if the keyboard is not grabbed by the client.

       * :REPLAY-KEYBOARD -- If the keyboard is actively grabbed by the client and is frozen as the result of an event having been sent to the client (either from the activation of a grab-key, or from a previous ALLOW-EVENTS with mode :SYNC-KEYBOARD, but not from a GRAB-KEYBOARD), the keyboard grab is released and that event is completely reprocessed, but this time ignoring any passive grabs at or above (towards the root) the GRAB-WINDOW of the grab just released. The request has no effect if the keyboard is not grabbed by the client, or if the keyboard is not frozen as the result of an event.

       * :SYNC-BOTH -- If both pointer and keyboard are frozen by the client, event processing (for both devices) continues normally until the next :BUTTON-PRESS, :BUTTON-RELEASE, :KEY-PRESS, or :KEY-RELEASE event is reported to the client for a grabbed device (button event for the pointer, key event for the keyboard). At this time, the devices again appear to freeze. If the reported event causes the grab to be released, the devices do not freeze. However, if the other device is still grabbed, then a subsequent event for it will still cause both devices to freeze. :SYNC-BOTH has no effect unless both pointer and keyboard are frozen by the client. If the pointer of keyboard is frozen twice by the client on behalf of two separate grabs, :SYNC-BOTH thaws for both, but a subsequent freeze for :SYNC-BOTH will only freeze each device once.

       * :ASYNC-BOTH -- If the pointer and the keyboard are frozen by the client, event processing for both devices continues normally. If a device is frozen twice by the client on behalf of two separate grabs, :ASYNC-BOTH thaws for both. :ASYNC-BOTH has no effect unless both pointer and keyboard are frozen by the client.

     :ASYNC-POINTER, :SYNC-POINTER, and :REPLAY-POINTER have no effect on processing of keyboard events. :ASYNC-KEYBOARD, :SYNC-KEYBOARD, and :REPLAY-KEYBOARD have no effect on processing of pointer events.

     It is possible for both a pointer grab and a keyboard grab to be active simultaneously by the same or different clients. When a device is frozen on behalf of either grab, no event processing is performed for the device. It is possible for a single device to be frozen due to both grabs. In this case, the freeze must be released on behalf of both grabs before events can again be processed.

Resources
*********

Users need a way to specify preferences for various user interface values (for example, colors, fonts, title strings, and so forth). Applications need a consistent method for determining the default interface values that are specific to them. It is also useful if application interface values can be modified by users without changes to the program code. For example, this capability can make it easy to change the color scheme of a user interface. In CLX, such interface values are referred to as resources. CLX defines functions for storing and retrieving interface resources from a resource database. A user can store various user interface values as resources in a resource database; a CLX application can then read these resource values and modify its user interface accordingly.

NOTE: The general term resource refers to any application user interface value stored in a resource database. The term server resource is used more specifically to refer to the types of objects allocated by an X server and referenced by clients (for example, windows, fonts, graphics contexts, and so forth).

Resource Binings
================

Conceptually, a resource database is a set of resource name-value pairs (or resource bindings). The name in a resource binding is a list that is the concatenation of a path list and an attribute name.

A path list is a list of symbols (or strings) that corresponds to a path through a tree-structured hierarchy. For example, the path:

     '(top middle bottom)

corresponds to a three-level hierarchy in which middle is the child of top, and bottom is the child of middle.

Typically, the path of a resource name corresponds to a path in a hierarchy of windows, and each symbol/string names a window in the hierarchy. However, the first element of the path can also represent the overall name of the entire program, and subsequent path elements can refer to an application-specific hierarchy of resource names not strictly related to windows. In addition, a resource name can contain a partially-specified path list.  The asterisk symbol (*) is a wildcard that can correspond to any sequence of levels in the hierarchy (including the null sequence). For example, the path:

     '(top * bottom)

corresponds to a hierarchy of two or more levels in which top is at the top level and bot- tom is at the bottom level. An element of a path list can be the name of an individual window or the name of a class of windows.

The final element of a resource name list is an attribute name. This symbol (or string) identifies a specific attribute of the object(s) named by the preceding path list. The attribute name can also be the symbol * or the string "*", in which case the resource name refers to all attributes of the path object(s). However, this form of resource name is rarely useful.

Some examples of resource bindings are shown below. In these examples, assume that mail is the resource name of a mail reading application. mail uses a window of the class button whose name is reply.

(mail screen-1 reply background)   'green
(mail * background)   'red
(* button background)   'blue

These resource bindings specify the following:

  * The background attribute resource of mail application's reply button has the value of green on screen-1.

  * The background attribute for the rest of the mail application is always red on all screens.

  * In general, the background attribute for all button windows is blue.

Basic Resource Database Functions
=================================

A RESOURCE-DATABASE structure is a CLX object that represents a set of resource bindings. The following paragraphs describe the CLX functions used to:

  * Create a resource database

  * Add a resource binding

  * Remove a resource binding

  * Merge two resource databases

  * Map a function over the contents of a resource database

 -- Function: make-resource-database

     resource-database
          Type RESOURCE-DATABASE.

     Returns an empty resource database.

 -- Function: add-resource database name-list value

     database
          The RESOURCE-DATABASE for the new resource binding.

     name-list
          A list containing strings or symbols specifying the name for the resource binding.

     value
          The value associated with the name-list in the resource binding. This can be an object of any type.

     Adds the resource binding specified by name-list and value to the given database. Only one value can be associated with the name-list in the database. This function replaces any value previously associated with the name-list.

 -- Function: delete-resource database name-list

     database
          The RESOURCE-DATABASE containing the resource binding.

     name-list
          A list containing strings or symbols specifying the name for the deleted resource binding.

     Removes the resource binding specified by name-list from the given database.

 -- Function: map-resource database function &rest args

     database
          A RESOURCE-DATABASE.

     function
          A FUNCTION object or function symbol.

     args
          A list of arguments to the function.

     Calls the function for each resource binding in the database. For each resource binding consisting of a name-list and a value, the form (APPLY function name-list value args) is executed.

 -- Function: merge-resources from-database to-database

     from-database
          The RESOURCE-DATABASE from which resource bindings are read.

     to-database
          The RESOURCE-DATABASE to which resource bindings are added.

     Merges the contents of the from-database with the to-database. MAP-RESOURCE invokes ADD-RESOURCE in order to add each resource binding in the from-database to the to-database. The updated to-database is returned.

     to-database
          Type RESOURCE-DATABASE.

Accessing Resource Values
=========================

The power and flexibility of resource management is the result of the way resource values in a resource database are accessed. A resource binding binding stored in the database generally contains only a partial resource name consisting of a mixture of name and class identifiers and wildcard elements (that is, *). To look up a resource value, an application program starts with two resource name lists of the same length containing no wildcard elements -- a complete resource name and a complete resource class. The lookup algorithm returns the value for the resource binding whose resource name is the closest match to the complete name and class given. The definition of closest match takes into account the top-down, parent-child hierarchy of resource names and also the distinction between individual names and class names.

Complete Names and Classes
--------------------------

A resource binding contains a resource name list that can contain names, class names, or a mixture of both. A class name is a symbol or string that represents a group of related objects. The set of names used as class names are not specified by CLX. Instead, class names are defined by agreement between those who use class names when creating resource bindings (that is, users) and those who use class names when accessing resource values (that is, application programmers).

In order to access a value in a resource database, an application uses a key consisting of two items: a complete resource name and a complete resource class. A complete resource name is a resource name list containing no wildcard elements. A complete resource class is a list of exactly the same form. The distinction between a complete resource name and a complete resource class lies in how they are used to access resource bindings. The elements of a complete resource name are interpreted as names of individual objects; the elements of a complete resource class are interpreted as names of object classes. The complete resource name and class lists used in a resource database access must have the same length.

Like any resource name list, a complete resource name consists of a path list and an attribute name. The first path list element is typically a symbol (or string) identifying the application as a whole. The second element can be a screen root identifier. Subsequent elements can be identifiers for each ancestor window of an application window. Thus, a path list typically identifies a specific window by tracing a path to it through the application window hierarchy. The final element of a complete resource name (its attribute name) is typically the name of a specific attribute of the window given by the path list (for example, 'background). An attribute name can refer to a feature associated with the window by the application but not by the X server (for example, a font identifier).  Similarly, a complete resource class typically represents a path to a window in the application window hierarchy and a specific window attribute. However, a complete resource class contains the class name for each window and for the window attribute.

For instance, in the previous example, the mail application can attempt to look up the value of the background resource for the reply button window by using the following complete resource name:

     (mail screen-1 reply background)

and the following complete resource class:

     (application root button fill)

This complete resource name contains a path list identifying the reply button window -- (mail screen-1 reply) -- and an attribute name for the window background. The corresponding resource class contains the class names for the same path list and window attribute.

Matching Resource Names
-----------------------

The resource lookup algorithm searches a specified resource data base and returns the value for the resource binding whose resource name is the closest match to a given complete resource name and class. The intent of the lookup algorithm is to formalize an intuitive notion of the closest match.

Precedence is given to a match which begins higher in the parent-child contact hierarchy. This allows a resource binding with a partial name to define a resource value shared by all members of a window subtree. For example, suppose the resource database contained the following resource bindings:

(mail * background)   'red
(* reply background)   'blue

Suppose an application program searched by using the following complete resource name:

     (mail screen-1 reply background)

then the closest matching value returned would be 'red.

Precedence is given to the more specific match. A name match is more specific than a class match. Either a name or class match is more specific than a wildcard match. For example, suppose the resource database contained the following resource bindings:

(mail * background)   'red
(mail * fill)   'blue

Suppose an application program searched by using the following complete resource name and complete resource class:

     (mail screen-1 reply background)
     (application root button fill)

then the closest matching value returned would be 'red. However, suppose the resource database contained the following resource bindings:

(mail * background)   'red
(mail * button background)   'blue

then the closest matching value returned would be 'blue.

Resource Access Functions
-------------------------

The following paragraphs describe the CLX functions used to return a value from a resource database.

 -- Function: get-resource database attribute-name attribute-class path-name path-class

     database
          A RESOURCE-DATABASE.

     attribute-name
          A string or symbol giving an attribute name from a complete resource name.

     attribute-class
          A string or symbol giving an attribute class name from a complete resource class.

     path-name
          The path list from a complete resource name. path-name and path-class must have the same length.

     path-class
          The path list from a complete resource class. path-name and path-class must have the same length.

     Returns the value of the resource binding in the database whose resource name most closely matches the complete resource name/class given by the path-name, path-class, attribute-name, and attribute-class. The lookup algorithm implements the precedence rules described previously to determine the closest match. When comparing name elements, case is significant only if both elements are strings; otherwise, element matching is case-insensitive.

     value
          Type T.

 -- Function: get-search-table database path-name path-class

     database
          A RESOURCE-DATABASE.

     path-name
          The path list from a complete resource name. path-name and path-classmust have the same length.

     path-class
          The path list from a complete resource class. path-name and path-class must have the same length.

     Returns a table containing the subset of the database that matches the path-name and path-class. Resources using the same path-name and path-class can be accessed much more efficiently by using this table as an argument to GET-SEARCH-RESOURCE.

     search-table
          Type LIST.

 -- Function: get-search-resource table attribute-name attribute-class

     table
          A search table returned by GET-SEARCH-TABLE.

     attribute-name
          A string or symbol giving an attribute name from a complete resource name.

     attribute-class
          A string or symbol giving an attribute class name from a complete resource class.

     Returns the value of the resource binding in the search table that most closely matches the attribute-name and attribute-class. The table is computed by GET-SEARCH-TABLE and represents a set of resource bindings. The closest match is determined by the same algorithm used in GET-RESOURCE.

     The following two forms are functionally equivalent:

          (get-resource
           database attribute-name attribute-class path-name path-class)

          (get-search-resource
           (get-search-table database path-name path-class)
           attribute-name attribute-class)

     However, the hard part of the search is done by GET-SEARCH-TABLE. Looking up values for several resource attributes that share the same path list can be done much more efficiently with calls to GET-SEARCH-RESOURCE.

     value
          Type T.

Resource Database Files
=======================

X users and application programs can save resource bindings in a file, using a standard file format shared by all X clients. The following paragraphs describe the CLX functions used to convert between the standard external format of resource files and the internal resource-database format used by application programs.

 -- Function: read-resources database pathname &key :key :test :test-not

     database
          The RESOURCE-DATABASE to merge.

     pathname
          A pathname for the resource file to read.

     :key
          A function used to convert a value from the resource file into a resource binding value.

     :test
     :test-not
          Functions used to select which resource bindings from the resource file are merged with the database.

     Reads resource bindings from a resource file in standard X11 format and merges them with the given resource database. The :KEY function is called to convert a file resource value into the value stored in the database. By default, :KEY is #'IDENTITY. The :TEST and :TEST-NOT functions are predicates that select resource bindings to merge, based on the result of the :KEY function. For each file resource binding consisting of a resource-name and a resource-value, the :TEST (or :TEST-NOT) function is called with the arguments resource-name and (FUNCALL key resource-value).

     database
          Type RESOURCE-DATABASE.

 -- Function: write-resources database pathname &key :write :test :test-not

     database
          The RESOURCE-DATABASE to write.

     pathname
          A pathname of the file to write.

     :write
          A function for writing resource values.

     :test
     :test-not
          Functions used to select which resource bindings from the resource file are merged with the database.

     Writes resource bindings found in the database to the file given by the pathname. The output file is written in the standard X11 format. The :WRITE function is used for writing resource values; the default is #'PRINC. The :WRITE function is passed two arguments: a resource-value and a stream. The :TEST and :TEST-NOT functions are predicates which select resource bindings to write. For each resource binding consisting of a resource-name and a resource-value, the :TEST (or :TEST-NOT) function is called with the arguments resource-name and resource-value.

Control Functions
*****************

Grabbing the Server
===================

Certain cases may require that a client demand exclusive access to the server, causing the processing for all other clients to be suspended. Such exclusive access is referred to as grabbing the server. CLX provides functions to grab and release exclusive access to the server. These function should be used rarely and always with extreme caution, since they have the potential to disrupt the entire window system for all clients.

 -- Function: grab-server display

     display
          A DISPLAY.

     Disables processing of requests and close-downs on all connections other than the one on which this request arrived.

 -- Function: ungrab-server display

     display
          A DISPLAY.

     Restarts processing of requests and close-downs on other connections.

 -- Macro: with-server-grabbed display &body body

     Grabs the display server only within the dynamic extent of the body. UNGRAB-SERVER is automatically called upon exit from the body. This macro provides the most reliable way for CLX clients to grab the server.

     display
          A DISPLAY.

     body
          The forms to execute while the server is grabbed.

Pointer Control
===============

The following paragraphs describe the CLX functions used to:

  * Return or change the pointer acceleration and acceleration threshold

  * Return or change the mapping of pointer button numbers

 -- Function: change-pointer-control display &key :acceleration :threshold

     display
          A DISPLAY.

     :acceleration
          A number for the acceleration ratio.

     :threshold
          The number of pixels required for acceleration to take effect.

     Changes the acceleration and/or the acceleration threshold of the pointer for the display.  The :ACCELERATION number is used as a multiplier, typically specified as a rational number of the form C/P, where C is the number of pixel positions of cursor motion displayed for P units of pointer device motion. The acceleration only occurs if the pointer moves more that :THRESHOLD pixels at once, and only applies to the motion beyond the :THRESHOLD. Either :ACCELERATION or :THRESHOLD can be set to :DEFAULT, that restores the default settings of the server.

 -- Function: pointer-control display

     display
          A DISPLAY.

     Returns the acceleration and threshold for the display pointer.

     acceleration
     threshold
          Type NUMBER.

 -- Function: pointer-mapping display &key (:result-type 'list)

     display
          A DISPLAY.

     :result-type
          The type of sequence to return.

     Returns or (with setf) changes the mapping of button numbers for the display pointer.  The :RESULT-TYPE is not used when changing the mapping. If element i of the mapping sequence is j, then the events from pointer button j are reported by the server as events for button i+1. (Note that pointer buttons are numbered beginning with one, while the mapping sequence itself is indexed normally from zero.) If element i of the mapping sequence is zero, then button i+1 is disabled and can no longer generate input events. No two elements of the mapping can have the same non-zero value.

     The length of the mapping sequence indicates the actual number of buttons on the device. When changing the mapping, the new mapping must have this same length.

     mapping
          Type SEQUENCE or CARD8.

Keyboard Control
================

The following paragraphs describe the CLX functions used to:

  * Return or change keyboard controls

  * Ring the keyboard bell

  * Return or change the mapping of modifiers

  * Return the current up/down state of all keys

 -- Function: bell display &optional (percent-from-normal 0)

     display
          A DISPLAY.

     percent-from-normal
          An integer (-100 through 100).

     Rings the bell on the keyboard at a volume relative to the base volume for the keyboard, if possible. Percent can range from -100 to 100 inclusive, or else a Value error occurs. The following is the bell volume when percent is non-negative:

          (- (+ base percent) (QUOTIENT (* base percent) 100))

     and when percent is negative:

          (+ base (QUOTIENT (* base percent) 100))

 -- Function: change-keyboard-control display &key :key-click-percent :bell-percent :bell-pitch :bell-duration :led :led-mode :key :auto-repeat-mode

     display
          A DISPLAY.

     :key-click-percent
          An integer (0 100).

     :bell-percent
          An integer (0 100).

     :bell-pitch
          A CARD16.

     :bell-duration
          A CARD16.

     :led
          A CARD8.

     :led-mode
          Either :ON or :OFF.

     :key
          A CARD8 keycode.

     :auto-repeat-mode
          Either :ON, :OFF, or :DEFAULT.

     Changes the various aspects of the keyboard. The keyword arguments specify which controls to change.

     The :KEY-CLICK-PERCENT keyword sets the volume for key clicks, if possible. A value of 0 implies off, while a value of 100 implies loud. Setting :KEY-CLICK-PERCENT to :DEFAULT restores the default value.

     The :BELL-PERCENT sets the base volume for the bell between 0 (off) and 100 (loud) if possible. Setting :BELL-PERCENT to :DEFAULT restores the default value.

     The :BELL-PITCH sets the pitch (specified in Hz) of the bell, if possible. Setting the :BELL-PITCH to :DEFAULT restores the default value. The :BELL-DURATION sets the duration ( specified in milliseconds) of the bell, if possible. Setting :BELL-PITCH to :DEFAULT restores the default. Note that a bell generator connected with the console but not directly on the keyboard is treated as if it were part of the keyboard.

     If both :LED-MODE and :LED are specified, then the state of that LED is changed, if possible. If only :LED-MODE is specified, the state of all LEDs are changed, if possible. At most 32 LEDs are supported, numbered from one. No standard interpretation of the LEDs are defined.

     If both :AUTO-REPEAT-MODE and :KEY are specified, the auto-repeat mode of that key is changed, if possible. If only :AUTO-REPEAT-MODE is specified, the global auto-repeat mode for the entire keyboard is changed, if possible, without affecting the per-key settings. An error occurs if :KEY is specified without :AUTO-REPEAT-MODE.

 -- Function: keyboard-control display

     display
          A DISPLAY.

     Returns the current control values for the keyboard. For the LEDs, the least significant bit of led-mask corresponds to LED one, and each one bit in led-mask indicates an LED that is lit. auto-repeats is a bit vector; each one bit indicates that auto-repeat is enabled for the corresponding key. The vector is represented as 32 bytes. Byte n (from 0) contains the bits for keys 8n to 8n+7, with the least significant bit in the byte representing key 8n.

     key-click-percent
     bell-percent
          Type CARD8.

     bell-pitch
     bell-duration
          Type CARD16.

     led-mask
          Type CARD32.

     global-auto-repeat
          Either :ON or :OFF.

     auto-repeats
          Type BIT-VECTOR.

 -- Function: modifier-mapping display

     display
          A DISPLAY.

     Returns the set of keycodes used for each modifier on the display keyboard. Each return value is a list of the CARD8 keycodes used for each modifier key. The order of keycodes within each list is server-dependent.

     shift-keycodes
     lock-keycodes
     control-keycodes
     mod1-keycodes
     mod2-keycodes
     mod3-keycodes
     mod4-keycodes
     mod5-keycodes
          Type LIST of CARD8.

 -- Function: query-keymap display

     display
          A DISPLAY.

     Returns a bit vector that describes the state of the keyboard. Each one bit indicates that the corresponding key is currently pressed. The vector is represented as 32 bytes. Byte n (from 0) contains the bits for keys 8n to 8n+7, with the least significant bit in the byte representing key 8n.

     keymap
          Type BIT-VECTOR 256.

 -- Function: set-modifier-mapping display &key :shift :lock :control :mod1 :mod2 :mod3 :mod4 :mod5

     display
          A DISPLAY.

     :shift
     :lock
     :control
     :mod1
     :mod2
     :mod3
     :mod4
     :mod5
          A sequence of CARD8 keycodes for the given modifier.

     Changes the set of keycodes mapped to the specified modifier keys on the display keyboard. Each keyword argument contains a sequence of new CARD8 keycodes for a specific modifier. The return value indicates whether the change was completed successfully.

     A status of :FAILED is returned if hardware limitations prevent the requested change. For example, multiple keycodes per modifier may not be supported, up transitions on a given keycode may not be supported, or autorepeat may be mandatory for a given keycode. If :FAILED is returned, the mappings for all modifiers remain unchanged.

     A status of :DEVICE-BUSY is returned if a new keycode given for a modifier was not previously mapped to that modifier and is currently in the down state. In this case, the mappings for all modifiers remain unchanged.

     status
          One of :SUCCESS, :FAILED, or :DEVICE-BUSY.

Keyboard Encodings
==================

Handling the great diversity of keyboard devices and international language character encodings is a difficult problem for interactive programs that need to receive text input but must also be portable. The X Window System solves this problem by using different sets of encodings for device keys (keycodes) and for character symbols (keysyms). Each X server maintains a keyboard mapping that associates keycodes and keysyms, and which can be returned or changed by client programs.

To handle text input, a CLX client program must follow these steps:

 1. Receive a :KEY-PRESS (or :KEY-RELEASE) event containing a keycode.

 2. Convert the keycode into its corresponding keysym, based on the current keyboard mapping. See KEYCODE-&GT;KEYSYM.

 3. Convert the keysym into the corresponding Common Lisp character. See KEYSYM-&GT;CHARACTER.

Keycodes and Keysyms
--------------------

A keycode represents a physical (or logical) key. In CLX, keycodes are values of type (INTEGER 8 255). A keycode value carries no intrinsic information, although server implementors may attempt to encode geometry (for example, matrix) information in some fashion so it can be interpreted in a server- dependent fashion. The mapping between keys and keycodes cannot be changed.

A keysym is an encoding of a symbol on the cap of a key. In CLX, keysyms are values of type CARD32. The set of defined keysyms include the ISO Latin character sets (1-4), Katakana, Arabic, Cyrillic, Greek, Technical, Special, Publishing, APL, Hebrew, and miscellaneous keys found on keyboards (RETURN, HELP, TAB, and so on). The encoding of keysyms is defined by the X Protocol.

A list of keysyms is associated with each keycode. The length of the list can vary with each keycode. The list is intended to convey the set of symbols on the corresponding key. By convention, if the list contains a single keysym and if that keysym is alphabetic and case distinction is relevant, then it should be treated as equivalent to a two-element list of the lowercase and uppercase keysyms. For example, if the list contains the single keysym for uppercase A, the client should treat it as if it were a pair with lowercase as the first keysym and uppercase A as the second keysym.

For any keycode, the first keysym in the list should be chosen as the interpretation of a key press when no modifier keys are down. The second keysym in the list normally should be chosen when the :SHIFT modifier is on, or when the :LOCK modifier is on and :LOCK is interpreted as :SHIFT-LOCK. When the :LOCK modifier is on and is interpreted as :CAPS-LOCK, it is suggested that the :SHIFT modifier first be applied to choose a keysym, but if that keysym is lowercase alphabetic, the corresponding uppercase keysym should be used instead.

Other interpretations of :CAPS-LOCK are possible; for example, it may be viewed as equivalent to :SHIFT-LOCK, but only applying when the first keysym is lowercase alphabetic and the second keysym is the corresponding uppercase alphabetic. No interpretation of keysyms beyond the first two in a list is suggested here. No spatial geometry of the symbols on the key is defined by their order in the keysym list, although a geometry might be defined on a vendor-specific basis. The X server does not use the mapping between keycodes and keysyms. Rather, the X server stores the mapping merely for reading and writing by clients.

Keyboard Mapping
----------------

The X server maintains a keyboard mapping that associates each keycode with one or more keysyms. The following paragraphs describe the CLX functions used to return or change the mapping of keycodes.

 -- Function: change-keyboard-mapping display keysyms &key (:start 0) :end

     display
          A DISPLAY.

     keysyms
          A two-dimensional array of keysym (CARD32) values.

     :start
     :end
          Indexes for the subsequence of keysyms used.

     :first-keycode
          A CARD8 defining the first keycode mapping changed.

     (:FIRST-KEYCODE :START)

     Changes the mapping of keycodes to keysyms. A :MAPPING-NOTIFY event is generated for all clients.

     The new keysyms are specified as a two-dimensional array in which:

     (AREF keysyms (+ :START i) j)

     is keysym j associated with keycode (+ :FIRST-KEYCODE i). The maximum number of keysyms associated with any one keycode is given by:

     (ARRAY-DIMENSION keysyms 1)

     keysyms should contain NIL elements to represent those keysyms that are undefined for a given keycode. :START and :END define the subsequence of the keysyms array that defines the new mapping, and the number of keycode mappings changed. By default, :END is given by:

     (ARRAY-DIMENSION keysyms 0)

     The keycodes whose mappings are changed are given by :FIRST-KEYCODE through the following:

     (+ :FIRST-KEYCODE (- :END :START) -1)

     keycodes outside this range of are not affected. :FIRST-KEYCODE must not be less than (DISPLAY-MIN-KEYCODE display), and the last keycode modified must not be greater than (DISPLAY-MAX-KEYCODE display).

 -- Function: keyboard-mapping display &key :first-keycode :start :end :data

     display
          A DISPLAY.

     :first-keycode
          A CARD8 defining the first keycode mapping returned.

     :start
     :end
          Indexes for the subsequence of the returned array which is modified.

     :data
          If given, a two-dimensional array to receive the returned keysyms.

     Returns the keysyms mapped to the given range of keycodes for the display keyboard.  The mappings are returned in the form of a two-dimensional array of CARD32 keysym values. The :DATA argument, if given, must be a two-dimensional array in which the returned mappings will be stored. In this case:

     (ARRAY-DIMENSION :DATA 1)

     defines the maximum number of keysyms returned for any keycode. Otherwise, a new array is created and returned.

     Upon return:

     (AREF mappings (+ :start i) j)

     will contain keysym j associated with keycode (+ :FIRST-KEYCODE I) (or NIL, if keysym j is undefined for that keycode).

     :FIRST-KEYCODE specifies the first keycode whose mapping is returned; by default, :FIRST-KEYCODE is (DISPLAY-MIN-KEYCODE display). :START and :END define the subsequence of the returned array in which the returned mappings are stored. By default, :START is given by :FIRST-KEYCODE and :END is given by:

     (1+ (DISPLAY-MAX-KEYCODE display))

     :FIRST-KEYCODE must not be less than (DISPLAY-MIN-KEYCODE display), and the last keycode returned must not be greater than (DISPLAY-MAX-KEYCODE display).

     mappings
          Type (ARRAY CARD32 (* *)).

Using Keycodes and Keysyms
--------------------------

The following paragraphs describe the CLX functions used to:

  * Convert a keycode into a keysym

  * Convert a keysym into a character

 -- Function: keycode->keysym display keycode keysym-index

     display
          A DISPLAY.

     keycode
          A CARD8.

     keysym-index
          A CARD8.

     Returns the keysym at the given keysym-index from the keysym list for the keycode in the current keyboard mapping for the display server. This function was called keycode-keysym in X11R4 and older versions of CLX.

     keysym
          Type KEYSYM.

 -- Function: keysym->character display keysym &optional (state 0)

     display
          A DISPLAY.

     keysym
          A KEYSYM.

     state
          A MASK16.

     Returns the character associated with the keysym and the state. The state is a MASK16 bit mask representing the state of the display modifier keys and pointer buttons. See STATE-MASK-KEY in Data Types. If the keysym does not represent a Common Lisp character, then NIL is returned. This function was called keysym-character in X11R4 and older versions of CLX.

     The state determines the bits attribute of the returned character, as follows:

     :control
          CHAR-CONTROL-BIT

     :mod-1
          CHAR-META-BIT

     :mod-2
          CHAR-SUPER-BIT

     :mod-3
          CHAR-HYPER-BIT

     character
          Type CHARACTER or NULL.

Client Termination
==================

The CLX functions affecting client termination are discussed in the following paragraphs.

When a display connection to an X server is closed, whether by an explicit call to CLOSE-DISPLAY or by some external condition, the server automatically performs a sequence of operations to clean up server state information associated with the closed connection.  The effect of these operations depends the close-down mode and the save-set that the client has specified for the closed display connection. The close-down mode of a display determines whether server resources allocated by the connection are freed or not. The save-set identifies windows that will remain after the connection is closed.

The display save-set is used primarily by window managers that reparent the top-level windows of other clients. For example, such a window manager can automatically create a frame window that encloses a top-level client window, along with a set of controls used for window management. Ordinarily, termination of the window manager client would then destroy all client windows! However, the window manager can prevent this by adding to its save-set those windows created by other clients that should be preserved.

When a display connection closes, an X server performs the following operations:

 1. For each selection owned by a window created on the connection, the selection owner is set to NIL.

 2. An active or passive grab established for a window created on the connection is released.

 3. If the connection has grabbed the server, the server is ungrabbed.

 4. Server resources and colormap cells allocated by the connection are freed and destroyed, depending on the close-down mode, as follows:

       * :RETAIN-PERMANENT -- All resources are marked permanent, and no resources are destroyed. These resources can later be destroyed by a call to KILL-CLIENT.

       * :RETAIN-TEMPORARY -- All resources are marked temporary, and no resources are destroyed. These resources can later be destroyed by a call to KILL-CLIENT or KILL-TEMPORARY-CLIENTS.

       * :DESTROY -- All resources are destroyed.

When server resources allocated by a display connection are destroyed -- whether by closing the connection with close-down mode :DESTROY or by later calling KILL-CLIENT or KILL-TEMPORARY-CLIENTS -- then an X server performs the following operations on each member of the save-set before actually destroying resources.

 1. If the save-set window is a descendant of a window created on the connection, the save-set window is reparented. The new parent is the closest ancestor such that the save-set window is no longer a descendant of any window created on the connection. The position of the reparented window with respect to its parent remains unchanged.

 2. If the save-set window is unmapped, then it is mapped.

If the last connection open to an X server is closed with close-down mode :DESTROY, the server resets its state to restore all initial defaults. The server state after reset is the same as its initial state when first started. When an X server resets, it performs the following operations:

  * All permanent and temporary server resources from previously-closed connections are destroyed.

  * All but the predefined atoms are deleted.

  * All root window properties are deleted.

  * All device control attributes and mappings are restored to their original default values.

  * The default background and cursor for all root windows are restored.

  * The default font path is restored.

  * The input focus is set to :POINTER-ROOT.

  * The access control list is reset.

The following paragraphs describe the CLX functions used to:

  * Add or remove a window from a display save-set.

  * Return or change the display close-down mode.

  * Force a connection to be closed or all its server resources to be destroyed.

  * Force a connection to be closed and all temporary resources to be destroyed.

 -- Function: add-to-save-set window

     window
          A WINDOW.

     Adds the specified window to the save-set of the window display. The window must have been created by some other display. Windows are removed automatically from the save-set when they are destroyed.

 -- Function: close-down-mode display

     display
          A DISPLAY.

     Returns and (with setf) sets the close-down mode of the client's resources at connection close.

     mode
          One of :DESTROY, :RETAIN-PERMANENT, or :RETAIN-TEMPORARY.

 -- Function: kill-client display resource-id

     display
          A DISPLAY.

     resource-id
          A valid CARD29 resource ID.

     Closes the display connection which created the given resource-id. The resource-id must be valid, but need not belong to the given display.

     If the closed connection was previously open, the connection is closed according to its close-down mode. Otherwise, if the connection had been previously terminated with close-down mode :RETAIN-PERMANENT or :RETAIN-TEMPORARY, then all its retained server resources -- both permanent and temporary -- are destroyed.

 -- Function: kill-temporary-clients display

     display
          A DISPLAY.

     Closes the display connection and destroys all retained temporary server resources for this and all previously-terminated connections.

     If the display connection was previously open, the connection is closed according to its close-down mode. Otherwise, if the display connection had been previously terminated with close-down mode :RETAIN-PERMANENT or :RETAIN-TEMPORARY, then all its retained server resources -- both permanent and temporary -- are destroyed.

 -- Function: remove-from-save-set window

     window
          A WINDOW.

     Removes the specified window from the save-set of the window display. The window must have been created by some other display. Windows are removed automatically from the save-set when they are destroyed.

Managing Host Access
====================

An X server maintains a list of hosts from which client programs can be run. Only clients executing on hosts that belong to this access control list are allowed to open a connection to the server. Typically, the access control list can be changed by clients running on the same host as the server. Some server implementations can also implement other authorization mechanisms in addition to, or in place of, this mechanism.  The action of this mechanism can be conditional based on the authorization protocol name and data received by the server at connection setup.

The following paragraphs describe the CLX functions used to:

  * Add or remove hosts on the access control list.

  * Return the hosts on the access control list.

  * Return or change the state of the access control list mechanism

 -- Function: access-control display

     display
          A DISPLAY.

     Returns and (with setf) changes the state of the access control list mechanism for the display server. Returns true if access control is enabled; otherwise, NIL is returned. If enabled, the access control list is used to validate each client during connection setup.

     Only a client running on the same host as the server is allowed to enable or disable the access control list mechanism.

     enabled-p
          Type BOOLEAN.

 -- Function: access-hosts display &key (:result-type 'list)

     display
          A DISPLAY.

     :result-type
          The type of hosts sequence to return.

     Returns a sequence containing the hosts that belong to the access control list of the display server. Elements of the returned hosts sequence are either strings or some other type of object recognized as a host name by ADD-ACCESS-HOST and REMOVE-ACCESS-HOST.  The second returned value specifies whether the access control list mechanism is currently enabled or disabled (see ACCESS-CONTROL).

     hosts
          SEQUENCE of STRING.

     enabled-p
          Type BOOLEAN.

 -- Function: add-access-host display host

     display
          A DISPLAY.

     host
          A host name. Either a string or some other implementation-dependent type.

     Adds the specified host to the access control list. Only a client running on the same host as the server can change the access control list.

 -- Function: remove-access-host display host

     display
          A DISPLAY.

     host
          A host name. Either a string or some other implementation-dependent type.

     Removes the specified host from the access control list. Only a client running on the same host as the server can change the access control list.

Screen Saver
============

To prevent monitor damage, an X server implements a screen saver function which blanks screens during periods of unuse. The screen saver can be in one of three states:

  * Disabled -- No screen blanking is done and screen content remains unchanged.

  * Deactivated -- The server is being used. When the server input devices are unused for a specific amount of time, the screen saver becomes activated.

  * Activated -- The server input devices are unused. The screen saver blanks all server screens or displays a server-dependent image. As soon as an input event from either the pointer or the keyboard occurs, the screen saver is deactivated and its timer is reset.

The following paragraphs describe the CLX functions used to:

  * Return or change screen saver control values.

  * Activate or reset the screen saver

 -- Function: activate-screen-saver display

     display
          A DISPLAY.

     Activates the screen saver for the display server.

 -- Function: reset-screen-saver display

     display
          A DISPLAY.

     Deactivates the screen saver for the display server (if necessary) and resets its timer, just as if a pointer or keyboard event had occurred.

 -- Function: screen-saver display

     display
          A DISPLAY.

     Returns the current control values for the display server screen saver. See SET-SCREEN-SAVER.

     timeout
     period
          Type INT16.

     blanking
     exposures
          One of :YES or :NO.

 -- Function: set-screen-saver display timeout period blanking exposures

     display
          A DISPLAY.

     timeout
          Specifies the delay until timeout takes over.

     period
          Specifies the periodic change interval, if used.

     blanking
          Specifies whether the blanking option is available.

     exposures
          Specifies whether exposures are allowed during blanking.

     Changes the current control values for the display server screen saver. The screen saver is reset. The screen saver is also disabled if:

       * timeout is zero, or

       * Both blanking and exposures are disabled and the server cannot regenerate the screen contents without sending :EXPOSURE events.

     The timeout specifies the (non-negative) number of seconds of input device inactivity that must elapse before the screen saver is activated. The timeout can be set to :DEFAULT to restore the server default timeout interval.

     If blanking is :YES and the screen hardware supports blanking, blanking is enabled; that is, the screen saver will simply blank all screens when it is activated. blanking can be set to :DEFAULT to restore the server default state for blanking.

     If exposures is :YES, exposures are enabled. If exposures are enabled, or if the server is capable of regenerating screen contents without sending :EXPOSURE events, the screen saver will display some server-dependent image when activated. Frequently, this image will consist of a repeating animation sequence, in which case period specifies the ( non-negative) number of seconds for each repetition. A period of zero is a hint that no repetition should occur.

Extensions
**********

Extensions
==========

The X Window System is based on a core protocol which can be extended to provide new functionality. An extension is generally represented by an additional set of requests or event types that are implemented by an X server supporting the extension.  By definition, a client program using an extension may not be portable to other servers.  However, extensions allow different server implementations and different sites to add their own special features to X, without disrupting clients that rely only on the core protocol.

Extensions are identified by assigning them unique name strings and major protocol numbers. A client program can request an X server to use a protocol extension by furnishing the extension protocol number as an argument to OPEN-DISPLAY. The X Consortium maintains a registry of standard extension names and protocol numbers.

The following paragraphs describe the CLX functions used to:

  * List all supported extensions.

  * Find out if a given extension is supported.

 -- Function: list-extensions display &key (:result-type 'list)

     display
          A DISPLAY.

     :result-type
          The type of name sequence to return.

     Returns a sequence containing the names of all extensions supported by the display server.

     names
          Type SEQUENCE of STRING.

 -- Function: query-extension display name

     display
          A DISPLAY.

     name
          An extension name string.

     Returns the major-opcode for the given extension name support by the display server. If the extension is not supported, only NIL values are returned. The extension name must contain only ISO Latin-1 characters; case is significant.

     If the extension involves additional event types, the first-event returned is the base event type code for new events; otherwise, the first-event is NIL. If the extension involves additional error codes, the first-error returned is the base code for new errors; otherwise, the first-error is NIL. The formats of error and event messages sent by the server are completely defined by the extension.

     major-opcode
     first-event
     first-error
          Type CARD8 or NULL.

SHAPE - The X11 Nonrectangular Window Shape Extension
=====================================================

This documentation is yet to be written.

RENDER - A new rendering system for X11
=======================================

XRENDER is an experimental step in building a newer and modern graphics rendering system that can keep up with the demands of visual appearance on current user interfaces.

The X Rendering Extension (Render) introduces digital image composition as the foundation of a new rendering model within the X Window System. Rendering geometric figures is accomplished by client-side tesselation into either triangles or trapezoids.  Text is drawn by loading glyphs into the server and rendering sets of them.

Picture formats
---------------

The following is what the X protocol rendering spec has to say about picture formats. http://www.xfree86.org/~keithp/render/protocol.html

The PICTURE-FORMAT object holds information needed to translate pixel values into red, green, blue and alpha channels.  The server has a list of picture formats corresponding to the various visuals on the screen.  There are two classes of formats, Indexed and Direct.  Indexed picture-formats hold a list of pixel values and RGBA values while Direct picture-formats hold bit masks for each of R, G, B and A.

The server must support a direct PICTURE-FORMAT with 8 bits each of red, green, blue and alpha as well as a direct PICTURE-FORMAT with 8 bits of red, green and blue and 0 bits of alpha.  The server must also support direct PICTURE-FORMATs with 1, 4 and 8 bits of alpha and 0 bits of r, g and b.

Pixel component values lie in the closed range [0,1].  These values are encoded in a varying number of bits.  Values are encoded in a straight forward manner.  For a component encoded in m bits, a binary encoding b is equal to a component value of b/(2^m-1).

A direct PICTURE-FORMAT with zero bits of alpha component is declared to have alpha == 1 everywhere.  A direct PICTURE-FORMAT with zero bits of red, green and blue is declared to have red, green, blue == 0 everywhere.  If any of red, green or blue components are of zero size, all are of zero size.  Direct PICTURE-FORMATs never have colormaps and are therefore screen independent.

Indexed PICTURE-FORMATs never have alpha channels and the direct component is all zeros.  Indexed PICTURE-FORMATs always have a colormap in which the specified colors are allocated read- only and are therefore screen dependent.

These are valid accessors for picture-format objects.

picture-format-display
     A display

picture-format-id
     The X protocol RESOURCE-ID

picture-format-type
     (member :indexed :direct)

picture-format-depth
     Bitdepth as CARD8

picture-format-red-byte
     A bitmask

picture-format-green-byte
picture-format-blue-byte
picture-format-alpha-byte
picture-format-colormap
     A COLORMAP or nil

The picture object
------------------

The PICTURE object contains a DRAWABLE, a PICTURE-FORMAT and some rendering state.  More than one PICTURE can refer to the same DRAWABLE.

A PICTURE is almost like a GCONTEXT, except that it is tied in use to a single DRAWABLE. Another similarity it has with GCONTEXT is that it is a cached object. Updates are not processed until the PICTURE is used. This also makes it possible to query state, as there is no such request in XRENDER to do so.

The PICTURE object is also a lot like a DRAWABLE, in that it is used as a target for graphics operations. Or at least that it occurs where you would expect a drawable in XRENDER requests.

 -- Function: render-create-picture drawable &key format picture ...

     drawable
          A DRAWABLE

     format
          A PICTURE-FORMAT

     picture
          An existing PICTURE object to use, one is created if not specified.

     repeat
          (member :off :on)

     alpha-map
          A PICTURE or :NONE

     alpha-x-origin
          INT16

     alpha-y-origin
          INT16

     clip-x-origin
          INT16

     clip-y-origin
          INT16

     clip-mask
          A PIXMAP or :NONE

     graphics-exposures
          (member :off :on)

     subwindow-mode
          (member :clip-by-children :include-inferiors)

     poly-edge
          (member :sharp :smooth)

     poly-mode
          (member :precise :imprecise)

     dither
          XATOM or :NONE

     component-alpha
          (member :off :on)

     This request creates a Picture object.  If the drawable is a Window then the Red, Green and Blue masks must match those in the visual for the window else a Match error is generated.

     picture
          A PICTURE

 -- Function: render-free-picture picture This request deletes all server resources associated with the picture object.

     picture
          The PICTURE object to free

Glyphs and Glyphsets
--------------------

A glyph in XRENDER is an alpha mask and an associated orgin, advancement and numeric id. The application refers to them by the numeric id.

Glyphs are stored in a glyph-set. The client is responsible for making sure the glyphs it uses are stored in the glyph-set, or there will be a Glyph-error.

 -- Function: render-create-glyph-set format &key glyph-set

     format
          A PICTURE-FORMAT for the alpha masks that this font will use.

     glyph-set
          An optional GLYPH-SET object to initialize with a server side glyphset resource.

     Creates an initially empty glyph-set for the client to use. Format must be a Direct format. When it contains RGB values, the glyphs are composited using component-alpha True, otherwise they are composited using component-alpha False.

 -- Function: render-reference-glyph-set existing-glyph-set &key glyph-set

     existing-glyph-set
          An existing GLYPH-SET

     glyph-set
          An optional GLYPH-SET, just like in RENDER-CREATE-GLYPH-SET

     Creates a new id refering to the existing-glyph-set. The glyph-set itself will not be freed until all ids has been removed.

 -- Function: render-free-glyph-set glyph-set

     glyph-set
          A glyphset resource to free

     Removes an id to a glyph-set. When all ids have been removed the glyph-set itself is removed.

 -- Function: render-add-glyph glyph-set id &key x-origin y-origin x-advance y-advance data

     glyph-set
          A GLYPH-SET

     id
          CARD32

     x-orgin
          INT16

     y-orgin
          INT16

     x-advance
          INT16

     y-advance
          INT16

     data
          An ARRAY of CARD8 bytes.

     Associates id with the given description of a glyph. An existing glyph with the same id is replaced.

     At the time of writing, only 8bit alpha masks are supported. Experimentation with glyph-sets in other pict-formats needed.

 -- Function: render-add-glyph-from-picture glyph-set picture &key x-origin y-origin x-advance y-advance width height

     glyph-set
          glyph-set

     picture
          picture

     x-origin
          int16

     y-origin
          int16

     x-advance
          int16

     y-advance
          int16

     x
          int16

     y
          int16

     width
          card16

     height
          card16

     This request add a glyph to glyph-set by copying it from the x,y location in the picture.

     Existing glyphs with the same names are replaced. The source picture may be in a different PICTURE-FORMAT than glyph-set, in which case the images are converted to the glyph-set's format.

 -- Function: render-free-glyphs glyph-set glyphs

     glyph-set
          A GLYPH-SET

     glyphs
          sequence of CARD32

     This request removes glyphs from glyph-set. Each glyph must exist in glyph-set (else a MATCH error results).

Using glyphs
------------

 -- Function: render-composite-glyph dest glyph-set source dest-x dest-y sequence &key op src-x src-y mask-format start end

     dest
          picture

     glyph-set
          glyph-set

     source
          picture

     dest-x
          int16

     dest-y
          int16

     sequence

     op
          (member clear :src :dst :over :over-reverse :in :in-reverse :out :out-reverse :atop :atop-reverse :xor :add :saturate :maximum)

     src-x
          int16

     src-y
          iny16

     mask-format
          picture-format

     start
          blah

     end
          blah

     Requests the sequence of glyphs to be drawn with the glyph-set.

Errors
------

What new errors Xrender defines...

DPMS - The X11 Display Power Management Signaling Extension
===========================================================

 -- Function: dpms-get-version display &optional (major-version 1) (minor-version 1)

     display
          DISPLAY

     major-version
          CARD16

     minor-version
          CARD16

     Return two values: the major and minor version of the DPMS implementation the server supports.

     If supplied, the MAJOR-VERSION and MINOR-VERSION indicate what version of the protocol the client wants the server to implement.

 -- Function: dpms-capable display

     display
          DISPLAY

     True if the currently running server's devices are capable of DPMS operations.

     The truth value of this request is implementation defined, but is generally based on the capabilities of the graphic card and monitor combination.  Also, the return value in the case of heterogeneous multi-head servers is implementation defined.

 -- Function: dpms-get-timeouts display

     display
          DISPLAY

     Return three values: the current values of the DPMS timeout values. The timeout values are (in order returned): standby, suspend and off. All values are in units of seconds.  A value of zero for any timeout value indicates that the mode is disabled.

 -- Function: dpms-set-timeouts display standby suspend off

     display
          DISPLAY

     standby
          CARD16

     suspend
          CARD16

     off
          CARD16

     Set the values of the DPMS timeouts.  All values are in units of seconds.  A value of zero for any timeout value disables that mode.

 -- Function: dpms-enable display

     display
          DISPLAY

     Enable the DPMS characteristics of the server using the server's currently stored timeouts.  If DPMS is already enabled, no change is affected.

 -- Function: dpms-disable display

     display
          DISPLAY

     Disable the DPMS characteristics of the server.  It does not affect the core or extension screen savers.  If DPMS is already disabled, no change is effected.

     This request is provided so that DPMS may be disabled without damaging the server's stored timeout values.

 -- Function: dpms-force-level display power-level

     display
          DISPLAY

     power-level
          (member :dpms-mode-on :dpms-mode-standby :dpms-mode-suspend :dpms-mode-off)

     Forces a specific DPMS level on the server.

 -- Function: dpms-info display

     display
          DISPLAY

     Returns two values: the DPMS power-level and state value for the display.

     State is one of the keywords DPMS-ENABLED or DPMS-DISABLED.

     If state is DPMS-ENABLED, then power-level is returned as one of the keywords DPMS-MODE-ON, DPMS-MODE-STANDBY, DPMS-MODE-SUSPEND or DPMS-MODE-OFF.  If state is DPMS-DISABLED, then power-level is undefined and returned as NIL.

BIG-REQUESTS - Big Requests Extension
=====================================

 -- Function: display-extended-max-request-length display

 -- Function: enable-big-requests display

Errors
******

Introduction
============

CLX error conditions are hierarchial. The base error condition is X-ERROR, and all other conditions are built on top of X-ERROR. X-ERROR can be built on a lower-level condition that is implementation dependent (this is probably the ERROR condition).

 -- Macro: define-condition name (parent-types*) [(slot-specifier*) option*]

     Any new condition type must be defined with the DEFINE-CONDITION macro. A condition type has a name, parent types, report message, and any number of slot items. See the Lisp Reference manual for further information regarding DEFINE-CONDITION.

     The following are the predefined error conditions that can occur in CLX.

 -- Condition: access-error

     An ACCESS-ERROR can occur for several reasons:

       * A client attempted to grab a key/button combination already grabbed by another client

       * A client attempted to free a colormap entry that it did not already allocate

       * A client attempted to store into a read-only colormap entry

       * A client attempted to modify the access control list from other than the local (or otherwise authorized) host

       * A client attempted to select an event type that another client has already selected, and, that at most, one client can select at a time

     An ACCESS-ERROR is a special case of the more general REQUEST-ERROR (see request-error).

 -- Condition: alloc-error

     The server failed to allocate the requested resource or server memory.

     An ALLOC-ERROR is a special case of the more general REQUEST-ERROR (see request-error).

 -- Condition: atom-error

     A value for an atom argument does not name a defined atom.

     An ATOM-ERROR is a special case of the more general REQUEST-ERROR (see request-error).

 -- Condition: closed-display

     The CLOSED-DISPLAY condition is signaled when trying to read or write a closed display (that is, CLOSE-DISPLAY has been called on the DISPLAY object, or a server-disconnect occurred). The CLOSED-DISPLAY object is reported with the error.

     A CLOSED-DISPLAY condition is a special case of the more general X-ERROR (see x-error).

 -- Condition: colormap-error

     A value for a colormap argument does not name a defined colormap.

     A COLORMAP-ERROR is a special case of the more general RESOURCE-ERROR (see resource-error).

 -- Condition: connection-failure

     Signaled when an X11 server refuses a connection. The following items are reported along with the error:

       * major-version -- The major version of the X server code.

       * minor-version -- The minor version of the X server code.

       * host -- The host name for the X server.

       * display -- The display on which the error occurred.

       * reason -- A string indicating why the connection failed.

     A CONNECTION-FAILURE is a special case of the more general X-ERROR (see x-error).

 -- Condition: cursor-error

     A value for a cursor argument does not name a defined cursor.

     A CURSOR-ERROR is a special case of the more general RESOURCE-ERROR (see resource-error).

 -- Condition: device-busy

     Signaled by (setf (POINTER-MAPPING display) MAPPING) when the SET-POINTER-MAPPING request returns a busy status. A similar condition occurs in SET-MODIFIER-MAPPING, but in this case, it returns a boolean indicating success, rather than signaling an error.  The DEVICE-BUSY condition returns the display object as part of the error.

     A DEVICE-BUSY condition is a special case of the more general X-ERROR (see x-error).

 -- Condition: drawable-error

     A value for a drawable argument does not name a defined window or pixmap.

     A DRAWABLE-ERROR is a special case of the more general RESOURCE-ERROR (see resource-error).

 -- Condition: font-error

     A value for a font or gcontext argument does not name a defined font.

     A FONT-ERROR is a special case of the more general RESOURCE-ERROR (see resource-error).

 -- Condition: gcontext-error

     A value for a gcontext argument does not name a defined GContext.

     A GCONTEXT-ERROR is a special case of the more general RESOURCE-ERROR (see resource-error).

 -- Condition: id-choice-error

     The value chosen for a resource identifier is either not included in the range assigned to the client or is already in use. Under normal circumstances, this cannot occur and should be considered a server or CLX library error.

     An ID-CHOICE-ERROR is a special case of the more general RESOURCE-ERROR (see resource-error).

 -- Condition: implementation-error

     The server does not implement some aspect of the request. A server that generates this error for a core request is deficient. As such, this error is not listed for any of the requests.  However, clients should be prepared to receive such errors and either handle or discard them.

     An IMPLEMENTATION-ERROR is a special case of the more general RESOURCE-ERROR (see resource-error).

 -- Condition: length-error

     The length of a request is shorter or longer than that minimally required to contain the arguments. This usually means an internal CLX error.

     A LENGTH-ERROR is a special case of the more general RESOURCE-ERROR (see resource-error).

 -- Condition: lookup-error

     CLX has the option of caching different resource types (see *CLX-CACHED-TYPES*) in a hash table by resource ID. When looking up an object in the hash table, if the type of the object is wrong, a LOOKUP-ERROR is signaled.

     For example: The cursor with ID 123 is interned in the hash table. An event is received with a field for window 123. When 123 is looked up in the hash table, a cursor is found.  Since a window was expected, a LOOKUP-ERROR is signaled. This error indicates a problem with the extension code being used. The following items are reported along with the error:

       * id -- The resource ID.

       * display -- The display being used.

       * type -- The resource type.

       * object -- The RESOURCE object.

     A LOOKUP-ERROR is a special case of the more general X-ERROR (see x-error).

 -- Condition: match-error

     In a graphics request, the root and depth of the GContext does not match that of the drawable. An :INPUT-ONLY window is used as a drawable. Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request. An :INPUT-ONLY window locks this attribute. The values do not exist for an :INPUT-ONLY window.

     A MATCH-ERROR is a special case of the more general REQUEST-ERROR (see request-error).

 -- Condition: missing-parameter

     One or more of the required keyword parameters is missing or NIL. The missing parameters are reported along with the error.

     A MISSING-PARAMETER condition is a special case of the more general X-ERROR (see x-error).

 -- Condition: name-error

     A font or color of the specified name does not exist.

     A NAME-ERROR is a special case of the more general REQUEST-ERROR (see request-error).

 -- Condition: pixmap-error

     A value for a pixmap argument does not name a defined pixmap.

     A PIXMAP-ERROR is a special case of the more general RESOURCE-ERROR. (see resource-error.)

 -- Condition: reply-length-error (x-error) (slots*)

     The reply to a request has an unexpected length. The following items are reported along with the error:

       * reply-length -- The actual reply length.

       * expected-length -- The expected reply length.

       * display -- The display on which the error occurred.

     A REPLY-LENGTH-ERROR is a special case of the more general X-ERROR (see x-error).

 -- Condition: reply-timeout

     The *REPLY-TIMEOUT* parameter specifies the maximum number of seconds to wait for a request reply, or NIL to wait forever (the default). When a reply has not been received after *REPLY-TIMEOUT* seconds, the REPLY-TIMEOUT condition is signaled. The timeout period and display are reported along with the error.

     A REPLY-TIMEOUT condition is a special case of the more general X-ERROR (see x-error).

 -- Condition: request-error

     The following items are reported along with the error:

     The major or minor opcode does not specify a valid request.

       * display -- The display on which the error occurred.

       * error-key -- The error (sub)type.

       * major -- The major opcode.

       * minor -- The minor opcode.

       * sequence -- The actual sequence number.

       * current-sequence -- The current sequence number.

     A REQUEST-ERROR condition is a special case of the more general X-ERROR (see x-error).

 -- Condition: resource-error

     All X11 errors for incorrect resource IDs are built on top of RESOURCE-ERROR. These are COLORMAP-ERROR, CURSOR-ERROR, DRAWABLE-ERROR, FONT-ERROR, GCONTEXT-ERROR, ID-CHOICE-ERROR, PIXMAP-ERROR and WINDOW-ERROR. RESOURCE-ERROR is never signaled directly.

     A RESOURCE-ERROR is a special case of the more general REQUEST-ERROR (see request-error).

 -- Condition: sequence-error

     All X11 request replies contain the sequence number of their request. If a reply's sequence does not match the request count, a SEQUENCE-ERROR is signaled. A SEQUENCE-ERROR usually indicates a locking problem with a multi-processing Lisp. The following items are reported along with the error:

       * display -- The display on which the error occurred.

       * req-sequence -- The sequence number in the reply.

       * msg-sequence -- The current sequence number.

     A SEQUENCE-ERROR condition is a special case of the more general X-ERROR. (see x-error)

 -- Condition: server-disconnect

     The connection to the server was lost. The display on which the error occurred is reported along with the error.

     A SERVER-DISCONNECT condition is a special case of the more general X-ERROR. (see x-error)

 -- Condition: unexpected-reply

     A reply was found when none was expected. This indicates a problem with the extension code. The following items are reported along with the error:

     display
          The display on which the error occurred.

     req-sequence
          The sequence number in the reply.

     msg-sequence
          The current sequence number.

     length
          The message length of the reply.

     An UNEXPECTED-REPLY condition is a special case of the more general X-ERROR. (see x-error.)

 -- Condition: unknown-error (request-error) (error-code)

     An error was received from the server with an unknown error code. This indicates a problem with the extension code. The undefined error code is reported.

     An UNKNOWN-ERROR is a special case of the more general REQUEST-ERROR. (see request-error)

 -- Condition: value-error (request-error) (value)

     Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. The erroneous value is reported.

     A VALUE-ERROR is a special case of the more general REQUEST-ERROR. (see request-error)

 -- Condition: window-error (resource-error)

     A value for a window argument does not name a defined window.

     A WINDOW-ERROR is a special case of the more general RESOURCE-ERROR. (see resource-error.)

 -- Condition: x-error

     This is the most general error condition upon which all other conditions are defined.

Undocumented
************

This section just lists all symbols exported from the XLIB package but not documented in this manual.

 -- Function: bitmap-image &optional plist &rest patterns

 -- Function: character->keysyms character &optional display

 -- Function: character-in-map-p display character keymap

     display
          A DISPLAY.

 -- Function: decode-core-error display event &optional arg

 -- Function: default-error-handler display error-key &rest key-vals &key asynchronous &allow-other-keys

 -- Function: default-keysym-index display keycode state

 -- Function: default-keysym-translate display state object

 -- Function: define-keysym object keysym &key lowercase translate modifiers mask display

 -- Function: define-keysym-set set first-keysym last-keysym

 -- Function: display-invoke-after-function display

     Explicitly invokes the after-function of the display. (see DISPLAY-AFTER-FUNCTION). This function is internally called after every request.

 -- Function: display-nscreens display

 -- Function: display-release-number object

 -- Function: event-handler handlers event-key

 -- Function: get-external-event-code display event

 -- Function: get-standard-colormap window property

 -- Function: get-wm-class window

 -- Function: icon-sizes window

 -- Function: iconify-window window screen

 -- Function: keysym->keycodes display keysym

 -- Function: keysym-in-map-p display keysym keymap

 -- Function: keysym-set keysym

 -- Function: mapping-notify display request start count

     Called on a :MAPPING-NOTIFY event to update the keyboard-mapping cache in display.

 -- Function: no-operation display

 -- Function: parse-color colormap spec

 -- Function: resource-database-timestamp database

 -- Function: resource-key stringable

 -- Function: rgb-colormaps window property

 -- Function: root-resources screen &key database key test test-not

     Returns a resource database containing the contents of the root window RESOURCE_MANAGER property for the given screen. If screen is a display, then its default screen is used. If an existing database is given, then resource values are merged with the database and the modified database is returned.

     test and test-not are predicates for selecting which resources are read. Arguments are a resource name list and a resource value. The key function, if given, is called to convert a resource value string to the value given to test or test-not.

 -- Function: rotate-cut-buffers display &optional (delta 1) (careful-p t)

 -- Function: set-access-control display enabled-p

 -- Function: set-close-down-mode display mode

 -- Function: set-pointer-mapping display map

 -- Function: set-selection-owner display selection owner &optional time

 -- Function: set-standard-colormap window property colormap base-pixel max-color mult-color

 -- Function: set-standard-properties window &rest options

 -- Function: set-wm-class window resource-name resource-class

 -- Function: set-wm-properties window &rest options &key name icon-name resource-name resource-class command client-machine hints normal-hints zoom-hints (user-specified-position-p nil usppp) (user-specified-size-p nil usspp) (program-specified-position-p nil psppp) (program-specified-size-p nil psspp) x y width height min-width min-height max-width max-height width-inc height-inc min-aspect max-aspect base-width base-height win-gravity input initial-state icon-pixmap icon-window icon-x icon-y icon-mask window-group

 -- Function: set-wm-resources database window &key write test test-not

 -- Function: transient-for window

 -- Function: translate-default src src-start src-end font dst dst-start

 -- Function: undefine-keysym object keysym &key display modifiers &allow-other-keys

 -- Function: visual-info-blue-mask object

 -- Function: visual-info-green-mask object

 -- Function: visual-info-red-mask object

 -- Function: window-cursor window

 -- Function: window-visual-info window

 -- Function: withdraw-window window screen

 -- Function: wm-client-machine window

 -- Function: wm-colormap-windows window

 -- Function: wm-command window

 -- Function: wm-hints window

 -- Function: wm-hints-flags object

 -- Function: wm-icon-name window

 -- Function: wm-name window

 -- Function: wm-normal-hints window

 -- Function: wm-protocols window

 -- Function: wm-resources database window &key key test test-not

 -- Function: wm-zoom-hints window

Glossary
********

access control list
     X maintains a list of hosts from which client programs can be run. By default, only programs on the local host can use the display, plus any hosts specified in an initial list read by the server. This access control list can be changed by clients on the local host. Some server implementations can also implement other authorization mechanisms in addition to or in place of this mechanism. The action of this mechanism can be conditional based on the authorization protocol name and data received by the server at connection setup.

action
     A function that is designed to handle an input event. CLUE input processing consists of matching an event with an event specification found in a contact's EVENT-TRANSLATIONS slot and then calling actions associated with the matching event specification.

active grab
     A grab is active when the pointer or keyboard is actually owned by the single grabbing client.

ancestors
     If W is an inferior of A, then A is an ancestor of W.

atom
     A unique ID corresponding to a string name. Atoms are used to identify properties, types, and selections.

backing store
     When a server maintains the contents of a window, the off-screen saved pixels are known as a backing store.

before action
     An action of a CONTACT-DISPLAY that is called when an event is dispatched to a contact, but before any other contact input processing is performed.

bit gravity
     When a window is resized, the contents of the window are not necessarily discarded. It is possible to request the server to relocate the previous contents to some region of the window. This attraction of window contents for some location of a window is known as bit gravity.

bitmap
     A pixmap of depth one.

button grabbing
     Buttons on the pointer can be passively grabbed by a client. When the button is pressed, the pointer is then actively grabbed by the client.

byte order
     For image (pixmap/bitmap) data, byte order is defined by the server, and clients with different native byte ordering must swap bytes as necessary. For all other parts of the protocol, the byte order is defined by the client, and the server swaps bytes as necessary.

callback
     A function that represents a connection between a contact and the rest of an application program. A contact calls a callback function in order to report the results of the user interface component that it represents.

children
     First-level subwindows of a window.

class event
     Event translations that belong to all instances of a contact class. A class event TRANSLATIONS translation is created by the DEFEVENT macro.

class resources
     Resources defined for each instance of a contact class. Also see constraint resources.

click
     A :BUTTON-PRESS event followed immediately by a :BUTTON-RELEASE event for the same button, with no intervening change in pointer position or modifier key state.

client
     An application program connects to the window system server by some interprocess communication (IPC) path, such as a TCP connection or a shared memory buffer. This program is referred to as a client of the window system server. More precisely, the client is the IPC path itself. A program with multiple paths open to the server is viewed as multiple clients by the protocol. Resource lifetimes are controlled by connection lifetimes, not by program lifetimes.

clipping regions
     In a graphics context, a bitmap or list of rectangles can be specified to restrict output to a particular region of the window. The image defined by the bitmap or rectangles is called a clipping region.

colormap
     A set of entries defining color values. The colormap associated with a window is used to display the contents of the window. Each pixel value indexes the colormap to produce RGB values that drive the guns of a monitor. Depending on hardware limitations, one or more colormaps can be installed at one time, such that windows associated with those maps display with correct colors.

composite
     A subclass of CONTACT representing contacts that are the parents of other contacts. A composite provides geometry management and input focus management services for the contacts that are its children.

complete resource class
     A list of symbols containing the class of the contact, the class of the contact's PARENT (and so on), and the class of the CONTACT-DISPLAY to which the contact belongs.  The complete resource class is one of the two items used as a key by a CLUE application in order to access a contact resource value in a resource database.

complete resource name
     A list of symbols containing the NAME of the contact, the NAME of the contact's PARENT (and so on), and the name of the CONTACT-DISPLAY to which the contact belongs. The complete resource name is one of the two items used as a key by a CLUE application in order to access a contact resource value in a resource database.

connection
     The IPC path between the server and client program. A client program typically has one connection to the server over which requests and events are sent.

constraint resources
     Resources defined for each child belonging to a member of a composite class.  Constraint resources are typically used to control the parent's geometry management policy.  Also see class resources.

contact
     The basic CLUE object for programming a user interface.

contact-display
     The CLUE object type that represents a connection to an X server and that supports an event loop for application input.

contact initialization
     The process of collecting initial values for all contact attributes. No server resources (windows and so on) are actually allocated until contact realization.

contact realization
     The process of allocating contact resources. This process completes contact creation.

containment
     A window contains the pointer if the window is viewable and the hot spot of the cursor is within a visible region of the window or a visible region of one of its inferiors. The border of the window is included as part of the window for containment. The pointer is in a window if the window contains the pointer but no inferior contains the pointer.

content
     The single child of a shell. The basic geometry management policy implemented by the SHELL class constrains a shell and its content to have the same width and height; size changes to one are automatically applied to the other.

coordinate system
     The coordinate system has x horizontal and y vertical, with the origin [0, 0] at the upper left. Coordinates are discrete and are in terms of pixels. Each window and pixmap has its own coordinate system. For a window, the origin is at the inside upper left, inside the border.

cursor
     The visible shape of the pointer on a screen. It consists of a hot-spot, a source bitmap, a shape bitmap, and a pair of colors. The cursor defined for a window controls the visible appearance when the pointer is in that window.

depth
     The depth of a window or pixmap is number of bits per pixel it has. The depth of a graphics context is the depth of the drawables it can be used in conjunction with for graphics output.

descendant
     If W is an inferior of A, then W is a descendant of A.

device
     Keyboards, mice, tablets, track-balls, button boxes, and so forth, are all collectively known as input devices. The core protocol only deals with two devices: the keyboard and the pointer.

direct color
     A class of colormap in which a pixel value is decomposed into three separate subfields for indexing. One subfield indexes an array to produce red intensity values, the second subfield indexes a second array to produce blue intensity values, and the third subfield indexes a third array to produce green intensity values. The RGB values can be changed dynamically.

dispatching an event
     The process of finding the appropriate contact and its actions.

double-click
     A sequence of two clicks of the same button in rapid succession.

drawable
     Both windows and pixmaps can be used as sources and destinations in graphics operations. These are collectively known as drawables. However, an :INPUT-ONLY window cannot be used as a source or destination in a graphics operation.

event
     Clients receive information asynchronously via events. These events can be either asynchronously generated from devices, or generated as side effects of client requests.  Events are grouped into types; events are never sent to a client by the server unless the client has specifically asked to be informed of that type of event, but clients can force events to be sent to other clients. Events are typically reported relative to a window.

event compression
     Ignoring (or compressing) certain redundant input events. Compression of redundant events is controlled by the class slots COMPRESS-EXPOSURES and COMPRESS-MOTION, which are shared by all instances of a contact class.

event loop
     The fundamental application control structure: wait for an event, figure out how to handle it, process the event, then go back and wait for the next one. In CLUE, the event loop is implemented using the PROCESS-NEXT-EVENT function.

event mask
     Events are requested relative to a window. The set of event types a client requests relative to a window are described using an event mask.

event propagation
     Device-related events propagate from the source window to ancestor windows until some client has expressed interest in handling that type of event, or until the event is discarded explicitly.

event specification
     A notation for describing a certain sort of event. CLUE input processing consists of matching an event with an event specification found in a contact's EVENT-TRANSLATIONS slot and then calling actions associated with the matching event specification.

event synchronization
     Certain race conditions are possible when demultiplexing device events to clients (in particular deciding where pointer and keyboard events should be sent when in the middle of window management operations). The event synchronization mechanism allows synchronous processing of device events.

event source
     The smallest window containing the pointer is the source of a device related event.

event translation
     The process of determining which contact action functions will be executed. An event translation is a list found in a contact's EVENT-TRANSLATIONS slot associating an event specification with one or more action names. Also see class event translations.

exposure event
     Servers do not guarantee to preserve the contents of windows when windows are obscured or reconfigured. Exposure events are sent to clients to inform them when contents of regions of windows have been lost.

extension
     Named extensions to the core protocol can be defined to extend the system. Extension to output requests, resources, and event types are all possible, and expected.

focus window
     Another term for the input focus.

font
     A matrix of glyphs (typically characters). The protocol does no translation or interpretation of character sets. The client simply indicates values used to index the glyph array. A font contains additional metric information to determine inter-glyph and inter-line spacing.

geometry management
     The process whereby a composite controls the geometrical properties of its child contacts; the composite is referred to as the geometry manager.

glyph
     An image, typically of a character, in a font.

grab
     Keyboard keys, the keyboard, pointer buttons, the pointer, and the server can be grabbed for exclusive use by a client. In general, these facilities are not intended to be used by normal applications but are intended for various input and window managers to implement various styles of user interfaces.

gcontext
     Shorthand for graphics context.

graphics context
     Various information for graphics output is stored in a graphics context (or gcontext), such as foreground pixel, background pixel, line width, clipping region, and so forth. A graphics context can only be used with drawables that have the same root and the same depth as the graphics context.

gray scale
     A degenerate case of pseudo color, in which the red, green, and blue values in any given colormap entry are equal, thus producing shades of gray. The gray values can be changed dynamically.

hot spot
     A cursor has an associated hot spot that defines a point in the cursor that corresponds to the coordinates reported for the pointer.

identifier
     Each resource has an identifier, a unique value associated with it that clients use to name the resource. An identifier can be used over any connection to name the resource.

inferiors
     All of the subwindows nested below a window: the children, the children's children, and so on.

initialization
     See contact initialization.

input event
     See event.

input focus
     Normally a window defining the scope for processing of keyboard input. If a generated keyboard event would normally be reported to this window or one of its inferiors, the event is reported normally; otherwise, the event is reported with respect to the focus window. The input focus also can be set such that all keyboard events are discarded and that the focus window is dynamically taken to be the root window of whatever screen the pointer is on at each keyboard event.

input-only window
     A window that cannot be used for graphics requests. input-only windows are invisible, and can be used to control such things as cursors, input event generation, and grabbing.  input-only windows cannot have input/output windows as inferiors.

input/output window
     The normal kind of opaque window, used for both input and output. Input/output windows can have both input/output and input-only windows as inferiors.

insensitivity
     See sensitivity.

interactive-stream
     A contact subclass designed to integrate CLUE with the conventional stream-based I/O of Common Lisp.

key grabbing
     Keys on the keyboard can be passively grabbed by a client. When the key is pressed, the keyboard is then actively grabbed by the client.

keyboard grabbing
     A client can actively grab control of the keyboard, and key events will be sent to that client rather than the client to which the events would normally have been sent.

keysym
     An encoding of a symbol on a keycap on a keyboard.

managed
     A contact under geometry management control.

mapped
     A window is said to be mapped if a map call has been performed on it. Unmapped windows and their inferiors are never viewable or visible.

modifier keys
     SHIFT, CONTROL, META, SUPER, HYPER, ALT, Compose, Apple, CAPS LOCK, Shift Lock, and similar keys are called modifier keys.

monochrome
     A special case of static gray, in which there are only two colormap entries.

obscure
     A window is obscured if some other window obscures it. For example, window A obscures window B if:

       * Both windows are viewable :INPUT-OUTPUT windows

       * Window A is higher in the global stacking order than window B

       * The rectangle defined by the outside edges of window A intersects the rectangle defined by the outside edges of window B

     Notice that window borders are included in the calculation, and that a window can be obscured and yet still have visible regions. See occlude (there is a fine distinction between obscure and occlude).

occlude
     A window is occluded if some other window occludes it. For example, window A occludes window B if:

       * Both windows are mapped

       * Window A is higher in the global stacking order than window B

       * The rectangle defined by the outside edges of window A intersects the rectangle defined by the outside edges of window B

     Notice that window borders are included in the calculation. See obscure (there is a fine distinction between occlude and obscure).

override-shell
     A subclass of SHELL used to override the window manager. This subclass contains pop-up menus and other temporary objects that the user can never resize and so on.

padding
     Some padding bytes are inserted in the data stream to maintain alignment of the protocol requests on natural boundaries. This increases ease of portability to some machine architectures.

parent window
     If C is a child of P, then P is the parent of C.

passive grab
     Grabbing a key or button is a passive grab. The grab activates when the key or button is actually pressed.

pixel value
     An n-bit value, where n is the number of bit planes used in (that is, the depth of) a particular window or pixmap. For a window, a pixel value indexes a colormap to derive an actual color to be displayed.

pixmap
     A three dimensional array of bits. A pixmap is normally thought of as a two dimensional array of pixels, where each pixel can be a value from 0 to (2n)-1, where n is the depth (z axis) of the pixmap. A pixmap can also be thought of as a stack of n bitmaps.

plane
     When a pixmap or window is thought of as a stack of bitmaps, each bitmap is called a plane or bit plane.

plane mask
     Graphics operations can be restricted to only affect a subset of bit planes of a destination.  A plane mask is a bit mask describing which planes are to be modified, and it is stored in a graphics context.

pointer
     The pointing device attached to the cursor and tracked on the screens.

pointer grabbing
     A client can actively grab control of the pointer, and button and motion events will be sent to that client rather than the client to which the events would normally have been sent.

pointing device
     Typically a mouse or tablet, or some other device with effective dimensional motion.  There is only one visible cursor defined by the core protocol, and it tracks whatever pointing device is attached as the pointer.

pop-up
     One of the uses of a top-level shell (for example, a menu that pops up when a command button contact is activated). Setting the STATE of a shell to :MAPPED is sometimes referred to as mapping or popping up the shell. Setting the STATE of a shell to :WITHDRAWN or :ICONIC is sometimes referred to as unmapping or popping down the shell.

property
     Windows can have associated properties, consisting of a name, a type, a data format, and some data. The protocol places no interpretation on properties; they are intended as a general-purpose naming mechanism for clients. For example, clients might share information such as resize hints, program names, and icon formats with a window manager via properties.

property list
     The list of properties that have been defined for a window.

pseudo color
     A class of colormap in which a pixel value indexes the colormap to produce independent red, green, and blue values. That is, the colormap is viewed as an array of triples (RGB values). The RGB values can be changed dynamically.

realization
     See contact realization.

redirecting control
     Window managers (or client programs) may choose to enforce window layout policy in various ways. When a client attempts to change the size or position of a window, the operation can be redirected to a specified client, rather than the operation actually being performed.

reply
     Information requested by a client program is sent back to the client with a reply. Both events and replies are multiplexed on the same connection. Most requests do not generate replies. However, some requests generate multiple replies.

representation type
     The type of representation of a resource value. For example, a color value might be represented either as a namestring ("red"), a pixel value, an RGB triplet, an HSV triplet, and so on.

request
     A command to the server is called a request. It is a single block of data sent over a connection.

resource
     A value of the user interface that can be changed by the user in a resource database via CLX functions ADD-RESOURCE, GET-RESOURCE, and so forth. See server resource.

resource class, complete
     See complete resource class.

resource database
     Conceptually, a set of resource name/value pairs (or resource bindings). CLX defines functions for storing and retrieving interface resources from a resource database.

resource name, complete
     See complete resource name.

RGB values
     Red, green, and blue intensity values used to define color. These values are always represented as 16-bit unsigned numbers, with zero being the minimum intensity and 65535 being the maximum intensity. The values are scaled by the server to match the display hardware.

root
     A special composite contact used to represent an entire display screen.

root window
     Each screen has a root window covering it. It cannot be reconfigured or unmapped, but otherwise acts as a full-fledged window. A root window has no parent.

save set
     The save set of a client is a list of other client's windows that, if they are inferiors of one of the client's windows at connection close, should not be destroyed and that should be remapped if it is unmapped. Save sets are typically used by window managers to avoid lost windows if the manager should terminate abnormally.

scanline
     A list of pixel or bit values viewed as a horizontal row (all values having the same y coordinate) of an image, with the values ordered by increasing x coordinate.

scanline order
     An image represented in scanline order contains scanlines ordered by increasing y coordinate.

screen
     A server can provide several independent screens, which typically have physically independent monitors. This would be the expected configuration when there is only a single keyboard and pointer shared among the screens.

selection

     A selection can be thought of as an indirect property with dynamic type. That is, rather than having the property stored in the server, it is maintained by some client (the owner).  A selection is global in nature, being thought of as belonging to the user (but maintained by clients), rather than being private to a particular window subhierarchy or a particular set of clients. When a client asks for the contents of a selection, it specifies a selection target type. This target type can be used to control the transmitted representation of the contents.

     For example, if the selection is "the last thing the user clicked on" and that is currently an image, then the target type might specify whether the contents of the image should be sent in XY Format or Z Format. The target type can also be used to control the class of contents transmitted; that is, asking for the looks (fonts, line spacing, indentation, and so forth) of a paragraph selection, rather than the text of the paragraph. The target type can also be used for other purposes; the semantics is not constrained by the protocol.

sensitivity
     A condition in which a user interface component of an application will accept input.  Conversely, when a contact is insensitive, events of particular types are not dispatched to the contact and are ignored.

server
     The server provides the basic windowing mechanism. It handles IPC connections from clients, demultiplexes graphics requests onto the screens, and multiplexes input back to the appropriate clients.

server grabbing
     The server can be grabbed by a single client for exclusive use. This prevents processing of any requests from other client connections until the grab is complete. This is typically only a transient state for such things as rubber-banding and pop-up menus, or to execute requests indivisibly.

server resource
     Windows, pixmaps, cursors, fonts, gcontexts, and colormaps are known as resources.  They all have unique identifiers associated with them for naming purposes. The lifetime of a resource is bounded by the lifetime of the connection over which the resource was created. See resource.

shell
     A composite that handles the duties required by standard conventions for top-level X windows.

sibling
     Children of the same parent window are known as sibling windows.

static color
     A degenerate case of pseudo color in which the RGB values are predefined and read-only.

static gray
     A degenerate case of gray scale in which the gray values are predefined and read-only.  The values are typically (near-)linear increasing ramps.

stacking order
     Sibling windows can stack on top of each other. Windows above both obscure and occlude lower windows. This is similar to paper on a desk. The relationship between sibling windows is known as the stacking order.

state
     A slot of CONTACT that controls the visual effect of the contact.

stipple
     A bitmap that is used to tile a region to serve as an additional clip mask for a fill operation with the foreground color.

tile
     A pixmap can be replicated in two dimensions to tile a region. The pixmap itself is also known as a tile.

timer
     A CLUE object that provides support for animation and other types of time-sensitive user interfaces. A timer causes :TIMER events to be dispatched to a specific contact for processing.

timestamp
     A time value, expressed in milliseconds, typically since the last server reset. Timestamp values wrap around (after about 49.7 days). The server, given its current time is represented by timestamp T, always interprets timestamps from clients by treating half of the timestamp space as being earlier in time than T and half of the timestamp space as being later in time than T. One timestamp value (named CurrentTime) is never generated by the server; this value is reserved for use in requests to represent the current server time.

top-level contact
     A contact whose parent is a root. A top-level contact is usually a composite at the top of a hierarchy of other contacts created by an application program.

top-level-session
     A subclass of SHELL that is used to communicate with a session manager.

top-level-shell
     A subclass of SHELL that provides full window manager interaction.

transient-shell
     A subclass of SHELL that a window manager typically will unmap when its owner becomes unmapped or iconified and will not allow to be individually iconified.

true color
     A degenerate case of direct color in which the subfields in the pixel value directly encode the corresponding RGB values. That is, the colormap has predefined read-only RGB values. The values are typically (near-)linear increasing ramps.

type
     An arbitrary atom used to identify the interpretation of property data. Types are completely uninterpreted by the server; they are solely for the benefit of clients.

unmanaged
     A contact that is not under geometry management control.

user interface
     A set of abstract interface objects used to control the dialog between an application and its human user.

viewable
     A window is viewable if it and all of its ancestors are mapped. This does not imply that any portion of the window is actually visible. Graphics requests can be performed on a window when it is not viewable, but output will not be retained unless the server is maintaining backing store.

visible
     A region of a window is visible if someone looking at the screen can actually see it; that is, the window is viewable and the region is not occluded by any other window.

window gravity
     When windows are resized, subwindows can be repositioned automatically relative to some position in the window. This attraction of a subwindow to some part of its parent is known as window gravity.

window manager
     Manipulation of windows on the screen, and much of the user interface (policy) is typically provided by a window manager client.

window manager shell
     A subclass of SHELL called WM-SHELL that interacts with the window manager.

XY Format
     The data for a pixmap is said to be in XY Format if it is organized as a set of bitmaps representing individual bit planes, with the planes appearing from most to least significant in bit order.

Z Format
     The data for a pixmap is said to be in Z Format if it is organized as a set of pixel values in scanline order.