\input texinfo   @c -*-texinfo-*-
@c $Id: clx.texinfo,v 1.3 2004/11/18 12:01:48 dan Exp $
@c %**start of header
@setfilename clx.info
@settitle Common LISP X Interface
@setchapternewpage odd
@c %**end of header

@dircategory lisp
@direntry
* CLX: (clx).           Common LISP X Interface
@end direntry

@copying
The Common LISP X Interface (CLX)

Copyright @copyright{} 1988, 1989 Texas Instruments Incorporated

@quotation
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.
@end quotation

@end copying

@titlepage
@title The Common Lisp X Interface (CLX)

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Acknowledgments, (dir), (dir)
@top The Common LISP X Interface (CLX)

@insertcopying
@end ifnottex

@menu
* Acknowledgments::
* Introduction to CLX::
* Displays::
* Screens::
* Windows and Pixmaps::
* Graphics Contexts::
* Graphic Operations::
* Images::
* Font and Characters::
* Colors::
* Cursors::
* Atoms::
* Events and Input::
* Resources::
* Control Functions::
* Extensions::
* Errors::
* Undocumented::
* Glossary::
* Function Index::
* Type Index::

@detailmenu
 --- The Detailed Node Listing ---

Introduction to CLX

* The X Window System::
* A Quick Tour of CLX::
* Naming and Argument Conventions::
* Programming Considerations::
* Data Types::

The X Window System

* Windows::
* Input Events::

A Quick Tour of CLX

* A Simple Menu::
* Displaying the Menu::
* Menu Input::
* The Main Program::
* Debugging With CLX::

Displays

* Opening the Display::
* Display Attributes::
* Managing the Output Buffer::
* Closing the Display::

Screens

* Screens and Visuals::
* Screen Attributes::

Windows and Pixmaps

* Drawables::
* Creating Windows::
* Window Attributes::
* Stacking Order::
* Window Hierarchy::
* Mapping Windows::
* Destroying Windows::
* Pixmaps::

Graphics Contexts

* Creating Graphics Contexts::
* Graphics Context Attributes::
* Copying Graphics Contexts::
* Destroying Graphics Contexts::
* Graphics Context Cache::

Graphic Operations

* Area and Plane Operations::
* Drawing Points::
* Drawing Lines::
* Drawing Rectangles::
* Drawing Arcs::
* Drawing Text::

Images

* Image Types::
* Image Functions::
* Image Files::
* Direct Image Transfer::

Image Types

* Basic Images::
* XY-Format Images::
* Z-Format Images::

Font and Characters

* Opening Fonts::
* Listing Fonts::
* Font Attributes::
* Chracter Attributes::
* Querying Text Size::

Colors

* Colormaps and Colors::
* Color Functions::
* Colormap Functions::

Colormap Functions

* Creating Colormaps::
* Installing Colormaps::
* Allocating Colors::
* Finding Colors::
* Changing Colors::
* Colormap Attributes::

Cursors

* Creating Cursors::
* Cursor Functions::
* Cursor Attributes::

Atoms, Properties and Selections

* Atoms (Atoms)::
* Properties::
* Selections::

Events and Input

* Selecting Events::
* Processing Events::
* Managing the Event Queue::
* Sending Events::
* Pointer Position::
* Managing Input Focus::
* Grabbing the Pointer::
* Grabbing a Button::
* Grabbing the Keyboard::
* Grabbing a Key::
* Event Types::
* Releasing Queued Events::

Event Types

* Keyboard and Pointer Events::
* Input Focus Events::
* Keyboard and Pointer State Events::
* Exposure Events::
* Window State Events::
* Structure Control Events::
* Client Communications Events::
* Declaring Event Types::

Resources

* Resource Binings::
* Basic Resource Database Functions::
* Accessing Resource Values::
* Resource Database Files::

Accessing Resource Values

* Complete Names and Classes::
* Matching Resource Names::
* Resource Access Functions::

Control Functions

* Grabbing the Server::
* Pointer Control::
* Keyboard Control::
* Keyboard Encodings::
* Client Termination::
* Managing Host Access::
* Screen Saver::

Keyboard Encodings

* Keycodes and Keysyms::
* Keyboard Mapping::
* Using Keycodes and Keysyms::

Extensions

* Extensions (Extensions)::
* SHAPE - The X11 Nonrectangular Window Shape Extension::
* RENDER - A new rendering system for X11::
* DPMS - The X11 Display Power Management Signaling Extension::  
* BIG-REQUESTS - Big Requests Extension::  

RENDER - A new rendering system for X11

* Picture formats::
* The picture object::
* Glyphs and Glyphsets::
* Using glyphs::
* Errors (Extensions)::

Errors

* Introduction (Errors)::

@end detailmenu
@end menu

@node Acknowledgments, Introduction to CLX, Top, Top
@chapter Acknowledgments

Primary Interface Author:

Robert W. Scheifler

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

Primary Implementation Author:

LaMott Oren

@display
Texas Instruments
PO Box 655474, MS 238
Dallas, TX 75265
@email{oren@@csc.ti.com}
@end display



Design Contributors:

@itemize @bullet
@item Dan Cerys, BBN
@item Scott Fahlman, CMU
@item Kerry Kimbrough, Texas Instruments
@item Chris Lindblad, MIT
@item Rob MacLachlan, CMU
@item Mike McMahon, Symbolics
@item David Moon, Symbolics
@item LaMott Oren, Texas Instruments
@item Daniel Weinreb, Symbolics
@item John Wroclawski, MIT
@item Richard Zippel, Symbolics
@end itemize

Documentation Contributors:

@itemize @bullet
@item Keith Cessna, Texas Instruments
@item Kerry Kimbrough, Texas Instruments
@item Mike Myjak
@item LaMott Oren, Texas Instruments
@item Dan Stenger, Texas Instruments
@end itemize

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.

@node Introduction to CLX, Displays, Acknowledgments, Top
@chapter 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:

@itemize @bullet
@item Overview of the X Window System
@item Naming and argument conventions
@item Programming considerations
@end itemize

@menu
* The X Window System::
* A Quick Tour of CLX::
* Naming and Argument Conventions::
* Programming Considerations::
* Data Types::
@end menu

@node The X Window System, A Quick Tour of CLX, Introduction to CLX, Introduction to CLX
@section 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:

@table @asis
@item 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.

@item 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.

@item 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.

@item Multitasking
Support multiple applications being displayed simultaneously.

@item 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.

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

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

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

Some of these goals lead directly to the basic X architecture -- the
client-server model. The basic window system is implemented by the X
@emph{server} program. An application program (the @emph{client})
sends window system @emph{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 @emph{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 @emph{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.

@menu
* Windows::
* Input Events::
@end menu

@node Windows, Input Events, The X Window System, The X Window System
@subsection Windows

The X Window System supports one or more screens containing
overlapping windows and subwindows. A @emph{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 @emph{display}.

All windows in an X server are arranged in a strict hierarchy. At the
top of the hierarchy are the @emph{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, @emph{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 @emph{pixmaps} for off-screen storage
of graphics. Single-plane pixmaps (that is, of depth 1) are sometimes
referred to as @emph{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
@emph{tiles}. Windows and pixmaps together are referred to as
@emph{drawables}.

@node Input Events,  , Windows, The X Window System
@subsection 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 @var{:enter-notify}
(@pxref{:enter-notify}) event
when the pointer cursor moves into a certain window. Another vital
message from the server is an @var{:exposure}
(@pxref{: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 @emph{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.

@node A Quick Tour of CLX, Naming and Argument Conventions, The X Window System, Introduction to CLX
@section 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.

@menu
* A Simple Menu::
* Displaying the Menu::
* Menu Input::
* The Main Program::
* Debugging With CLX::
@end menu

@node A Simple Menu, Displaying the Menu, A Quick Tour of CLX, A Quick Tour of CLX
@subsection 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.

@lisp
(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
@end lisp


The @code{window} slot will contain the
@var{window} (@pxref{window})
object that represents the menu. The @code{item-}
@code{alist} represents the relationship between the menu items
and their associated subwindows. Each entry in @code{item-alist}
is a list whose first element is a (sub)window object and whose second
element is the corresponding item string. A
@var{window} (@pxref{window})
object is an instance of a CLX-defined data type which represents X
windows. A
@var{window} (@pxref{window})
object actually carries two pieces of information: an X window ID
integer and a
@var{display} (@pxref{display})
object. A
@var{display} (@pxref{display})
is another CLX-defined data type that represents a connection to a
specific X display server. The @code{gcontext} slot contains an
instance of a CLX data type known as a @emph{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
@code{gcontext} will thus hold all of the attribute values used
during menu display.

The first thing to do is make an instance of a @code{menu} object:

@lisp
(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))))
@end lisp

@var{create-window} (@pxref{create-window})
is one of the most important CLX functions, since it creates and returns
a @var{window} (@pxref{window})
object. Several of its options are shown here. The default window class
is @var{:input-output}, but X provides for @var{:input-only} windows,
too. Every window must have a parent window, except for a system-defined
@emph{root window}, which represents an entire display screen. The
@var{:event-mask} keyword value, a CLX
@var{event-mask} (@pxref{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 @var{: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 @var{:override-redirect} turned on for the menu window? This is
actually a little unusual, because it prevents any window manager client
from @emph{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 @code{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
@var{create-window} (@pxref{create-window}),
demonstrating the equal treatment of parent and children windows in the
X window hierarchy.

@lisp
(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)))))
@end lisp

@node Displaying the Menu, Menu Input, A Simple Menu, A Quick Tour of CLX
@subsection Displaying the Menu

The @code{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
@var{text-extents} (@pxref{text-extents})
function.
@var{text-extents} (@pxref{text-extents})
returns the geometry of a given string as displayed in a given font.
Notice the use of the
@var{with-state} (@pxref{with-state})
macro when setting a window's geometry attributes. CLX strives to
preserve the familiar @code{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.
@var{with-state} (@pxref{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.

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

@lisp
(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))))
@end lisp

Of course, the sample client must know how to draw/redraw the menu and
its items, so the function @code{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.

@lisp
(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))))))
@end lisp

@var{with-gcontext} (@pxref{with-gcontext})
is a CLX macro that allows you temporarily to modify a graphics context
within the dynamic scope of the macro body.
@var{draw-image-glyphs} (@pxref{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
@emph{glyphs} instead of @emph{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,
@var{draw-image-glyphs} (@pxref{draw-image-glyphs}),
@var{text-extents} (@pxref{text-extents}),
and other CLX text functions accept a @var{: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 @var{char-code} to compute an index into the current font.

@node Menu Input, The Main Program, Displaying the Menu, A Quick Tour of CLX
@subsection Menu Input

Now that a menu can be displayed, the sample client program must define
how the menu will process user input. The @code{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
@var{event-case} (@pxref{event-case})
macro continues reading an event from the menu window's display object
until one of its clauses returns non-@var{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 @var{event-window}
receiving the event. Notice that the @var{:force-output-p} option is
enabled, causing
@var{event-case} (@pxref{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.

@lisp
(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)))
@end lisp

The event loop in @code{menu-choose} demonstrates an idiom used in
all X programs: the contents of a window are displayed (in this case, by
calling @code{menu-refresh}) only when an
@var{:exposure} (@pxref{:exposure})
event is received, signaling that the server has actually made the
window @emph{viewable}. The handling of
@var{:exposure} (@pxref{:exposure})
in @code{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
@var{:exposure} (@pxref{: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
@code{menu-refresh}.

@node The Main Program, Debugging With CLX, Menu Input, A Quick Tour of CLX
@subsection 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.

@lisp
(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))))
@end lisp

Note that the main program event loop lies in the body of an
@var{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 @emph{server resources} it has
created. Server resources are CLX objects which refer to objects
actually stored on the X server. Examples of these are
@var{window} (@pxref{window}),
@var{font} (@pxref{font}),
@var{pixmap} (@pxref{pixmap}),
@var{cursor} (@pxref{cursor}),
@var{colormap} (@pxref{colormap}),
and
@var{gcontext} (@pxref{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.
@var{gcontext} (@pxref{gcontext})
objects are not ordinarily shared between client applications.

@node Debugging With CLX,  , The Main Program, A Quick Tour of CLX
@subsection 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
@var{display-force-output} (@pxref{display-force-output}).
This function @emph{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,
@var{get-property} (@pxref{get-property}).
Certain output requests can cause input events to be sent. For example,
@var{map-window} (@pxref{map-window})
can cause
@var{:exposure} (@pxref{:exposure})
events to be sent. Synchronizing output with the resulting input can be
done with the
@var{display-finish-output} (@pxref{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.

@node Naming and Argument Conventions, Programming Considerations, A Quick Tour of CLX, Introduction to CLX
@section 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:

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

@item
The @emph{display} argument, where used, is always first in the
argument list.

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

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

@item
Source arguments always precede the destination arguments in the
argument list.

@item
The @emph{x} argument always precedes the @emph{y} argument in the
argument list.

@item
The @emph{width} argument always precedes the @emph{height} argument
in the argument list.

@item
Where the @emph{x}, @emph{y}, @emph{width} and @emph{height} arguments
are used together, the @emph{x} and @emph{y} arguments always precede
the @emph{width} and @emph{height} arguments.

@item
Where a @emph{mask} is accompanied with a @emph{structure}, the mask
always precedes the structure in the argument list.
@end itemize

@node Programming Considerations, Data Types, Naming and Argument Conventions, Introduction to CLX
@section Programming Considerations

The major programming considerations are as follows:

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

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

@item
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.

@item
Coordinates and sizes in X are actually 16-bit quantities. They
usually are declared as an
@var{int16} (@pxref{int16}) in
the functions. Values larger than 16 bits can be truncated silently.
Sizes (width and height) are unsigned quantities.

@item
The types
@var{color} (@pxref{color}),
@var{colormap} (@pxref{colormap}),
@var{cursor} (@pxref{cursor}),
@var{display} (@pxref{display}),
@var{font} (@pxref{font}),
@var{gcontext} (@pxref{gcontext}),
@var{pixmap} (@pxref{pixmap}),
@var{screen} (@pxref{screen}),
and
@var{window} (@pxref{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 @var{defun.} (It is a requirement that they be
functions as opposed to macros or special forms.)
@end itemize

@node Data Types,  , Programming Considerations, Introduction to CLX
@section Data Types


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

@deftp {Type} alist (key-type-and-name datum-type-and-name) 'list
@var{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 (@emph{type} @emph{name}).
@end deftp


@deftp {Type} angle `(number ,(* -2pi) ,(* 2pi))
@var{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.
@end deftp


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


@deftp {Type} array-index `(integer 0 ,array-dimension-limit)
@var{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.
@end deftp


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

@emph{gravity} -- One of the following:
@itemize @c menu

@item @var{:center}
@item @var{:north}
@item @var{:south}
@item @var{:static}

@item @var{:east}
@item @var{:north-east}
@item @var{:south-east :west}

@item @var{:forget}
@item @var{:north-west}
@item @var{:south-west}
@end itemize

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
@var{window-bit-gravity}, in @ref{Window Attributes}, for additional
information.

@end deftp



@deftp {Type} bitmap '(array bit (* *))
Specifies a two-dimensional array of bits.
@end deftp


@deftp {Structure} bitmap-format

A structure that describes the storage format of a bitmap.

The @var{bitmap-format} structure contains slots for @var{unit},
@var{pad}, and @var{lsb-first-p}. The @var{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 @var{pad} member
indicates how many bits are needed to pad the left edge of the
scan-line. The @var{lsb-first-p} member is a predicate which
indicates the ordering of bits with the bitmap unit.

@end deftp


@deftp {Slot of bitmap-format} unit

Type: (@var{member} 8 16 32).

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

@end deftp



@deftp {Slot of bitmap-format} pad

Type: (@var{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.
@end deftp


@deftp {Slot of bitmap-format} lsb-first-p

Type: @var{boolean}.

A predicate indicating whether the least significant bit comes first
(@var{true}) or not (@var{nil}).
@end deftp


@deftp {Type} boolean '(or nil (not nil))
@var{boolean} defines a type which is all inclusive. It is used for
variables that can take on a true (non-@var{nil}) or false
(@var{nil}) value.
@end deftp

@deftp {Type} boole-constant `(member value*)

@var{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.

@emph{value} -- One of the following:
@itemize @c menu

@item @var{boole-1}
@item @var{boole-c1}
@item @var{boole-nand}
@item @var{boole-xor}

@item @var{boole-2}
@item @var{boole-c2}
@item @var{boole-nor}

@item @var{boole-and}
@item @var{boole-clr}
@item @var{boole-orc1}

@item @var{boole-andc1}
@item @var{boole-eqv}
@item @var{boole-orc2}

@item @var{boole-andc2}
@item @var{boole-ior}
@item @var{boole-set}
@end itemize
@end deftp


@deftp {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.
@end deftp


@deftp {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.
@end deftp


@deftp {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.
@end deftp


@deftp {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.
@end deftp


@deftp {Type} color '(satisfies color-p)
@anchor{color}
A @var{color}. @xref{Color Functions}, for additional
information.
@end deftp


@deftp {Type} colormap '(satisfies colormap-p)
@anchor{colormap}
A @var{colormap}. @xref{Colormap Functions}, for
additional information.
@end deftp


@deftp {Type} cursor '(satisfies cursor-p)
@anchor{cursor}
A @var{cursor}. @xref{Cursors}, for additional information.
@end deftp


@deftp {Type} device-event-mask '(or mask32 (list device-event-mask-class))
@anchor{event-mask}

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.
@end deftp


@deftp {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 @var{event-mask-class}.

@emph{event} -- One of the following:
@itemize @c menu

@item @var{:button-1-motion}
@item @var{:button-motion}

@item @var{:button-2-motion}
@item @var{:button-press}

@item @var{:button-3-motion}
@item @var{:key-press}

@item @var{:button-4-motion}
@item @var{:key-release}

@item @var{:button-5-motion}
@item @var{:pointer-motion}
@end itemize
@end deftp


@deftp {Type} display '(satisfies display-p)
@anchor{display}
A connection to an X server. @xref{Displays}, for additional
information.
@end deftp


@deftp {Type} drawable '(or window pixmap)
Both @var{windows} and @var{pixmaps} can be used as sources and
destinations in graphics operations. @var{windows} and @var{pixmaps}
together are known as @emph{drawables}. However, an @var{:input-only}
window cannot be used as a source or destination in a graphics
operation.
@end deftp


@deftp {Type} draw-direction '(member :left-to-right :right-to-left)
Defines a list of rotation directions for drawing arcs and
fonts. @var{draw-direction} can have the values of
@var{:left-to-right} or @var{:right-to-left}.
@end deftp


@deftp {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.

@emph{error} -- One of the following:
@itemize @c menu

@item @var{:access}
@item @var{:drawable}
@item @var{:implementation}
@item @var{:value}

@item @var{:alloc}
@item @var{:font}
@item @var{:length}
@item @var{:window}

@item @var{:atom}
@item @var{:gcontext}
@item @var{:match}

@item @var{:colormap}
@item @var{:id-choice}
@item @var{:name}

@item @var{:cursor}
@item @var{:illegal-request}
@item @var{:pixmap}
@end itemize
@end deftp

@deftp {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.

@emph{event-type} -- One of the following:
@itemize @c menu

@item @var{:button-press}
@item @var{:exposure}
@item @var{:motion-notify}

@item @var{:button-release}
@item @var{:focus-in}
@item @var{:no-exposure}

@item @var{:circulate-notify}
@item @var{:focus-out}
@item @var{:property-notify}

@item @var{:circulate-request}
@item @var{:graphics-exposure}
@item @var{:reparent-notify}

@item @var{:client-message}
@item @var{:gravity-notify}
@item @var{:resize-request}

@item @var{:colormap-notify}
@item @var{:keymap-notify}
@item @var{:selection-clear}

@item @var{:configure-notify}
@item @var{:key-press}
@item @var{:selection-notify}

@item @var{:configure-request}
@item @var{:key-release}
@item @var{:selection-request}

@item @var{:create-notify}
@item @var{:leave-notify}
@item @var{:unmap-notify}

@item @var{:destroy-notify}
@item @var{:map-notify}
@item @var{:visibility-notify}

@item @var{:enter-notify}
@item @var{:map-request}
@end itemize
@end deftp

@deftp {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.
@end deftp


@deftp {Type} event-mask-class '(member event*)
The elements of the type @var{event-mask-class} are keyword names
that correspond to a particular bit in an event bitmask.

@emph{event} -- One of the following:
@itemize @c menu

@item @var{:button-1-motion}
@item @var{:enter-window}
@item @var{:pointer-motion-hint}

@item @var{:button-2-motion}
@item @var{:exposure}
@item @var{:property-change}

@item @var{:button-3-motion}
@item @var{:focus-change}
@item @var{:resize-redirect}

@item @var{:button-4-motion}
@item @var{:key-press}
@item @var{:structure-notify}

@item @var{:button-5-motion}
@item @var{:key-release}
@item @var{:substructure-notify}

@item @var{:button-motion}
@item @var{:keymap-state}
@item @var{:substructure-redirect}

@item @var{:button-press}
@item @var{:leave-window}
@item @var{:visibility-change}

@item @var{:button-release}
@item @var{:owner-grab-button}

@item @var{:colormap-change}
@item @var{:pointer-motion}
@end itemize
@end deftp


@defun make-event-keys event-mask
Returns a list of @var{event-mask-class} keyword names for the event
bits that are set in the specified event mask.

@table @var
@item event-mask
An event mask (type @var{mask32}).
@end table

@end defun


@defun make-event-mask &rest keys

@table @var
@item keys
@var{event-mask-class} keywords.
@end table

Constructs an event mask from a set of @var{event-mask-class} keyword
names.

@table @var
@item event-mask
Type @var{mask32}.
@end table

@end defun


@deftp {Type} font '(satisfies font-p)
@anchor{font}

A text font. @xref{Font and Characters}, for additional
information.

@end deftp


@deftp {Type} fontable '(or stringable font)

A @var{fontable} is either a @var{font} object or the name of one of
the fonts in the font database.

@end deftp


@deftp {Type} font-props 'list

A @var{list} that contains alternating keywords and integers.

@end deftp


@deftp {Type} gcontext '(satisfies gcontext-p)
@anchor{gcontext}

A graphics context. @xref{Graphics Contexts}, for additional
information.

@end deftp


@deftp {Type} gcontext-key '(member type*)

A list of predefined types for use in @var{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.

@var{type} -- One of the following:
@itemize @c menu

@item @var{:arc-mode}
@item @var{:exposures}
@item @var{:line-width}

@item @var{:background}
@item @var{:fill-rule}
@item @var{:plane-mask}

@item @var{:cap-style :fill-style}
@item @var{:stipple}

@item @var{:clip-mask}
@item @var{:font}
@item @var{:subwindow-mode}

@item @var{:clip-x}
@item @var{:foreground}
@item @var{:tile}

@item @var{:clip-y}
@item @var{:function}
@item @var{:ts-x}

@item @var{:dash-offset}
@item @var{:join-style}
@item @var{:ts-y}

@item @var{:dashes}
@item @var{:line-style}
@end itemize
@end deftp

@deftp {Type} grab-status '(member grab-type*)

There are two kinds of grabs: active and passive. An @emph{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 @emph{passive grab}. Passive grabs
can be very convenient for implementing reliable pop-up menus.

@var{grab-type} -- One of the following:

@itemize @c menu

@item @var{:already-grabbed}

@item @var{:frozen}

@item @var{:invalid-time}

@item @var{:not-viewable}

@item @var{:success}
@end itemize
@end deftp


@deftp {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.
@end deftp


@deftp {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 @var{:default} is
specified, the size is based on the current font, if known; otherwise,
16 is used.
@end deftp


@deftp {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.
@end deftp


@deftp {Type} int16 '(signed-byte 16)
@anchor{int16}
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.
@end deftp


@deftp {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.
@end deftp


@deftp {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
@var{keysym} type can have a range from 0 to 4,294,967,295.
@end deftp


@deftp {Type} mask16 ' card16
A positional bitmask that contains 16 boolean flags.
@end deftp


@deftp {Type} mask32 ' card32
A positional bitmask that contains 32 boolean flags.
@end deftp


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

@var{modifier} -- One of the following:
@itemize @c menu

@item @var{:shift}
@item @var{:mod-2}

@item @var{:lock}
@item @var{:mod-3}

@item @var{:control}
@item @var{:mod-4}

@item @var{:mod-1}
@item @var{:mod-5}
@end itemize
@end deftp


@deftp {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 @var{:any} is equivalent to any subset of modifier
key.
@end deftp


@deftp {Type} pixarray '(or (array pixel (* *)) (array card16 (* *)) (array card8 (* *)) (array (unsigned-byte 4) (* *)) (array bit (* *)))

Specifies a two-dimensional array of pixels.

@end deftp



@deftp {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.

@end deftp


@deftp {Type} pixmap '(satisfies pixmap-p)
@anchor{pixmap}

A @var{pixmap}, @pxref{Pixmaps}), for additional information.

@end deftp


@deftp {Structure} pixmap-format

A structure that describes the storage format of a pixmap.

The @var{pixmap-format} structure contains slots for @var{depth},
@var{bits-per-pixel}, and @var{scanline-pad}. The @var{depth} member
indicates the number of bit planes in the pixmap. The
@var{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 @var{bitmap-format}, the @var{scanline-pad} member
indicates how many pixels are needed to pad the left edge of the
scan-line.
@end deftp

@deftp {Slot of pixmap-format} depth

Type: @var{image-depth}.

The number of bit planes in the pixmap.
@end deftp


@deftp {Slot of pixmap-format} bits-per-pixel


Type: (@var{member} 1 4 8 16 24 32).

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


@deftp {Slot of pixmap-format} scanline-pad

Type: (@var{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.
@end deftp

@deftp {Type} point-seq '(repeat-seq (int16 x) (int16 y))

The @var{point-seq} type is used to define sequences of
(@var{x},@var{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.
@end deftp

@deftp {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.

@end deftp


@deftp {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 @var{event-mask-class}.

@var{event} -- One of the following:

@itemize @c menu

@item @var{:button-1-motion}
@item @var{:button-motion}
@item @var{:leave-window}

@item @var{:button-2-motion}
@item @var{:button-press}
@item @var{:pointer-motion}

@item @var{:button-3-motion}
@item @var{:button-release}
@item @var{:pointer-motion-hint}

@item @var{:button-4-motion}
@item @var{:enter-window}

@item @var{:button-5-motion}
@item @var{:keymap-state}
@end itemize
@end deftp

@deftp {Type} rect-seq '(repeat-seq (int16 x) (int16 y) (card16 width) (card16 height))

@var{rect-seq} defines a four-tuple sequence of the form (@var{x},
@var{y}, @var{width}, @var{height}). The points @var{x} and
@var{y} are signed, 16-bit quantities with a range from -32,768 to
32,767. The @var{width} and @var{height} values are unsigned, 16-bit
quantities and range from 0 to 65,535.

@end deftp


@deftp {Type} repeat-seq (&rest elts) 'sequence

A subtype used to define repeating sequences.

@end deftp


@deftp {Type} resource-id 'card29

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

@end deftp


@deftp {Type} rgb-val '(float 0.0 1.0)

An @var{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.

@end deftp

@deftp {Type} screen '(satisfies screen-p)
@anchor{screen}

A display screen. @xref{Screens}, for further information.

@end deftp


@deftp {Type} seg-seq '(repeat-seq (int16 x1) (int16 y1) (int16 x2) (int16 y2))

Defines sequences of (@var{x1}, @var{y1}, @var{x2}, @var{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.

@end deftp


@deftp {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.

@var{button} -- One of the following:

@itemize @c menu
@item @var{:button-1}
@item @var{:button-4}
@item @var{:button-2}
@item @var{:button-5}
@item @var{:button-3}
@end itemize

@end deftp

@defun make-state-keys state-mask

@table @var
@item state-mask
A 16-bit mask of type @var{mask16}.

@end table

Returns a list of @var{state-mask-key} symbols corresponding to the
@var{state-mask}. A symbol belongs to the returned list if, and only
if, the corresponding @var{state-mask} bit is 1.

@table @var
@item state-keywords
Type @var{list}.
@end table

@end defun


@defun make-state-mask &rest keys

@table @var
@item keys
A list of @var{state-mask-key} symbols.
@end table

Returns a 16-bit @var{mask} representing the given
@var{state-mask-key} symbols. The returned @var{mask} contains a 1
bit for each keyword.

@table @var
@item mask
Type @var{mask16}.
@end table
@end defun

@deftp {Type} stringable '(or string symbol)

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

@end deftp


@deftp {Type} timestamp '(or null card32)

An encoding of a time. @var{nil} stands for the current time.

@end deftp


@deftp {Structure} visual-info

A structure that represents a visual type. The elements of this
structure are @var{id}, @var{class}, @var{red-mask}, @var{green-mask},
@var{blue-mask}, @var{bits-per-rgb}, and @var{colormap-entries}.

@end deftp


@deftp {Slot of visual-info} id

Type: @var{card29}.

A unique identification number.

@end deftp


@deftp {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.

@end deftp


@deftp {Slots of visual-info} red-mask
@deftpx {Slots of visual-info} green-mask
@deftpx {Slots of visual-info} blue-mask

Type: @var{pixel}.

The @var{red-mask}, @var{green-mask}, and @var{blue-mask} elements are
only meaningful for the @var{:direct-color} and @var{:true-color}
classes. Each mask has one contiguous set of bits with no
intersections.

@end deftp

@deftp {Slot of visual-info} bits-per-rgb

Type: @var{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.

@end deftp


@deftp {Slot of visual-info} colormap-entries

Type: @var{card16}.

Defines the number of available colormap entries in a newly created
colormap. For @var{:direct-color} and @var{:true-color}, this is the
size of an individual pixel subfield.

@end deftp


@deftp {Type} win-gravity '(member gravity*)

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

@var{gravity} -- One of the following:
@itemize @c menu

@item @var{:center}
@item @var{:north-west}
@item @var{:static}

@item @var{:east}
@item @var{:south}
@item @var{:unmap}

@item @var{:north}
@item @var{:south-east}
@item @var{:west}

@item @var{:north-east}
@item @var{:south-west}
@end itemize

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 @var{window-gravity}
(@pxref{Window Attributes})), for additional information.

@end deftp


@deftp {Type} window '(satisfies window-p)
@anchor{window}

A window. @xref{Windows and Pixmaps}, for additional
information.

@end deftp


@deftp {Type} xatom '(or string symbol)

A name that has been assigned a corresponding unique ID by the
server. @var{xatoms} are used to identify properties, selections, and
types defined in the X server. An @var{xatom} can be either a
@var{string} or @var{symbol} whose @var{symbol-name} is used as the
@var{xatom} name. The case of the characters in the string are
significant when comparing @var{xatoms}.

@end deftp

@node Displays, Screens, Introduction to CLX, Top
@chapter Displays

A particular X server, together with its screens and input devices, is
called a @emph{display}. The CLX @var{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:

@itemize @bullet
@item  Open (connect) a display
@item  Obtain information about a display
@item  Access and change display attributes
@item  Close (disconnect) a display
@end itemize

@menu
* Opening the Display::
* Display Attributes::
* Managing the Output Buffer::
* Closing the Display::
@end menu

@node Opening the Display, Display Attributes, Displays, Displays
@section Opening the Display


The @var{open-display} and @var{open-default-display} functions are
used to open a connection to an X server.  @var{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 @var{open-display} (particularly on
ssh-forwarded connections)

@defun open-display host &key :display :protocol

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

@item :display
An integer that specifies which display device on the @emph{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).

@item :protocol
A keyword argument that specifies which network protocol should be
used for connecting to the server (for example, @var{:tcp},
@var{:dna}, or @var{:chaos}). The set of possible values and the
default value are implementation specific.

@end table

Returns a @var{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 @var{open-display}, all
screens on the display can be used by the client application.

@table @var
@item display
Type @var{display}.
@end table

@end defun

@defun open-default-display &optional display-name

@table @var
@item display-name
The display to connect to.  Display names have the format

@verbatim
  [protocol/] [hostname] : [:] displaynumber [.screennumber]
@end verbatim

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

@itemize @bullet
@item If the hostname is @code{unix} or the empty string, any supplied
protocol is ignored and a connection is made using the @code{local} transport.
@item If a double colon separates @var{hostname} from @var{displaynumber}, the
protocol is assumed to be @code{decnet}.
@end itemize

If @var{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 @env{DISPLAY}.  See also the section ``DISPLAY
NAMES'' in X(7)

@end table

Open a connection to @var{display-name} or to the appropriate
default display.

@code{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 @env{AUTHORITY_PATHNAME} (typically
@file{$HOME/.Xauthority}).  If the protocol is @code{: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.

@end defun

@node Display Attributes, Managing the Output Buffer, Opening the Display, Displays
@section Display Attributes

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

@defun display-authorization-data display

@table @var
@item display
A @var{display} object.
@end table

Returns the authorization data string for @var{display} that was
transmitted to the server by @var{open-display} during connection
setup. The data is specific to the particular authorization protocol
that was used. The @var{display-authorization-name} function returns
the protocol used.

@table @var
@item authorization-data
Type @var{string}.
@end table

@end defun

@defun display-authorization-name display

@table @var
@item display
A @var{display} object.
@end table

Returns the authorization protocol namestring for @var{display} that
was transmitted by @var{open-display} to the server during connection
setup. The @var{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."

@table @var
@item authorization-name
Type @var{string}.
@end table

@end defun

@defun display-bitmap-format display
@anchor{display-bitmap-format}

@table @var
@item display
A @var{display} object.
@end table

Returns the @emph{bitmap-format} information for the specified @emph{display}.

@table @var
@item bitmap-format
Type @var{bitmap-format}.
@end table

@end defun

@defun display-byte-order display

@table @var
@item display
A @var{display} object.
@end table

Returns the @var{byte-order} to be employed in communication with the
server for the given @var{display}. The possible values are as
follows:

@table @var
@item :lsbfirst
Values are transmitted least significant byte first.
@item :msbfirst
Values are transmitted most significant byte first.
@end table

Except where explicitly noted in the protocol, all 16-bit and 32-bit
quantities sent by the client must be transmitted with this
@var{byte-order}, and all 16-bit and 32-bit quantities returned by the
server are transmitted with this @var{byte-order}.

@table @var
@item byte-order
Either @var{:lsbfirst} or @var{:msbfirst}.
@end table

@end defun

@defun display-display display

@table @var
@item display
A @var{display} object.
@end table

Returns the @var{display-number} for the host associated with
@var{display}.

@table @var
@item display-number
Type @var{integer}.
@end table

@end defun

@defun display-error-handler display

@table @var
@item display
A @var{display} object.
@end table

Returns and (with @code{setf}) sets the @var{error-handler} function
for the given @var{display}. CLX calls (one of) the display error
handler functions to handle server errors returned to the
connection. The default error handler, @var{default-error-handler},
signals conditions as they occur. @xref{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 @emph{Lisp Reference} manual.

If the value of @var{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
@var{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:

@multitable @columnfractions 0.5 0.5
@item @var{:current-sequence} @tab @var{card16}
@item @var{:major} @tab @var{card8}
@item @var{:minor} @tab @var{card16}
@item @var{:sequence} @tab @var{card16}
@end multitable

For @var{colormap}, @var{cursor}, @var{drawable}, @var{font},
@var{gcontext}, @var{id-choice}, @var{pixmap}, and @var{window}
errors, the keyword-value pairs are the core error pairs plus:

@multitable @columnfractions 0.5 0.5
@item @var{:resource-id} @tab @var{card32}
@end multitable

For @var{:atom} errors, the keyword-value pairs are the core error
pairs plus:

@multitable @columnfractions 0.5 0.5
@item @var{:atom-id} @tab @var{card32}
@end multitable

For @var{:value} errors, the keyword-value pairs are the core error
pairs plus:

@multitable @columnfractions 0.5 0.5
@item @var{:value} @tab @var{card32}
@end multitable

@table @var
@item error-handler
Type @var{function} or @var{sequence}.
@end table

@end defun

@defun display-image-lsb-first-p display

@table @var
@item display
A @var{display} object.
@end table

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 @var{display},
@var{display-image-lsb-first-p} returns non-@var{nil} if the leftmost
bit is the least significant bit; otherwise, it returns @var{nil}.

@table @var
@item image-lsb-first-p
Type @var{boolean}.
@end table

@end defun


@defun display-keycode-range display

@table @var
@item display
A @var{display} object.
@end table

Returns @var{min-keycode} and @var{max-keycode} as multiple
values. See the @var{display-max-keycode} and
@var{display-min-keycode} functions for additional information.

@table @var
@item min-keycode
@itemx max-keycode
Type @var{card8}.
@end table

@end defun


@defun display-max-keycode display

@table @var
@item display
A @var{display} object.
@end table

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

@table @var
@item max-keycode
Type @var{card8}.
@end table

@end defun


@defun display-max-request-length display

@table @var
@item display
A @var{display} object.
@end table

Returns the maximum length of a request, in four-byte units, that is
accepted by the specified @emph{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).

@table @var
@item max-request-length
Type @var{card16}.
@end table

@end defun


@defun display-min-keycode display

@table @var
@item display
A @var{display} object.
@end table

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

@table @var
@item min-keycode
Type @var{card8}.
@end table

@end defun


@defun display-motion-buffer-size display

@table @var
@item display
A @var{display} object.
@end table

Returns the approximate size of the motion buffer for the specified
@var{display}. The server can retain the recent history of pointer
motion at a finer granularity than is reported by @var{:motion-notify}
events. Such history is available through the @var{motion-events}
function.

@table @var
@item motion-buffer-size
Type @var{card32}.
@end table

@end defun


@defun display-p display

@table @var
@item display-p
Type @var{boolean}.
@end table

Returns non-@var{nil} if @emph{display} is a @var{display} object;
@end defun

@defun display-pixmap-formats display

@table @var
@item display
A @var{display} object.
@end table

Returns the list of @var{pixmap-format} values for the given
@emph{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.

@table @var
@item pixmap-formats
Type @var{list}.
@end table

@end defun


@defun display-plist display

@table @var
@item display
A @var{display} object.
@end table

Returns and (with @code{setf}) sets the property list for the specified
@emph{display}. This function provides a hook where extensions can add
data.
@table @var
@item plist
Type @var{list}.
@end table

@end defun


@defun display-protocol-major-version display

@table @var
@item display
A @var{display} object.
@end table

Returns the major version number of the X protocol associated with the
specified @emph{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.
@table @var
@item protocol-major-version
Type @var{card16}.
@end table

@end defun


@defun display-protocol-minor-version display

@table @var
@item display
A @var{display} object.
@end table

Returns the minor protocol revision number associated with the
specified @emph{display}. In general, the minor version would
increment for small upward compatible changes in the X protocol.
@table @var
@item protocol-minor-version
Type @var{card16}.
@end table

@end defun


@defun display-protocol-version display

@table @var
@item display
A @var{display} object.
@end table

Returns @emph{protocol-major-version} and
@emph{protocol-minor-version} as multiple values. See the
@var{display-protocol-major-version} and
@var{display-protocol-minor-version} functions for additional
information.

@table @var
@item protocol-major-version
@itemx protocol-minor-version
@end table

@end defun


@defun display-resource-id-base display

@table @var
@item display
A @var{display} object.
@end table

Returns the @emph{resource-id-base} value that was returned from the
server during connection setup for the specified @emph{display}. This
is used in combination with the @emph{resource-id-mask} to construct
valid IDs for this connection.
@table @var
@item resource-id-base
Type @var{resource-id}.
@end table

@end defun


@defun display-resource-id-mask display

@table @var
@item display
A @var{display} object.
@end table

Returns the @emph{resource-id-mask} that was returned from the server
during connection setup for the specified @emph{display}. The
@emph{resource-id-mask} contains a single contiguous set of bits (at
least 18) which the client uses to allocate resource IDs for types
@var{window}, @var{pixmap}, @var{cursor}, @var{font}, @var{gcontext},
and @var{colormap} by choosing a value with (only) some subset of
these bits set, and @var{or}ing it with the
@emph{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.)
@table @var
@item resource-id-mask
Type @var{resource-id}.
@end table

@end defun


@defun display-roots display

@table @var
@item display
A @var{display} object.
@end table

Returns a list of all the @var{screen} structures available for the
given @emph{display}.
@table @var
@item roots
A list of screens.
@end table

@end defun


@defun display-vendor display

@table @var
@item display
A @var{display} object.
@end table
Returns @emph{vendor-name} and @emph{release-number} as
multiple values. See the @var{display-vendor-name} and
@var{display-release-number} functions for additional information.
@table @var
@item vendor-name
@itemx release-number
@end table

@end defun


@defun display-vendor-name display

@table @var
@item display
A @var{display} object.
@end table

Returns a string that provides some vendor identification of the X
server implementation associated with the specified @emph{display}.
@table @var
@item vendor-name
Type @var{string}.
@end table

@end defun


@defun display-version-number display

@table @var
@item display
A @var{display} object.
@end table

Returns the X protocol version number for this implementation of CLX.
@table @var
@item version-number
Type @var{card16}.
@end table

@end defun

@defun display-xid display

@table @var
@item display
A @var{display} object.
@end table

Returns the function that is used to allocate server resource IDs for
this @emph{display}.
@table @var
@item resource-allocator
Type @var{function}.
@end table

@end defun


@defmac with-display display &body body

This macro is for use in a multi-process
environment. @var{with-display} provides exclusive access to the local
@var{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 @var{with-display}),
then synchronization need not (but can) occur immediately. Except
where noted, all routines effectively contain an implicit
@var{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 (@pxref{with-event-queue}).

@table @var
@item display
A @var{display}.
@end table

@end defmac

@node Managing the Output Buffer, Closing the Display, Display Attributes, Displays
@section 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 @emph{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
(@pxref{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 @var{display-force-output} and
@var{display-finish-output} functions allow a client program to
synchronize with buffered output requests.

@defun display-after-function display

@table @var
@item display
A @var{display} object.
@end table

Returns and (with @code{setf}) sets the @emph{after-function} for the
given @emph{display}. If @emph{after-function} is non-@var{nil}, it is
a function that is called after every protocol request is generated,
even those inside an explicit @var{with-display}, but never called
from inside the @emph{after-function}. The function is called inside
the effective @var{with-display} for the associated request. The
default value is @var{nil}. This can be set, for example, to
#'@var{display-force-output} or #' @var{display-finish-outpu}t.
@table @var
@item after-function
Type @var{function} or @var{null}.
@end table

@end defun


@defun display-force-output display
@anchor{display-force-output}

@table @var
@item display
A @var{display} object.
@end table

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

@end defun


@defun display-finish-output display
@anchor{display-finish-output}

@table @var
@item display
A @var{display} object.
@end table

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.

@end defun

@node Closing the Display,  , Managing the Output Buffer, Displays
@section Closing the Display

To close or disconnect a display from the X server, use @var{close-display}.

@defun close-display display

@table @var
@item display
A @var{display} object.
@end table

Closes the connection to the X server for the specified
@var{display}. It destroys all server resources (@var{window},
@var{font}, @var{pixmap}, @var{colormap}, @var{cursor}, and
@var{gcontext}), that the client application has created on this
display, unless the close down mode of the server resource has been
changed (@pxref{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.

@end defun

@node Screens, Windows and Pixmaps, Displays, Top
@chapter Screens

@menu
* Screens and Visuals::
* Screen Attributes::
@end menu

@node Screens and Visuals, Screen Attributes, Screens, Screens
@section Screens and Visuals


An X display supports graphical output to one or more
@emph{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 @emph{visual type} (usually
referred to simply as a @emph{visual}) which uniquely identifies the
hardware capabilities of a display screen. Fundamentally, a visual is
represented by a @var{card29} integer ID, which uniquely identifies
the visual type relative to a single display. CLX also represents a
visual with a @var{visual-info} structure that contains other
attributes associated with a visual (@pxref{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:

@itemize @bullet

@item
A screen can be color or gray-scale.

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

@item
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.

@end itemize

CLX supports the following classes of visual types:
@var{:direct-color}, @var{:gray-scale}, @var{:pseudo-color},
@var{:static-color}, @var{:static-gray}, and @var{: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:

@multitable {} {Color} {Gray-Scale}
@item Read-only @tab @var{:static-color} @tab @var{:static-gray}
@item Writable @tab @var{:pseudo-color} @tab @var{:gray-scale}
@end multitable

For screens with red, green, and blue colormaps:

@multitable @columnfractions 0.3 0.3 0.3
@item Read-only @tab @var{:true-color} @tab
@item Writable @tab @var{:direct-color} @tab @var{:gray-scale}
@end multitable

The visual class also indicates how screen colormaps are
handled. @pxref{Colormaps and Colors}).

@node Screen Attributes,  , Screens and Visuals, Screens
@section Screen Attributes

In CLX, each display screen is represented by a @var{screen}
structure. The @var{display-roots} function returns the list of
@var{screen} structures for the display. The following paragraphs
discuss the attributes of CLX @var{screen} structures.

@defun screen-backing-stores screen

@table @var
@item screen
A @var{screen}.
@end table

Returns a value indicating when the @emph{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 @var{:always},
@var{:never}, or @var{:when-mapped}.

@table @var
@item backing-stores-type
One of @var{:always}, @var{:never}, or @var{:when-mapped}.
@end table

@end defun


@defun screen-black-pixel screen

@table @var
@item screen
A @var{screen}.
@end table

Returns the black pixel value for the specified @emph{screen}.

@table @var
@item black-pixel
Type @var{pixel}.
@end table

@end defun


@defun screen-default-colormap screen

@table @var
@item screen
A @var{screen}.
@end table

Returns the @emph{default-colormap} for the specified
@emph{screen}. The @emph{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.

@table @var
@item default-colormap
Type @var{colormap}.
@end table

@end defun


@defun screen-depths screen

@table @var
@item screen
A @var{screen}.
@end table


Returns an association list that specifies what drawable
depths are supported on the specified @emph{screen}. Elements of the
returned association list have the form (depth @emph{visual}*), where
each @emph{visual} is a @var{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 @var{:input-only} windows are always supported.

@table @var
@item depths
Type @var{alist}.
@end table

@end defun


@defun screen-event-mask-at-open screen

@table @var
@item screen
A @var{screen}.
@end table


Returns the initial root event mask for the specified
@emph{screen}.

@table @var
@item event-mask-at-open
Type @var{mask32}.
@end table

@end defun


@defun screen-height screen

@table @var
@item screen
A @var{screen}.
@end table


Returns the @emph{height} of the specified @emph{screen} in
pixel units.

@table @var
@item height
Type @var{card16}.
@end table

@end defun


@defun screen-height-in-millimeters screen

@table @var
@item screen
A @var{screen}.
@end table


Returns the height of the specified @emph{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.

@table @var
@item height-in-millimeters
Type @var{card16}.
@end table

@end defun


@defun screen-max-installed-maps screen

@table @var
@item screen
A @var{screen}.
@end table


Returns the maximum number of colormaps that can be
installed simultaneously with @var{install-colormap}.

@table @var
@item max-installed-colormaps
Type @var{card16}.
@end table

@end defun


@defun screen-min-installed-maps screen

@table @var
@item screen
A @var{screen}.
@end table

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

@table @var
@item min-installed-colormaps
Type @var{card16}.
@end table

@end defun


@defun screen-p screen

@table @var
@item screen-p
Type @var{boolean}.
@end table


Returns non-@code{nil} if the @emph{screen} argument is a
@end defun



@defun screen-plist screen

@table @var
@item screen
A @var{screen}.
@end table


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

@table @var
@item plist
Type @var{list}.
@end table

@end defun

@defun screen-root screen

@table @var
@item screen
A @var{screen}.
@end table


Returns the @emph{root-window} for the specified
@emph{screen}. This function is useful with functions that take a
parent window as an argument. The class of the root window is always
@var{:input-output}.

@table @var
@item root-window
Type @var{window} or @var{null}.
@end table

@end defun


@defun screen-root-depth screen

@table @var
@item screen
A @var{screen}.
@end table

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

@table @var
@item root-window-depth
Type @var{image-depth}.
@end table

@end defun


@defun screen-root-visual screen

@table @var
@item screen
A @var{screen}.
@end table


Returns the default visual type for the root window for the
specified @emph{screen}.

@table @var
@item root-window-visual
Type @var{card29}.
@end table

@end defun


@defun screen-save-unders-p screen

@table @var
@item screen
A screen.
@end table


If true, the server can support the save-under mode in
@var{create-window} and in changing window attributes.

@table @var
@item save-unders-p
Type @var{boolean}.
@end table

@end defun


@defun screen-white-pixel screen

@table @var
@item screen
A screen.
@end table


Returns the white pixel value for the specified
@emph{screen}.

@table @var
@item white-pixel
Type @var{pixel}.
@end table

@end defun


@defun screen-width screen

@table @var
@item screen
A screen.
@end table


Returns the width of the specified @emph{screen} in pixel
units.

@table @var
@item width
Type @var{card16}.
@end table

@end defun


@defun screen-width-in-millimeters screen

@table @var
@item screen
A screen.
@end table


Returns the width of the specified @emph{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.

@table @var
@item width-in-millimeters
Type @var{card16}.
@end table

@end defun


@node Windows and Pixmaps, Graphics Contexts, Screens, Top
@chapter Windows and Pixmaps

@menu
* Drawables::
* Creating Windows::
* Window Attributes::
* Stacking Order::
* Window Hierarchy::
* Mapping Windows::
* Destroying Windows::
* Pixmaps::
@end menu

@node Drawables, Creating Windows, Windows and Pixmaps, Windows and Pixmaps
@section Drawables

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

@defun drawable-display drawable

@table @var
@item drawable
A @var{drawable} object.
@end table

Returns the display for the specified @emph{drawable}.

@end defun

@defun drawable-equal drawable-1 drawable-2

@table @var
@item drawable-1
@itemx drawable-2
@var{drawable} objects.
@end table

Returns true if the two arguments refer to the same server resource,
and @var{nil} if they do not.

@end defun


@defun drawable-id drawable

@table @var
@item drawable
A @var{drawable} object.
@end table

Returns the unique resource ID assigned to the specified
@var{drawable}.

@table @var
@item id
Type @var{resource-id}.
@end table

@end defun

@defun drawable-p drawable

@table @var
@item boole
Type @var{boolean}.
@end table

Returns true if the argument is a @var{drawable} and @var{nil}
otherwise.

@end defun

@defun drawable-plist drawable

@table @var
@item plist
A property list.
@end table

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

@end defun

@node Creating Windows, Window Attributes, Drawables, Windows and Pixmaps
@section Creating Windows


A window is a @var{drawable} that can also receive input events. CLX
represents a window with a @var{window} object. The
@var{create-window} function creates a new @var{window} object.

@defun 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
@anchor{create-window}

@table @var
@item :parent
The parent window. This argument is required.

@item :x
@itemx :y
@var{int16} coordinates for the outside upper-left corner of the new
window with respect to the origin (inside upper-left corner) of the
@var{:parent}. These arguments are required.

@item :width
@itemx :height

@var{card16} values for the size of the new window. These arguments
are required.

@item :depth

A @var{card16} specifying the depth of the new window.

@item :class

One of @var{:input-outpu}t, @var{:input-only}, or @var{:copy}.

@item :visual

A @var{card29} ID specifying the visual type of the new window.

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

Initial attribute values for the new window. If @var{nil}, the default
value is defined by the X protocol.See paragraph
@end table

Creates and returns a window. A @var{:parent} window must be
specified; the first window created by a client will have a root
window as its @var{:parent}. The new window is initially unmapped and
is placed on top of its siblings in the stacking order. A
@var{:create-notify} event is generated by the server.

The @var{:class} of a window can be @var{:input-output} or
@var{:input-only}. Windows of class @var{:input-only} cannot be used
as the destination drawable for graphics output and can never receive
@var{:exposure} events, but otherwise operate the same as
@var{:input-output} windows. The @var{:class} can also be @var{:copy},
in which case the new window has the same class as its @var{:parent}.

For an @var{:input-output} window, the @var{:visual} and @var{:depth}
must be a combination supported by the @var{:parent}'s screen, but the
@var{:depth} need not be the same as the @var{:parent}'s. The
@var{:parent} of an @var{:input-output} window must also be
@var{:input-output}. A @var{:depth} of 0 means that the depth of the
@var{:parent} is used.

For an @var{:input-only} window, the @var{:depth} must be zero, and
the @var{:visual} must be supported by the @var{:parent}'s screen. The
@var{:parent} of an @var{:input-only} window can be of any class. The
only attributes that can be given for an @var{:input-only} window are
@var{:cursor}, @var{:do-not-propagate-mask}, @var{:event-mask},
@var{:gravity}, and @var{:override-redirect}.

@table @var
@item window
Type @var{window}.
@end table

@end defun

@node Window Attributes, Stacking Order, Creating Windows, Windows and Pixmaps
@section Window Attributes


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

@defun drawable-border-width drawable

@table @var
@item drawable
A @var{drawable} object.
@end table

Returns the @emph{border-width} of the @emph{drawable} in pixels. It
always returns zero if the @emph{drawable} is a pixmap or an
@var{:input-only} window. Used with @code{setf}, this function also
changes the border width of the @var{: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
@var{:input-only} window nonzero.

When changing the border-width of a window, if the override-redirect
attribute of the window is @var{:off} and some other client has
selected @var{:substructure-redirect} on the parent, a
@var{:configure-request} event is generated, and no further processing
is performed.  Otherwise, the border-width is changed.

@table @var
@item border-width
Type @var{card16}.
@end table

@end defun


@defun drawable-depth drawable

@table @var
@item drawable
A @var{drawable} object.
@end table

Returns the depth of the specified @emph{drawable} (bits per pixel).

@table @var
@item depth
Type @var{card8}.
@end table

@end defun


@defun drawable-height drawable

@table @var
@item inside-height
Type @var{card16}.
@end table

@end defun


@defun drawable-width drawable

@table @var
@item drawable
A @var{drawable} object.
@end table

These functions return the height or width of the
@emph{drawable}. These coordinates define the inside size of the
@emph{drawable}, in pixels. Used with @code{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 @var{:exposure} event. If a mapped window is
made smaller, @var{: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 @var{:off} and some other client has selected
@var{:substructure-redirect} on the parent, a @var{:configure-request}
event is generated, and no further processing is performed. Otherwise,
if another client has selected @var{:resize-redirect} on the window, a
@var{: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 @var{:resize-redirect} and that
@var{:substructure-redirect} on the parent has precedence over
@var{: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.

@table @var
@item inside-width
Type @var{card16}.
@end table

@end defun


@defun drawable-x drawable

@table @var
@item outside-left
Type @var{int16}.
@end table

@end defun


@defun drawable-y drawable

@table @var
@item drawable
A @var{drawable} object.
@end table

These functions return the x or y coordinate of the specified
@emph{drawable}. They always return zero if the @emph{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
@code{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
@var{:exposure} events on any formerly obscured windows.

When changing the position of a window, if the override-redirect
attribute of the window is @var{:off} and some other client has
selected @var{:substructure-redirect} on the parent, a
@var{:configure-request} event is generated, and no further processing
is performed.  Otherwise, the window is moved.

@table @var
@item outside-top
Type @var{int16}.
@end table

@end defun


@defun window-all-event-masks window

@table @var
@item window
A @var{window}.
@end table

Returns the inclusive-or of the event masks selected on the
specified @emph{window} by all clients.
@table @var
@item all-event-masks
Type @var{mask32}.
@end table

@end defun


@defun setf (window-background) window background

@table @var
@item window
A @var{window}.
@item background
Either a @var{pixel}, a @var{pixmap}, @var{:none}, or @var{:parent-relative}.
@end table

Changes the @emph{background} attribute of the @emph{window} to the
specified value. This operation is not allowed on an @var{: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
@var{: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 @var{:none}, the
server will not modify exposed areas. If the background is
@var{: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
@var{:parent-relative}, the background pixmap tile origin is the same
as the parent's; otherwise, the tile origin is the window origin.

@table @var
@item background
Either a @var{pixel}, a @var{pixmap}, @var{:none}, or @var{:parent-relative}.
@end table

@end defun


@defun window-backing-pixel window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) changes the value of the backing-pixel
attribute for the specified @emph{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.

@table @var
@item backing-pixel
Type @var{pixel}.
@end table

@end defun


@defun window-backing-planes window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) changes the value of the backing-planes
attribute for the specified @emph{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.

@table @var
@item backing-planes
Type @var{pixel}.
@end table

@end defun


@defun window-backing-store window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) changes the value of the backing-store
attribute for the specified @emph{window}. Changing the backing-store
attribute of an obscured window to @var{:when-mapped} or @var{:always}
may have no immediate effect. The default backing-store of a new
window is @var{:not-useful}.

@table @var
@item backing-store-type
One of @var{:always}, @var{:not-useful}, or @var{:when-mapped}.
@end table

@end defun


@defun window-bit-gravity window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) changes the bit-gravity attribute of the
@emph{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 @var{:forget}.

For example, suppose a window's size is changed by @emph{W} pixels
in width and @emph{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.

@multitable {Bit-Gravity} {X Change} {Y Change}
@item @var{:center} @tab @emph{W/}2 @tab @emph{H/}2
@item @var{:east} @tab @emph{W} @tab @emph{H/}2
@item @var{:north} @tab @emph{W/}2 @tab 0
@item @var{:north-east} @tab @emph{W} @tab 0
@item @var{:north-west} @tab 0 @tab 0
@item @var{:south} @tab @emph{W/}2 @tab @emph{H}
@item @var{:south-east} @tab W @tab H
@item @var{:south-west} @tab 0 @tab H
@item @var{:west} @tab 0 @tab H/2
@end multitable


A @var{: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 @var{:forget} instead.  A @var{: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 @var{:on}. The window's background is displayed (unless it is
@var{:none}), and zero or more @var{:exposure} events are
generated.
@table @var
@item bit-gravity
Type @var{bit-gravity}.
@end table

@end defun


@defun setf (window-border) window border

@table @var
@item window
A @var{window}.
@item border
Either a @var{pixel}, a @var{pixmap}, or @var{:copy}.
@end table

Changes the @emph{border} attribute of the @emph{window} to the
specified value. This operation is not allowed on an
@var{: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 @var{: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
@var{:copy}, the parent's border is copied and used; subsequent
changes to the parent's border do not affect the window border.
@table @var
@item border
Either a @var{pixel}, a @var{pixmap}, or @var{:copy}.
@end table

@end defun


@defun window-class window

@table @var
@item window
A @var{window}.
@end table

Returns the @emph{class} of the specified @emph{window}.
@table @var
@item class
Either @var{:input-output} or @var{:input-only}.
@end table

@end defun


@defun window-colormap window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) changes the value of the colormap
attribute for the specified @emph{window}. A value of @var{:copy} is
never returned, since the parent's colormap attribute is actually
copied, but the attribute can be set to @var{:copy} in a @code{setf}
form. Changing the colormap of a window (defining a new map, not
changing the contents of the existing map) generates a
@var{:colormap-notify} event. Changing the colormap of a visible
window may have no immediate effect on the screen
(@pxref{install-colormap}). The default colormap of a new window is
@var{:copy}.
@table @var
@item colormap
Type @var{colormap} or @var{null}.
@end table

@end defun


@defun window-colormap-installed-p window

@table @var
@item window
A @var{window}.
@end table

Returns non-@var{nil} if the colormap associated with this
@emph{window} is installed. Otherwise, this function returns
@var{nil}.
@table @var
@item colormap-installed-p
Type @var{boolean}.
@end table

@end defun


@defun setf (window-cursor) window cursor

@table @var
@item window
A @var{window}.
@item cursor
Either @var{cursor} or @var{:none}.
@end table

Changes the @emph{cursor} attribute of the @emph{window} to the
specified value. Changing the cursor of a root window to @var{: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
@var{:none}.

@table @var
@item cursor
Type @var{cursor} or @var{:none}.
@end table

@end defun


@defun window-display window

@table @var
@item window
A @var{window}.
@end table

Returns the @var{display} object associated with the specified
@emph{window}.
@table @var
@item display
Type @var{display}.
@end table

@end defun


@defun window-do-not-propagate-mask window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{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
@var{device-event-mask-class}. @xref{Selecting Events}.
@table @var
@item do-not-propagate-mask
Type @var{mask32}.
@end table

@end defun


@defun window-equal window-1 window-2

@table @var
@item window-1
@itemx window-2
The windows to compare for equality.
@end table

Returns non-@var{nil} if the two arguments are the same window, and
@var{nil} if they are not.
@table @var
@item equal-p
Type @var{boolean}.
@end table

@end defun


@defun window-event-mask window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) changes the value of the event-mask
attribute for the @emph{window}.  The default event-mask of a new
window is zero.
@table @var
@item event-mask
Type @var{mask32}.
@end table

@end defun


@defun window-gravity window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) changes the gravity attribute of the
@emph{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 @var{:north-west}.

For example, suppose the size of the window's parent is changed by
@emph{W} pixels in width and @emph{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 @var{:configure-notify} event
followed by a @var{:gravity-notify} event.

@multitable {Gravity} {X Change} {Y Change}
@item @var{:center} @tab @emph{W/}2 @tab @emph{H/}2
@item @var{:east} @tab @emph{W} @tab @emph{H/}2
@item @var{:north} @tab @emph{W/}2 @tab 0
@item @var{:north-east} @tab @emph{W} @tab 0
@item @var{:north-west} @tab 0 @tab 0
@item @var{:south} @tab @emph{W/}2 @tab @emph{H}
@item @var{:south-east} @tab W @tab H
@item @var{:south-west} @tab 0 @tab H
@item @var{:west} @tab 0 @tab H/2
@end multitable


A @var{:static} gravity indicates that the position of the window
should not move relative to the origin of the root window.

An @var{:unmap} gravity is like @var{:north-west}, except the window
is also unmapped and an @var{:unmap-notify} event is generated. This
@var{:unmap-notify} event is generated after the
@var{:configure-notify} event is generated for the parent.
@table @var
@item gravity
Type @var{win-gravity}.
@end table

@end defun


@defun window-id window

@table @var
@item window
A @var{window}.
@end table

Returns the unique ID assigned to @emph{window}.
@table @var
@item id
Type @var{resource-id}.
@end table

@end defun


@defun window-map-state window

@table @var
@item window
A @var{window}.
@end table

Returns the map state of @emph{window}. A window is @var{:unviewable}
if it is mapped but some ancestor is unmapped.
@table @var
@item map-state
One of @var{:unmapped}, @var{:unviewable}, or @var{:viewable}.
@end table

@end defun


@defun window-override-redirect window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) changes the value of the
override-redirect attribute for @emph{window}.  The default
override-redirect of a new window is @var{:off}.

The override-redirect attribute determines whether or not attempts to
change window geometry or parent hierarchy can be @emph{redirected} by
a window manager or some other client. The functions that might be
affected by the override-redirect attribute are
@var{circulate-window-down}, @var{circulate-window-up},
@var{drawable-border-width}, @var{drawable-height},
@var{drawable-width}, @var{drawable-x}, @var{drawable-y},
@var{map-window}, and @var{window-priority}.
@table @var
@item override-redirect
Either @var{:on} or @var{:off}.
@end table

@end defun


@defun window-p object

@table @var
@item window-p
Type @var{boolean}.
@end table

Returns non-@var{nil} if the @emph{object} argument is a window; otherwise, it returns @var{nil}.
@end defun

@defun window-plist window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) sets the property list for the specified
@emph{window}. This function provides a hook where extensions can hang
data.
@table @var
@item plist
A property list.
@end table

@end defun



@defun setf (window-priority window) (&optional sibling) mode

@table @var
@item window
A @var{window}.

@item sibling
An optional argument specifying that @emph{window} is to be restacked
relative to this sibling @var{window}.

@item mode
One of @var{:above}, @var{:below}, @var{:bottom-if}, @var{:opposite}, or @var{:top-if}.
@end table

Changes the stacking priority element of the @emph{window} to the
specified value. It is an error if the @emph{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 @var{: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.
@table @var
@item mode
One of @var{:above}, @var{:below}, @var{:bottom-if}, @var{:opposite}, or @var{:top-if}.
@end table

@end defun


@defun window-save-under window

@table @var
@item window
A @var{window}.
@end table

Returns and (with @code{setf}) changes the value of the save-under
attribute for the specified @emph{window}. Changing the save-under
attribute of a mapped window may have no immediate effect.
@table @var
@item save-under
Either @var{:on} or @var{:off}.
@end table

@end defun

@defun window-visual window

@table @var
@item window
A @var{window}.
@end table

Returns the @emph{visual-type} associated with the specified @emph{window}.
@table @var
@item visual-type
Type @var{card29}.
@end table

@end defun



@defmac with-state drawable &body body
@anchor{with-state}

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 @emph{body}. The @emph{body} is not executed within a
@var{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. @var{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 @emph{drawable}.  The number of server requests sent depends on
the sequence of calls to reader and @code{setf} functions within the
dynamic extent of the @emph{body}. There are two groups of reader and
@code{setf} functions--the Window Attributes group and the Drawable
Geometry group--as shown in Table 4-1.

@multitable {Group} {Reader Functions} {Setf Functions}

@item Window Attributes @tab @var{window-all-event-masks} @tab @var{window-background}

@item @tab @var{window-backing-pixel} @tab @var{window-backing-pixel}
@item @tab @var{window-backing-planes} @tab @var{window-backing-planes}
@item @tab @var{window-backing-store} @tab @var{window-backing-store}
@item @tab @var{window-bit-gravity} @tab @var{window-bit-gravity}
@item @tab @var{window-class} @tab @var{window-border}
@item @tab @var{window-colormap} @tab @var{window-colormap}
@item @tab @var{window-colormap-installed-p} @tab @var{window-cursor}
@item @tab @var{window-do-not-propagate-mask} @tab @var{window-do-not-propagate-mask}
@item @tab @var{window-event-mask} @tab @var{window-event-mask}
@item @tab @var{window-gravity} @tab @var{window-gravity}
@item @tab @var{window-map-state} @tab
@item @tab @var{window-override-redirect} @tab @var{window-override-redirect}
@item @tab @var{window-save-under} @tab @var{window-save-under}
@item @tab @var{window-visual} @tab

@item Drawable Geometry @tab @var{drawable-border-width} @tab @var{drawable-border-width}

@item @tab @var{drawable-depth} @tab @var{drawable-height}
@item @tab @var{drawable-height} @tab @var{drawable-width}
@item @tab @var{drawable-root} @tab @var{drawable-x}
@item @tab @var{drawable-width} @tab @var{drawable-y}
@item @tab @var{drawable-x} @tab @var{window-priority}
@item @tab @var{drawable-y} @tab

@end multitable


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

@var{with-state} sends a single request to update all its cached
values for the @emph{drawable} before the first call to a reader
function within the @emph{body} and also before the first call to a
reader function following a sequence of calls to @code{setf} functions
from the corresponding group.

@table @var
@item drawable
A @var{display}.
@item body
The forms in which attributes accesses are batched.
@end table

@end defmac


@node Stacking Order, Window Hierarchy, Window Attributes, Windows and Pixmaps
@section Stacking Order


Sibling windows can @emph{stack} on top of each other. Windows above
can @emph{obscure} or @emph{occlude} lower windows. This relationship
between sibling windows is known as the stacking order. The
@var{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
@var{:exposure} events for the window and any mapped subwindows that
were formerly obscured. Lowering a mapped window can generate
@var{:exposure} events on any windows it formerly obscured.

@defun circulate-window-down window

@table @var
@item window
A @var{window}.
@end table

Lowers the highest mapped child of the specified @emph{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 @var{:substructure-redirect} on the
@emph{window}, a @var{:circulate-request} event is generated, and no
further processing is performed. Otherwise, the child window is
lowered and a @var{:circulate-notify} event is generated if the
@emph{window} is actually restacked.

@end defun


@defun circulate-window-up window

@table @var
@item window
A @var{window}.
@end table

Raises the lowest mapped child of the specified @emph{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 @var{:substructure-redirect} on the
@emph{window}, a @var{:circulate-request} event is generated, and no
further processing is performed. Otherwise, the child window is raised
and a @var{:circulate-notify} event is generated if the @emph{window}
is actually restacked.

@end defun

@node Window Hierarchy, Mapping Windows, Stacking Order, Windows and Pixmaps
@section 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.

@defun drawable-root drawable

@table @var
@item drawable
A @var{drawable}.
@end table

Returns the root window of the specified @emph{drawable}.

@table @var
@item root-window
Type @var{window}.
@end table

@end defun

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

@table @var
@item window
A @var{window}.
@item :result-type
A valid type specifier for a sub-type of @var{sequence}. The default is a @var{list}.
@end table

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

@table @var
@item children
Type @var{sequence} of @var{window}.
@item parent
Type @var{window} or @var{null}.
@item root
Type @var{window}.
@end table

@end defun


@defun reparent-window window parent x y

@table @var
@item window
A @var{window}.
@item parent
The new parent @var{window}.
@item x
@itemx y
The position (type @var{int16}) of the @emph{window} in its new
@emph{parent}. These coordinates are relative to the @emph{parent}'s
origin, and specify the new position of the upper, left, outer corner
of the @emph{window}.
@end table

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

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

After reparenting the specified @emph{window,} a
@var{:reparent-notify} event is generated. The override-redirect
attribute of the @emph{window} is passed on in this event. Window
manager clients normally should ignore this event if this attribute is
@var{:on}. @xref{Events and Input}, for more information on
@var{:reparent-notify} event processing. Finally, if the specified
@emph{window} was originally mapped, a @var{map-window} operation is
automatically performed on it.

The X server performs normal exposure processing on formerly obscured
windows. It might not generate @var{:exposure} events for regions from
the initial @var{unmap-window} operation if they are immediately
obscured by the final @var{map-window} operation.

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

@itemize @bullet

@item
The new @emph{parent} window is not on the same screen as the old parent window.

@item
The new @emph{parent} window is the specified @emph{window} or an
inferior of the specified @emph{window}.

@item
The specified @emph{window} has a @var{:parent-relative} background
attribute and the new @emph{parent} window is not the same depth as
the specified @emph{window}.
@end itemize



@end defun

@defun translate-coordinates source source-x source-y destination

@table @var
@item source
A @var{window} defining the source coordinate system.

@item source-x
@itemx source-y
Coordinates (@var{int16}) relative to the origin of the @emph{source}
@var{window}.

@item destination
A @var{window} defining the destination coordinate system.

@end table

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

@table @var
@item destination-x
Type @var{int16} or @var{null}.
@item destination-y
Type @var{int16} or @var{null}.
@item destination-child
Type @var{window} or @var{null}.
@end table

@end defun


@node Mapping Windows, Destroying Windows, Window Hierarchy, Windows and Pixmaps
@section Mapping Windows

A window is considered mapped if a @var{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:

@itemize @bullet

@item  It is obscured by another opaque sibling window.
@item  One of its ancestors is not mapped.
@item  It is entirely clipped by an ancestor.

@end itemize


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. @var{:exposure} events are generated for the window when
part or all of it becomes visible on the screen. A client only
receives the @var{:exposure} events if it has selected them. Mapping
or unmapping a window does not change its stacking order priority.

@defun map-window window

@table @var
@item window
A @var{window}.
@end table
@anchor{map-window}

Maps the @emph{window}. This function has no effect when the
@emph{window} is already mapped.

If the override-redirect attribute of the @emph{window} is @var{:off}
and another client has selected @var{:substructure-redirect} on the
parent window, the X server generates a @var{:map-request} event and
the @var{map-window} function does not map the
@emph{window}. Otherwise, the @emph{window} is mapped, and the X
server generates a @var{:map-notify} event.

If the @emph{window} becomes visible and no earlier contents for it
are remembered, @var{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 @var{:exposure} events. If a backing-store was maintained while
the window was unmapped, no @var{: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.

@var{map-window} generates @var{:exposure} events on each
@var{:input-output} window that it causes to become visible.



@end defun

@defun map-subwindows window

@table @var
@item window
A @var{window}.
@end table

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



@end defun


@defun unmap-window window

@table @var
@item window
A @var{window}.
@end table

Unmaps the specified @emph{window} and causes the X server to generate
an @var{:unmap-notify} event. If the specified @emph{window} is
already unmapped, @var{unmap-window} has no effect.  Normal exposure
processing on formerly obscured windows is performed. Any child window
is no longer viewable. Unmapping the @emph{window} generates
@var{:exposure} events on windows that were formerly obscured by
@emph{window} and its children.



@end defun


@defun unmap-subwindows window

@table @var
@item window
A @var{window}.
@end table

Unmaps all child windows for the specified @emph{window} in bottom to
top stacking order. The X server generates an @var{:unmap-notify}
event on each child and @var{:exposure} events on formerly obscured
windows. Using this function is much more efficient than unmapping
child windows individually.



@end defun


@node Destroying Windows, Pixmaps, Mapping Windows, Windows and Pixmaps
@section 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,
@xref{Closing the Display}, and @xref{Client Termination}.

@defun destroy-window window

@table @var
@item window
A @var{window}.
@end table

Destroys the specified @emph{window} as well as all of its
inferiors. The windows should never again be referenced. If the
specified @emph{window} is mapped, it is automatically unmapped.  The
window and all of its inferiors are then destroyed, and a
@var{:destroy-notify} event is generated for each window. The ordering
of the @var{:destroy-notify} events is such that for any given window
being destroyed, @var{: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 @emph{window} is a root window, no windows are
destroyed. Destroying a mapped window generates @var{:exposure} events
on other windows that the mapped window obscured.



@end defun

@defun destroy-subwindows window

@table @var
@item window
A @var{window}.
@end table

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


@end defun


@node Pixmaps,  , Destroying Windows, Windows and Pixmaps
@section Pixmaps


A @emph{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 2@emph{n}-1, where @emph{n}
is the depth of the pixmap. A pixmap can also be thought of as a stack
of @emph{n} bitmaps. A @emph{bitmap} is a single bit pixmap of depth
1. CLX provides functions to:

@itemize @bullet

@item  Create or free a pixmap

@item  Test if an object is a pixmap

@item  Test if two pixmap objects are equal

@item  Return the pixmap resource ID from a @var{pixmap} object
@end itemize



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.

@defun create-pixmap &key :width :height :depth :drawable

@table @var
@item :width
@itemx :height
The nonzero width and height (type @var{card16}).

@item :depth
The depth (type @var{card8}) of the pixmap.

@item :drawable
A @var{drawable} which determines the screen where the pixmap will be used.
@end table

Creates a pixmap of the specified @var{:width}, @var{:height}, and
@var{:depth}. It is valid to pass a window whose class is
@var{:input-only} as the @var{:drawable} argument. The @var{:width}
and @var{:height} arguments must be nonzero. The @var{:depth} must be
supported by the screen of the specified @var{:drawable}.

@table @var
@item pixmap
Type @var{pixmap}.
@end table

@end defun


@defun free-pixmap pixmap

@table @var
@item pixmap
A @var{pixmap}.
@end table

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



@end defun


@defun pixmap-display pixmap

@table @var
@item pixmap
A @var{pixmap}.
@end table

Returns the @var{display} object associated with the specified @emph{pixmap}.

@table @var
@item display
Type @var{display}.
@end table

@end defun


@defun pixmap-equal pixmap-1 pixmap-2

@table @var
@item pixmap-1
@itemx pixmap-2
A three-dimensional array of bits to be tested.
@end table

Returns true if the two arguments refer to the same server resource,
and @var{nil} if they do not.



@end defun


@defun pixmap-id pixmap

@table @var
@item pixmap
A @var{pixmap}.
@end table

Returns the unique resource ID that has been assigned to the specified
@emph{pixmap}.

@table @var
@item id
Type @var{resource-id}.
@end table

@end defun


@defun pixmap-p object

@table @var
@item pixmap
Type @var{boolean}.
@end table

Returns true if the argument is a @var{pixmap} object and @var{nil}
otherwise.

@end defun

@defun pixmap-plist pixmap

@table @var
@item pixmap
A @var{pixmap}.
@end table

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

@table @var
@item plist
A property list.
@end table

@end defun


@node Graphics Contexts, Graphic Operations, Windows and Pixmaps, Top
@chapter Graphics Contexts

Clients of the X Window System specify the visual attributes of
graphical output primitives by using @emph{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 @var{gcontext}
and defines functions to create, modify, and manipulate @var{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:

@enumerate

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

@item
Inquiring @var{gcontext} contents -- Accessor functions can be used
to return the value of any individual @var{gcontext} component by
reading the copy of the @var{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
@var{gcontext}.
@end enumerate


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
@var{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:

@itemize @bullet

@item  Create a graphics context

@item  Return the contents of a graphics context

@item  Change the contents of a graphics context

@item  Copy a graphics context

@item  Free a graphics context
@end itemize


@menu
* Creating Graphics Contexts::
* Graphics Context Attributes::
* Copying Graphics Contexts::
* Destroying Graphics Contexts::
* Graphics Context Cache::
@end menu

@node Creating Graphics Contexts, Graphics Context Attributes, Graphics Contexts, Graphics Contexts
@section Creating Graphics Contexts

To create a graphics context, use @var{create-gcontext}.

@defun 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

@table @var
@item :cache-p
Specifies if this graphics context should be cached locally by CLX. If
@var{nil} then the state is not cached, otherwise a local cache is
kept.
@item :drawable
The @var{drawable} whose root and depth are to be associated with
this graphics context. This is a required keyword argument.
@item :arc-mode
@itemx :background
@itemx :cap-style
@itemx :clip-mask
@itemx :clip-ordering
@itemx :clip-x
@itemx :clip-y
@itemx :dash-offset
@itemx :dashes
@itemx :exposures
@itemx :fill-rule
@itemx :fill-style
@itemx :font
@itemx :foreground
@itemx :function
@itemx :join-style
@itemx :line-style
@itemx :line-width
@itemx :plane-mask
@itemx :stipple
@itemx :subwindow-mode
@itemx :tile
@itemx :ts-x
@itemx :ts-y
Initial attribute values for the graphics context.
@end table

Creates, initializes, and returns a graphics context
(@var{gcontext}). The graphics context can only be used with
destination drawables having the same root and depth as the specified
@var{:drawable}. If @var{:cache-p} is non-@var{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 (@code{setf} and @var{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
@var{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 @var{nil}
causes the default value to be used. These default values are as
follows:

@multitable {Component} {Default Value}
@item @var{arc-mode} @tab @var{:pie-slice}
@item @var{background} @tab 1
@item @var{cap-style} @tab @var{:butt}
@item @var{clip-mask} @tab @var{:none}
@item @var{clip-ordering} @tab @var{:unsorted}
@item @var{clip-x} @tab 0
@item @var{clip-y} @tab 0
@item @var{dash-offset} @tab 0
@item @var{dashes} @tab 4 (that is, the list '(4, 4))
@item @var{exposures} @tab @var{:on}
@item @var{fill-rule} @tab @var{:even-odd}
@item @var{fill-style} @tab @var{:solid}
@item @var{font} @tab server dependent
@item @var{foreground} @tab 0
@item @var{function} @tab @var{boole-1}
@item @var{join-style} @tab @var{:miter}
@item @var{line-style} @tab @var{:solid}
@item @var{line-width} @tab 0
@item @var{plane-mask} @tab A bit mask of all ones
@item @var{stipple} @tab Pixmap of unspecified size filled with ones
@item @var{subwindow-mode} @tab @var{:clip-by-children}
@item @var{tile} @tab Pixmap of an unspecified size filled with the foreground pixel (that is, the client-specified pixel if any, or else 0)
@item @var{ts-x} @tab 0
@item @var{ts-y} @tab 0
@end multitable


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

@table @var
@item gcontext
Type @var{gcontext}.
@end table

@end defun


@node Graphics Context Attributes, Copying Graphics Contexts, Creating Graphics Contexts, Graphics Contexts
@section Graphics Context Attributes

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

@defun gcontext-arc-mode gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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 @var{draw-arcs} function. A value
of @var{:chord} specifies that arcs are filled inward to the chord
between the end points of the arc. @var{:pie-slice} specifies that
arcs are filled inward to the center point of the arc, creating a pie
slice effect.

@table @var
@item arc-mode
Either @var{:chord} or @var{:pie-slice}.
@end table

@end defun


@defun gcontext-background gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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.

@table @var
@item background
Type @var{card32}.
@end table

@end defun


@defun gcontext-cache-p gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

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

@table @var
@item cache-p
Type @var{boolean}.
@end table

@defun gcontext-cap-style gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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:
@multitable {Cap-Style} {Interpretations}
@item @var{:butt}
@tab Square at the end point (perpendicular to the slope of the line) with no projection beyond.

@item @var{:not-last}
@tab
Equivalent to @var{:butt}, except that for a line-width of zero or one
the final end point is not drawn.

@item @var{:projecting}
@tab
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
@var{:butt} for line-width zero or one.

@item @var{:round}
@tab
A circular arc with the radius equal to 1/2 of the line-width,
centered on the end point. This is equivalent to @var{:butt} for
line-width zero or one.
@end multitable

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.

@multitable {Cap-Style} {Line-Width} {Effect}
@item @var{:butt} @tab thin
@tab
Device dependent, but the desired effect is that a single pixel is
drawn.

@item @var{:butt} @tab wide
@tab
Nothing is drawn.

@item @var{:not-last} @tab thin
@tab
Device dependent, but the desired effect is that nothing is drawn.

@item @var{:projecting} @tab thin
@tab
Same as @var{:butt} with thin line-width.

@item @var{:projecting} @tab wide
@tab
The closed path is a square, aligned with the coordinate axes,
centered at the end point, with sides equal to the line-width.

@item @var{:round} @tab wide
@tab
The closed path is a circle, centered at the end point, with diameter equal to the line-width.

@item @var{:round} @tab thin
@tab
Same as @var{:butt} with thin line-width.

@end multitable

@table @var
@item cap-style
One of @var{:butt}, @var{:not-last}, @var{:projecting}, or @var{:round}.
@end table

@end defun


@defun gcontext-clip-mask gcontext &optional ordering

@table @var
@item gcontext
A @var{gcontext}.
@item ordering
One of @var{:unsorted}, @var{:y-sorted}, @var{:yx-banded}, @var{:yx-sorted}, or @var{nil}.
@end table

Returns and (with @code{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 @var{rect-seq} or as the values @var{:none}
or @var{nil}. The ordering argument can be specified only with
@code{setf} when the new clip-mask is a @var{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 @var{: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 @var{: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
@var{:unsorted} means the rectangles are in arbitrary order. A value
of @var{:y-sorted} means that the rectangles are non-decreasing in
their Y origin. A @var{:yx-sorted} value is like @var{:y-sorted} with
the additional constraint that all rectangles with an equal Y origin
are non-decreasing in their X origin. A @var{:yx-banded} value
additionally constrains @var{: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.



@end defun


@defun gcontext-clip-x gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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.

@table @var
@item clip-x
Type @var{int16}.
@end table

@end defun

@defun gcontext-clip-y gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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.
@table @var
@item clip-y
Type @var{int16}.
@end table

@end defun


@defun gcontext-dash-offset gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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.
@table @var
@item dash-offset
Type @var{card16}.
@end table

@end defun


@defun gcontext-dashes gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{setf}) changes the dashes attribute of the
specified graphics context.  The sequence must be non-empty and the
elements must be non-zero @var{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-@var{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, @emph{N}, for the dashes attribute
is an abbreviated way of specifying a two element sequence with both
elements equal to the specified value [@emph{N}, @emph{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.
@table @var
@item dashes
Type @var{sequence} or @var{card8}.
@end table

@end defun


@defun gcontext-display gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns the @var{display} object associated with the specified
@emph{gcontext}.
@table @var
@item display
Type @var{display}.
@end table

@end defun


@defun gcontext-equal gcontext-1 gcontext-2

@table @var
@item gcontext-1
@itemx gcontext-2
A @var{gcontext}.
@end table

Returns true if the two arguments refer to the same server resource,
and @var{nil} if they do not.
@table @var
@item equal-p
Type @var{boolean}.
@end table

@end defun


@defun gcontext-exposures gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{setf}) changes the exposures attribute of the
specified graphics context.

The exposures attribute in a graphics context controls the generation
of @var{:graphics-exposure} events for calls to the @var{copy-area}
and @var{copy-plane} functions. If @var{:on},
@var{:graphics-exposure} events will be reported when calling the
@var{copy-area} and @var{copy-plane} functions with this graphics
context. Otherwise, if @var{:off}, the events will not be reported.
@table @var
@item exposures
Either @var{:off} or @var{:on}.
@end table

@end defun


@defun gcontext-fill-rule gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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 @var{:even-odd} or @var{:winding}.

The @var{: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 @var{: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 @var{:even-odd} and @var{: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).
@table @var
@item fill-rule
Either @var{:even-odd} or @var{:winding}.
@end table

@end defun

@defun gcontext-fill-style gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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:

@table @var
@item :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.

@item :solid
Filled with the foreground pixel value.

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

@item :tiled
Filled with tile.
@end table


When drawing lines with line-style @var{:double-dash}, the filling of
the odd dashes are controlled by the fill-style in the following
manner:

@table @var
@item :opaque-stippled
Same as for even dashes.

@item :solid
Filled with the background pixel value.

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

@item :tiled
Filled the same as the even dashes.
@end table

@table @var
@item fill-style
One of @var{:opaque-stippled}, @var{:solid}, @var{:stippled}, or @var{:tiled}.
@end table

@end defun


@defun gcontext-font gcontext &optional metrics-p

@table @var
@item gcontext
A @var{gcontext}.

@item metrics-p
Specifies whether a pseudo-font is returned when the real font stored
in the graphics context is not known. The default is @var{nil}, which
means do not return a pseudo-font.
@end table

Returns and (with @code{setf}) changes the @emph{font} attribute of the
specified graphics context. If the stored font is known, it is
returned. If it is not known and the @emph{metrics-p} argument is
@var{nil}, then @var{nil} is returned. If the font is not known and
@emph{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 @var{font} object or a font name can be used. If a
font name is passed, @var{open-font} is call automatically to get the
@var{font} object.

@table @var
@item font
Type @var{font} or @var{null}.
@end table
@end defun

@end defun



@defun gcontext-foreground gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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.
@table @var
@item foreground
Type @var{card32}.
@end table

@end defun


@defun gcontext-function gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns the @emph{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 @var{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 @emph{S} and a
destination pixel @emph{D}.

@multitable {Symbol} {Result}
@item @var{boole-1}
@tab @emph{S}
@item @var{boole-2}
@tab @emph{D}
@item @var{boole-andc1}
@tab (logandc1 @emph{S D})
@item @var{boole-andc2}
@tab (logandc2 @emph{S D})
@item @var{boole-and}
@tab (logand @emph{S D})
@item @var{boole-c1}
@tab (lognot @emph{S})
@item @var{boole-c2}
@tab (lognot @emph{D})
@item @var{boole-clr}
@tab 0
@item @var{boole-eqv}
@tab (logeqv @emph{S D})
@item @var{boole-ior}
@tab (logior @emph{S D})
@item @var{boole-nand}
@tab (lognand @emph{S D})
@item @var{boole-nor}
@tab (lognor @emph{S D})
@item @var{boole-orc1}
@tab (logorc1 @emph{S D})
@item @var{boole-orc2}
@tab (logorc2 @emph{S D})
@item @var{boole-set}
@tab 1
@item @var{boole-xor}
@tab (logxor @emph{S D})
@end multitable

@table @var
@item function
Type @var{boole-constant}.
@end table

@end defun


@defun gcontext-id gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns the unique ID that has been assigned to the specified graphics
context.
@table @var
@item id
Type @var{resource-id}.
@end table

@end defun


@defun gcontext-join-style gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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:

@table @var
@item :bevel
Uses @var{:butt} end point styles with the triangular notch filled.
@item :miter
The outer edges of two lines extend to meet at an angle.
@item :round
A circular arc with diameter equal to the line-width, centered on the join point.
@end table

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.

@table @var
@item join-style
One of @var{:bevel}, @var{:miter}, or @var{:round}.
@end table

@end defun


@defun gcontext-line-style gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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:

@table @var
@item :solid
The full path is drawn.

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

@item :on-off-dash
Only the even dashes are drawn, with cap-style applied to all internal
ends of the individual dashes, except @var{:not-last} is treated as
@var{:butt}.
@end table

@table @var
@item line-style
One of @var{:dash}, @var{:double-dash}, or @var{:solid}.
@end table

@end defun


@defun gcontext-line-width gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns the @emph{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*@emph{sin}/2), y1 + (w*@emph{cos}/2)], [x1+ (w*@emph{sin}/2), y1 - (w*@emph{cos}/2)],@*
[x2 - (w*@emph{sin}/2), y2 + (w*@emph{cos}/2)], [x2 + (w*@emph{sin}/2), y2 - (w*@emph{cos}/2)]

where @emph{sin} is the sine of the angle of the line and @emph{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.

@enumerate
@item
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.

@item
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.
@end enumerate


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.
@table @var
@item line-width
Type @var{card16}.
@end table

@end defun


@defun gcontext-p gcontext

@table @var
@item gcontext
Type @var{boolean}.
@end table



Returns non-@var{nil} if the argument is a graphics context and

@end defun




@defun gcontext-plane-mask gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns the @emph{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:

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

	(logandc2
	 destination
	 plane-mask))
@end lisp

@table @var
@item plane-mask
Type @var{card32}.
@end table

@end defun


@defun gcontext-plist gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table



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

@table @var
@item gcontext-p
Type @var{list}.
@end table

@end defun


@defun gcontext-stipple gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns the @emph{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 @var{:stippled} (but not
@var{:opaque-stippled}), the stipple pattern is tiled in a single
plane and acts as an additional clip mask to be @var{and}ed 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
@var{query-best-stipple} and @var{query-best-tile}).

@table @var
@item stipple
Type @var{pixmap}.
@end table

@end defun


@defun gcontext-subwindow-mode gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns and (with @code{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 @var{:clip-by-children}, both
source and destination windows are clipped by all viewable
@var{:input-output} class children. This clipping is in addition to
the clipping provided by the clip-mode attribute. For a value of
@var{: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 @var{: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.
@table @var
@item subwindow-mode
One of @var{:clip-by-children} or @var{:include-inferiors}.
@end table

@end defun


@defun gcontext-tile gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns the @emph{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 @var{:stippled} (but not
@var{:opaque-stippled}), the stipple pattern is tiled in a single
plane and acts as an additional clip mask to be @var{and}ed 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
@var{query-best-stipple} and @var{query-best-tile}).
@table @var
@item tile
Type @var{pixmap}.
@end table

@end defun


@defun gcontext-ts-x gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns the @emph{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.
@table @var
@item ts-x
Type @var{int16}.
@end table

@end defun


@defun gcontext-ts-y gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Returns the @emph{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.
@table @var
@item ts-y
Type @var{int16}.
@end table

@end defun


@defun query-best-stipple width height drawable

@table @var
@item width
@itemx height
Specifies the width and height of the desired stipple pattern.
@item drawable
A @var{drawable}.
@end table

Returns the @emph{best-width} and @emph{best-height} for stipple
pixmaps on the @emph{drawable}.

The @emph{drawable} indicates the screen and possibly the window class
and depth. An @var{:input-only} window cannot be specified as the
@emph{drawable}. The size is returned as width and height values.

@table @var
@item best-width
@itemx best-height
Type @var{card16}.
@end table

@end defun


@defun query-best-tile width height drawable

@table @var
@item width
@itemx height
Specifies the width and height of the desired tile pattern.
@item drawable
A @var{drawable}.
@end table

Returns the @emph{best-width} and @emph{best-height} for tile pixmaps
on the @emph{drawable}.

The @emph{drawable} indicates the screen and possibly the window class
and depth. An @var{:input-only} window cannot be specified as the
@emph{drawable}. The size is returned as width and height values.

@table @var
@item best-width
@itemx best-height
Type @var{card16}.
@end table

@end defun


@node Copying Graphics Contexts, Destroying Graphics Contexts, Graphics Context Attributes, Graphics Contexts
@section 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 @code{setf} to copy @var{gcontext} attributes
individually.

@defun copy-gcontext source destination

@table @var
@item source
The source @var{gcontext}.
@item destination
The destination @var{gcontext}.
@end table

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.



@end defun


@defun copy-gcontext-components source destination &rest keys

@table @var
@item source
The source @var{gcontext}.
@item destination
The destination @var{gcontext}.

@item keys
The remaining arguments are keywords, of type @var{gcontext-key},
which specify which attributes of the graphics context are to be
copied.
@end table

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.


@end defun


@node Destroying Graphics Contexts, Graphics Context Cache, Copying Graphics Contexts, Graphics Contexts
@section Destroying Graphics Contexts

To destroy a graphics context, use @var{free-gcontext.}

@defun free-gcontext gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

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


@end defun


@node Graphics Context Cache,  , Destroying Graphics Contexts, Graphics Contexts
@section Graphics Context Cache

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


@defun force-gcontext-changes gcontext

@table @var
@item gcontext
A @var{gcontext}.
@end table

Forces any delayed changes to the specified graphics context to be
sent out to the server.  Note that @var{force-gcontext-changes} is
called by all of the graphics functions.



@end defun

@defmac 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
@anchor{with-gcontext}

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

@table @var
@item gcontext
A @var{gcontext}.
@item :arc-mode
@itemx :background
@itemx :cap-style
@itemx :clip-mask
@itemx :clip-ordering
@itemx :clip-x
@itemx :clip-y
@itemx :dashes
@itemx :dash-offset
@itemx :exposures
@itemx :fill-rule
@itemx :fill-style
@itemx :font
@itemx :foreground
@itemx :function
@itemx :join-style
@itemx :line-style
@itemx :line-width
@itemx :plane-mask
@itemx :stipple
@itemx :subwindow-mode
@itemx :tile
@itemx :ts-x
@itemx :ts-y
These keyword arguments and associated values specify which graphics
context components are to be changed. Any components not specified are
left unmodified. @xref{Creating Graphics Contexts}, for more information.
@item body
The body of code which will have access to the altered graphics context.
@end table

@end defmac

@node Graphic Operations, Images, Graphics Contexts, Top
@chapter 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:

@itemize @bullet

@item  Operate on areas and planes

@item  Draw points

@item  Draw lines

@item  Draw rectangles

@item  Draw arcs

@item  Draw text

@end itemize


@menu
* Area and Plane Operations::
* Drawing Points::
* Drawing Lines::
* Drawing Rectangles::
* Drawing Arcs::
* Drawing Text::
@end menu

@node Area and Plane Operations, Drawing Points, Graphic Operations, Graphic Operations
@section Area and Plane Operations


@var{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 @var{draw-rectangle}, which sets the pixmap to a known
value. @xref{Drawing Rectangles}, for information on
@var{draw-rectangle}.

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

@table @var
@item window
A @var{window}.

@item :x
@itemx :y
Upper-left corner of the area to be cleared. These coordinates are
relative to the @emph{window} origin. Type is @var{int16}.

@item :width
The width of the area to clear or @var{nil} to clear to the remaining
width of the window. Type is @var{card16} or @var{null}.

@item :height
The height of the area to clear or @var{nil} to clear to the remaining
height of the window. Type is @var{card16} or @var{null}.

@item :exposures-p
Specifies if @var{:exposure} events should be generated for the
affected areas. Type @var{boolean}.
@end table

Draws a rectangular area in the specified @emph{window} with the
background pixel or pixmap of the @emph{window}. The @var{:x} and
@var{:y} coordinates are relative to the @emph{window} origin, and
specify the upper-left corner of the rectangular area that is to be
cleared. A @var{nil} or zero value for @var{:height} or @var{:width}
clears the remaining area (height - y or width - x). If the
@emph{window} has a defined background tile, the rectangle is tiled by
using a plane-mask of all ones and a function of @var{:copy}. If the
@emph{window} has background @var{:none}, the contents of the
@emph{window} are not changed. In either case, if @var{:exposures-p}
is non-@var{nil}, then one or more @var{: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 @emph{window}, use
(@var{clear-area} @emph{window}).


@end defun

@defun copy-area source gcontext source-x source-y width height destination destination-x destination-y

@table @var
@item source
Source @var{drawable}.

@item gcontext
The graphics context to use during the copy operation.

@item source-x
@itemx source-y
The x and y coordinates of the upper-left corner of the area in the
@emph{source} @var{drawable}. These coordinates are relative to the
@emph{source} @var{drawable} origin.  Type is @var{int16}.

@item width
@itemx height
The width and height of the area being copied. These apply to both the
@emph{source} and @emph{destination} areas. Type is @var{card16}.

@item destination
The destination @var{drawable}.

@item destination-x
@itemx destination-y
The x and y coordinates of the upper left corner of the area in the
@emph{destination} @var{drawable}. These coordinates are relative to
the @emph{destination} @var{drawable} origin. Type is @var{int16}.
@end table

Copies the specified rectangular area from the @emph{source}
@var{drawable} to the specified rectangular area of the
@emph{destination} @var{drawable}, combining them as specified in the
supplied graphics context (@emph{gcontext}). The @emph{x} and @emph{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 @emph{source} area are obscured and have not
been retained in backing store, or regions outside the boundaries of
the @emph{source} @var{drawable} are specified, those regions are not
copied. Instead, the following occurs on all corresponding
@emph{destination} regions that are either visible or are retained in
backing store:

@itemize @bullet

@item
If the @emph{destination} rectangle is a window with a background
other than @var{:none}, these corresponding regions of the
@emph{destination} are tiled, using plane-mask of all ones and
function of @var{boole-1} (copy source), with that background.

@item
If the exposures attribute of the graphics context is @var{:on},
then @var{:graphics-exposure} events for all corresponding
@emph{destination} regions are generated (regardless of tiling or
whether the @emph{destination} is a window or a pixmap).

@item
If exposures is @var{:on} but no regions are exposed, a
@var{:no-exposure} event is generated.  Note that by default,
exposures is @var{:on} for new graphics contexts. @xref{Graphics Contexts}, for further information.

@end itemize


@end defun

@defun copy-plane source gcontext plane source-x source-y width height destination destination-x destination-y

@table @var
@item source
The source @var{drawable}.
@item gcontext
The graphics context to use during the copy operation.
@item plane
Specifies the bit-plane of the @emph{source} @var{drawable}. Exactly one bit must be set.
Type is @var{pixel}.
@item source-x
@itemx source-y
The @emph{x} and @emph{y} coordinates of the upper-left corner of the
area in the @emph{source} @var{drawable}. These coordinates are
relative to the @emph{source} @var{drawable} origin.  Type is
@var{int16}.

@item width
@itemx height
The width and height of the area being copied. These apply to both the
@emph{source} and @emph{destination} areas. Type is @var{card16}.

@item destination
The destination @var{drawable}.

@item destination-x
@itemx destination-y

The x and y coordinates of the upper-left corner of the destination
area in the @emph{destination} @var{drawable}. These coordinates are
relative to the @emph{destination} @var{drawable} origin. Type is
@var{int16}.
@end table

Uses a single bit plane of the specified rectangular area of the
@emph{source} @var{drawable} along with the specified graphics context
(@emph{gcontext}) to modify the specified rectangle area of the
@emph{destination} @var{drawabl}e. The drawables specified by the
@emph{source} and @emph{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
@emph{destination} and with a size specified by the @emph{source}
area. It then uses the foreground and background from the graphics
context (foreground where the bit-plane in @emph{source} contains a
one bit, background where the bit-plane in @emph{source} contains a
zero bit), and the equivalent of a @var{copy-area} operation is
performed with all the same exposure semantics. This can also be
thought of as using the specified region of the @emph{source}
bit-plane as a stipple with a fillstyle of @var{:opaque-stippled} for
filling a rectangular area of the @emph{destination}.



@end defun

@node Drawing Points, Drawing Lines, Area and Plane Operations, Graphic Operations
@section Drawing Points

The @var{draw-point} and @var{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 @var{draw-point} function uses the foreground pixel and function components of the
graphics context to draw a single point into the specified drawable, while @var{draw-points}
draws multiple points into the specified drawable. These functions are not affected by
the tile or stipple in the graphics context.


@defun draw-point drawable gcontext x y

@table @var
@item drawable
The destination @var{drawable}.
@item gcontext
The graphics context for drawing the point.
@item x
@itemx y
The @emph{x} and @emph{y} coordinates of the point drawn. Type is @var{int16}.
@end table
Combines the foreground pixel in the @emph{gcontext} with the pixel in
the @emph{drawable} specified by the @emph{x} and @emph{y}
coordinates.


@end defun

@defun draw-points drawable gcontext points &optional relative-p

@table @var
@item drawable
The destination @var{drawable}.
@item gcontext
The graphics context for drawing the points.
@item points
A list of points to be drawn in the order listed. The first point is always relative
to the @emph{drawable}'s origin; if @emph{relative-p}, the rest of the points are drawn relative to the
previous point, else they are drawn relative to the @emph{drawable}'s origin. Type is
@var{point-seq}.
@item relative-p
Specifies the coordinate mode used for drawing the pixels either relative to
the origin or to the previous point. Type @var{boolean}.
@end table

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

@var{draw-points} requires a mode argument, @emph{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 @emph{drawable}'s origin or to the previous
point, depending on the value of @emph{relative-p}.


@end defun


@node Drawing Lines, Drawing Rectangles, Drawing Points, Graphic Operations
@section Drawing Lines


The @var{draw-line}, @var{draw-lines}, and @var{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 @var{draw-lines} function also uses the join-style graphics context component.

@defun draw-line drawable gcontext x1 y1 x2 y2 &optional relative-p

@table @var
@item drawable
The destination @var{drawable}.
@item gcontext
The graphics context for drawing the line.
@item x1
@itemx y1
@itemx x2
@itemx y2
The end points of the line.
@item 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 @emph{drawable}'s origin.
@end table

Draws a line from the point @emph{x1},@emph{y1} to the point
@emph{x2},@emph{y2}. When @emph{relative-p} is true, the first point
is relative to the destination origin but the second point is relative
to the first point.  When @emph{relative-p} is @var{nil}, both points
are relative to the destination origin.


@end defun


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

@table @var
@item drawable
The destination @var{drawable}.
@item gcontext
The graphics context for drawing the lines.
@item points
A list of points that define the lines. Type is @var{point-seq}.
@item :relative-p
The coordinate mode of the points.
@item :fill-p
When true, a filled polygon is drawn instead of a polyline.
@item :shape
A hint that allows the server to use the most efficient area fill algorithm.
Either @var{:convex}, @var{:non-convex}, or @var{:complex}.
@end table

Draws a line between each pair of @emph{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 @var{:relative-p} is true, the first point is always relative to
the destination origin, but the rest are relative to the previous
point. When @var{:relative-p} is @var{nil}, the rest of the points
are drawn relative to the destination origin.

When @var{:fill-p} is true, the polygon defined by the @emph{points}
list is filled. The @var{:shape} keyword provides the server with a
hint about how to fill the polygon. @var{:shape} can be either
@var{:complex} (by default), @var{:convex}, or @var{:non-convex}.

The @var{: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 @var{: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 @var{: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.

@var{NOTE:} Unless you are sure that a shape is @var{:convex} or
@var{:non-convex}, it should always be drawn as a @var{:complex}
shape. If @var{:convex} or @var{:non-convex} is specified
incorrectly, the graphics result is undefined.


@end defun


@defun draw-segments drawable gcontext segments

@table @var
@item drawable
The destination @var{drawable} to receive the line segments.
@item gcontext
Specifies the graphics context for drawing the lines.
@item segments
The points list for the segments to draw. Type is @var{seq}.
@end table

Draws multiple lines, not necessarily connected. @emph{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 @emph{segments}. Unlike @var{draw-lines}, no
joining is performed at coincident end points.


@end defun


@node Drawing Rectangles, Drawing Arcs, Drawing Lines, Graphic Operations
@section Drawing Rectangles


The @var{draw-rectangle} and @var{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:

@display
[x,y,] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
@end display

@var{draw-rectangle} and @var{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.

@defun draw-rectangle drawable gcontext x y width height &optional fill-p

@table @var
@item drawable
The destination @var{drawable}.

@item gcontext
The graphics context for drawing the rectangle.

@item x
@itemx 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 @var{int16}.

@item width
@itemx height
Specifies the width and height that define the outline of the rectangle.
Type is @var{card16}.

@item fill-p
Specifies whether the rectangle is filled or not. Type @var{boolean}.
@end table

Draws a rectangle defined by the @emph{x}, @emph{y}, @emph{width}, and

@emph{height} arguments.



@end defun


@defun draw-rectangles drawable gcontext rectangles &optional fill-p

@table @var
@item drawable
The destination @var{drawable}.

@item gcontext
The graphics context.

@item rectangles
A list specifying the upper left corner x and y, width and height of the
rectangles. Type is @var{rect-seq}.

@item fill-p
Specified if the rectangles are filled or not. Type is @var{boolean}.
@end table

Draws the rectangles in the order listed in @emph{rectangles}. For the
specified @emph{rectangle} or @emph{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.



@end defun

@node Drawing Arcs, Drawing Text, Drawing Rectangles, Graphic Operations
@section Drawing Arcs

@var{draw-arc} draws a single circular or an elliptical arc, while
@var{draw-arcs} draws multiple circular or elliptical
arcs. @var{draw-arc} and @var{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.

@defun draw-arc drawable gcontext x y width height angle1 angle2 &optional fill-p

@table @var
@item drawable
The destination @var{drawable}.

@item gcontext
The graphics context for drawing the arc.

@item x
@itemx y
The x and y coordinates of the arc rectangle relative to the origin of the @emph{drawable}.
Type is @var{int16}.

@item width
@itemx height
Specifies the width and height of the rectangle. These are the major and
minor axes of the arc. Type is @var{card16}.

@item angle1
Specifies the start of the arc in radians. Type is @var{angle}.

@item angle2
Specifies the direction and end point of the arc. Type is @var{angle}.

@item fill-p
Specifies whether the arc is filled or not. Type @var{boolean}.
@end table

Draws either a circular or an elliptical arc. Also, outlined or filled
arcs can be drawn.  Each arc is specified by a rectangle (@emph{x},
@emph{y}, @emph{width}, and @emph{height}) and two angles
(@emph{angle1} and @emph{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
@emph{angle1}, and the path and extent of the arc is specified by
@emph{angle2} relative to the start of the arc. If the magnitude of
@emph{angle2} is greater than 360 degrees, it is truncated to 360
degrees. The @emph{x} and @emph{y} coordinates of the rectangle are
relative to the @emph{drawable}'s origin.

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

@display
[@emph{x}+(@emph{width}/2),@emph{y}+(@emph{height}/2)]
@end display

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

@display
[@emph{x},@emph{y}+(@emph{height}/2)] and [@emph{x}+@emph{width},@emph{y}+(@emph{height}/2)]
@end display

The intersection of the vertical axis is at:

@display
[@emph{x}+(@emph{width}/2),@emph{y}] and [@emph{x}+(@emph{width}/2),@emph{y}+@emph{height}]
@end display

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 @emph{fill-p} is @var{nil}, then only the outline of the arc is
drawn. Otherwise, if @emph{fill-p} is true, @var{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 @var{:chord}, the
filled area is bounded by the arc outline and the line segment joining
the arc end points. If the arc-mode is @var{: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.



@end defun


@defun draw-arcs drawable gcontext arcs &optional fill-p

@table @var
@item drawable
Specifies the @var{drawable} where you want the arcs drawn.
@item gcontext
Specifies the graphics context for drawing the arc.
@item arcs
A sequence containing the width, height, angle1, and angle2 arguments defining
the arcs. See @var{draw-arc} for more detail. Type is @var{arc-seq}.
@item fill-p
Specifies whether the arcs are filled or not. Type is @var{boolean}.
@end table

Draws circular or elliptical, outlined or filled arcs. Each arc is
specified by a rectangle and two angles. For a more detailed
description, see @var{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.


@end defun


@node Drawing Text,  , Drawing Arcs, Graphic Operations
@section 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. @xref{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 @var{:translate}
argument to a text function is a function which performs this
conversion. The default @var{:translate} function handles all
characters that satisfy @var{graphic-char-p} by converting each
character into its ASCII code. Note that the assumption made by the
default @var{:translate} function--that is, that an X font indexes
bitmaps by ASCII codes--is often valid, but other encodings are
possible. In general, a @var{: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 @var{:translate}
function is given below by describing a prototypical
@var{translate-function}.

CLX offers two different ways to draw text--filled text and block
text. The @var{draw-glyph} and @var{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 @var{draw-image-glyph} and @var{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.


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

@table @var
@item drawable
The destination @var{drawable}.

@item gcontext
The graphics context for drawing text.

@item x
@itemx y
The left baseline position for the character drawn.

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

@item :translate
A function to translate text to font indexes. Default is @var{#'translate-default}.

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

@item :size
Specifies the element size of the destination buffer given to @var{:translate} (8, 16, or
@var{:default}).
@end table

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

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

The @var{:size} specifies the element size of the destination buffer
given to @var{:translate} (either 8, 16, or @var{:default}). If
@var{:default} is specified, the size is based on the current font,
if known; otherwise, 16 is used.

@table @var
@item output-p
Type @var{boolean}.
@item width
Type @var{int32} or @var{null}.
@end table

@end defun

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

@table @var
@item drawable
The destination @var{drawable}.
@item gcontext
The graphics context for drawing text.
@item x
@itemx y
The left baseline position for the character drawn.
@item sequence
A sequence of characters or other objects to be translated into font indexes.
@item :start
@itemx :end
Start and end indexes defining the elements to draw.
@item :translate
A function to translate text to font indexes. Default is
@var{#'translate-default}.
@item :width
The total total pixel width of the character actually drawn, if known.
@item :size
The element size of the destination buffer given to @var{:translate} (8, 16, or
@var{:default}).
@end table


Draws the filled text characters represented by the given
sequence. @var{:start} and @var{:end} define the elements of the
sequence which are drawn. The given @emph{x} and @emph{y} specify the
left baseline position for the first character. The first return value
is @var{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 @var{:width} is a hint to improve performance. The
@var{:width} is assumed to be the total pixel width of the character
sequence actually drawn. Specifying @var{:width} permits appending
the output of subsequent calls to the same protocol request, provided
@emph{gcontext} has not been modified in the interim. If @var{:width}
is not specified, appending of subsequent output might not occur
(unless @var{:translate} returns the character width).

The @var{:size} specifies the element size of the destination buffer
given to@var{ :translate} (either 8, 16, or @var{:default}). If
@var{:default} is specified, the size is based on the current font,
if known; otherwise, 16 is used.
@table @var
@item new-start
Type @var{array-index} or @var{null}.
@item width
Type @var{int32} or @var{null}.
@end table

@end defun


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

@table @var
@item drawable
The destination @var{drawable}.
@item gcontext
The graphics context for drawing text.
@item x
@itemx y
The left baseline position for the character drawn.
@item element
A character or other object to be translated into a font index.
@item :translate
A function to translate text to font indexes. Default is
@var{#'translate-default}.
@item :width
The total pixel width of the character actually drawn, if known.
@item :size
Specifies the element size of the destination buffer given to @var{:translate} (8, 16, or
@var{:default}).
@end table


Draws a single character of block text represented by the given
@emph{element}. The given @emph{x} and @emph{y} specify the left
baseline position for the character. The first return value is true if
the character is successfully translated and drawn, or @var{nil} if
the @var{:translate} function did not translate it. The
@var{: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 @var{:translate} function may not return a horizontal position
change, since @var{draw-image-glyph} does not generate complex output
requests.

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

The @var{:size} specifies the element size of the destination buffer
given to @var{:translate} (either 8, 16, or @var{:default}). If
@var{:default} is specified, the size is based on the current font,
if known; otherwise, 16 is used.
@table @var
@item output-p
Type @var{boolean}.
@item width
Type @var{int32} or @var{null}.
@end table

@end defun



@defun draw-image-glyphs drawable gcontext x y sequence &key (:start 0) :end :translate :width (:size :default)
@anchor{draw-image-glyphs}

@table @var
@item drawable
The destination @var{drawable}.
@item x
@itemx y
The left baseline position for the character drawn.
@item gcontext
The graphics context for drawing text.
@item sequence
A sequence of characters or other objects to be translated into font indexes.
@item :start
@itemx :end
Start and end indexes defining the elements to draw.
@item :translate
A function to translate text to font indexes. Default is
@var{#'translate-default}.
@item :width
The total total pixel width of the character actually drawn, if known.
@item :size
The element size of the destination buffer given to @var{:translate} (8, 16, or
@var{:default}).
@end table


Draws the block text characters represented by the given
@var{sequence}. @var{:start} and @var{:end} define the elements of
the @emph{sequence} which are drawn. The given @emph{x} and @emph{y}
specify the left baseline position for the first character. The first
return value is @var{nil} if all characters are successfully
translated and drawn; otherwise, the index of the first untranslated
sequence element is returned. The @var{: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 @var{:translate} function may not return a horizontal position
change, since @var{draw-image-glyphs} does not generate complex
output requests.

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

The @var{:size} specifies the element size of the destination buffer
given to @var{:translate} (either 8, 16, or @var{:default}). If
@var{:default} is specified, the size will be based on the current
font, if known; otherwise, 16 is used.

@table @var
@item new-start
Type @var{array-index} or @var{null}.
@item width
Type @var{int32} or @var{null}.
@end table

@end defun


@defun translate-function source source-start source-end font destination destination-start

@table @var
@item source
A sequence of characters or other objects to be translated.
@item source-start
An array-index specifying the first @emph{source} element to be translated.
@item source-end
An array-index specifying the end of the @emph{source} subsequence to be
translated.
@item font
The font indexed by translated @emph{source} elements.
@item destination
A vector where translated @emph{source} elements are stored.
@item destination-start
An array-index specifying the position to begin storing
translated @emph{source} elements.
@end table


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

The @emph{destination} vector is created automatically by
CLX. @emph{destination} is guaranteed to have room for (-
@emph{source-end source-star}t) integer elements, starting at
@emph{destination-start}. Elements of @emph{destination} can be
either @var{card8} or @var{card16} integers, depending on the
context. @emph{font} is the current font, if known, or @var{nil}
otherwise. Starting with the element at @emph{source-start},
@var{translate-function} should translate as many elements of
@emph{source} as possible (up to the @emph{source-end} element)
into indexes in the current @emph{font}, and store them into
@emph{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 @emph{source} elements. If no further elements need to
be translated, the second return value should be @var{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.
@table @var
@item first-not-done
Type @var{array-index}.
@item to-continue
Type @var{int16}, @var{font}, or @var{null}.
@item current-width
Type @var{int32} or @var{null}.
@end table

@end defun



@node Images, Font and Characters, Graphic Operations, Top
@chapter Images

The X protocol provides for the transfer of images (two-dimensional
arrays of pixel data) between a client program and a
@var{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 @var{image} data
type. Additional @var{image} subtypes -- @var{image-xy} and
@var{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 @var{image} objects; for transferring image data between
@var{image} objects, @var{drawables}, and files; and also for direct
transfer of raw image data.

@menu
* Image Types::
* Image Functions::
* Image Files::
* Direct Image Transfer::
@end menu

@node Image Types, Image Functions, Images, Images
@section Image Types


The @var{image} data type is the base type for all @var{image}
objects. @var{image-xy} and @var{image-z} are subtypes of the
@var{image} type which furnish accessors specialized for different
image representations.

@menu
* Basic Images::
* XY-Format Images::
* Z-Format Images::
@end menu

@node Basic Images, XY-Format Images, Image Types, Image Types
@subsection Basic Images

The following paragraphs describe the CLX functions that can be used to
access all types of @var{image} objects.

@defun image-blue-mask image

@table @var
@item image
An @var{image} object.
@end table


Returns (and with @code{setf}) changes the @emph{mask} that
selects the pixel subfield for blue intensity values. The
@emph{mask} is non-@var{nil} only for images for
@var{:direct-color} or @var{:true-color} visual types.

@table @var
@item mask
Type @var{pixel} or @var{null}.
@end table

@end defun


@defun image-depth image

@table @var
@item image
An @var{image} object.
@end table

Returns the @emph{depth} (that is, the number of bits per pixel)
for the @emph{image}.
@table @var
@item depth
Type @var{card8}.
@end table

@end defun


@defun image-green-mask image

@table @var
@item image
An @var{image} object.
@end table

Returns (and with @code{setf}) changes the mask that selects the
pixel subfield for green intensity values. The mask is
non-@var{nil} only for images for @var{:direct-color} or
@var{:true-color} visual types.
@table @var
@item mask
Type @var{pixel} or @var{null}.
@end table

@end defun


@defun image-height image

@table @var
@item image
An @var{image} object.
@end table

Returns the @emph{height} of the @emph{image} in pixels.
@table @var
@item height
Type @var{card16}.
@end table

@end defun

@defun image-name image

@table @var
@item image
An @var{image} object.
@end table

Returns and (with @code{setf}) changes the @emph{name} string
optionally associated with the @emph{image}.
@table @var
@item name
Type @var{stringable} or @var{null}.
@end table

@end defun


@defun image-plist image

@table @var
@item image
An @var{image} object.
@end table


Returns and (with @code{setf}) changes the @emph{image} property
list. The property list is a hook for added application
extensions.
@table @var
@item plist
Type @var{list}.
@end table

@end defun


@defun image-red-mask image

@table @var
@item image
An @var{image} object.
@end table


Returns (and with @code{setf}) changes the @emph{mask} which
selects the pixel subfield for red intensity values. The
@emph{mask} is non-@var{nil} only for images for
@var{:direct-color} or @var{:true-color} visual types.
@table @var
@item mask
Type @var{pixel} or @var{null}.
@end table

@end defun


@defun image-width image

@table @var
@item image
An @var{image} object.
@end table


Returns the @emph{width} of the @emph{image} in pixels.
@table @var
@item width
Type @var{card16}.
@end table

@end defun


@defun image-x-hot image

@table @var
@item image
An @var{image} object.
@end table


Returns and (with @code{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 @emph{image}.
@table @var
@item x-position
Type @var{card16} or @var{null}.
@end table

@end defun


@defun image-y-hot image

@table @var
@item image
An @var{image} object.
@end table


Returns and (with @code{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 @emph{image}.
@table @var
@item y-position
Type @var{card16} or @var{null}.
@end table

@end defun


@node XY-Format Images, Z-Format Images, Basic Images, Image Types
@subsection XY-Format Images


The @var{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 @var{image-xy}
objects.

@defun image-xy-bitmap-list image

@table @var
@item image
An @var{image-xy} object.
@end table


Returns and (with @code{setf}) changes the list of bitmap planes
for the @emph{image}.
@table @var
@item bitmaps
Type @var{list} of @var{bitmap}.
@end table

@end defun


@node Z-Format Images,  , XY-Format Images, Image Types
@subsection Z-Format Images


The @var{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 @var{image-z}
objects.

@defun image-z-bits-per-pixel image

@table @var
@item image
An @var{image-z} object.
@end table


Returns and (with @code{setf}) changes the number of bits per data
unit used to contain a pixel value for the @emph{image}. Depending
on the storage format for image data, this value can be larger
than the actual @emph{image} depth.
@table @var
@item pixel-data-size
One of 1, 4, 8, 16, 24, or 32.
@end table

@end defun


@defun image-z-pixarray image

@table @var
@item image
An @var{image-z} object.
@end table

Returns and (with @code{setf}) changes the two-dimensional array
of pixel data for the @emph{image}.
@table @var
@item pixarray
Type @var{pixarray}.
@end table

@end defun



@node Image Functions, Image Files, Image Types, Images
@section Image Functions

The following paragraphs describe the CLX functions used to:

@itemize @bullet
@item  Create an @var{image} object.

@item  Copy an image or a subimage.

@item  Read an image from a @var{drawable}.

@item  Display an image to a @var{drawable}.
@end itemize


@defun 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

@table @var
@item :bit-lsb-first-p
For a returned image, true if the order of bits in each @var{:data}
byte is least-significant bit first.
@item :bits-per-pixel
One of 1, 4, 8, 16, 24, or 32.
@item :blue-mask
For @var{:true-color} or @var{:direct-color} images, a pixel mask.
@item :byte-lsb-first-p
For a returned @emph{image}, true if the @var{:data} byte order is
least-significant byte first.
@item :bytes-per-line
For a returned @emph{image}, the number of @var{:data} bytes per scanline.
@item :data
Either a @var{list} of @var{bitmaps}, a @var{pixarray}, or an array of @var{card8} bytes.
@item :depth
The number of bits per displayed pixel.
@item :format
One of @var{:bitmap}, @var{:xy-format}, or @var{:z-format}.
@item :green-mask
For @var{:true-color} or @var{:direct-color} images, a pixel mask.
@item :height
A @var{card16} for the image height in pixels.
@item :name
An optional @var{stringable} for the image name.
@item :plist
An optional image property list.
@item :red-mask
For @var{:true-color} or @var{:direct-color} images, a pixel mask.
@item :width
A @var{card16} for the image width in pixels.
@item :x-hot
For a @var{cursor} image, the x position of the hot spot.
@item :y-hot
For a cursor image, the y position of the hot spot.
@end table

Creates an @var{image} object from the given @var{:data} and
returns either an @var{image}, @var{image-xy}, or an
@var{image-z}, depending on the type of image @var{:data}. If the
@var{:data} is a list, it is assumed to be a @var{list} of
@var{bitmaps} and an @var{image-xy} is created. If the
@var{:data} is a @var{pixarray}, an @var{image-z} is
created. Otherwise, the @var{:data} must be an array of bytes
(@var{card8}), in which case a basic @var{image} object is
created.

If the @var{:data} is a list, each element must be a bitmap of
equal size. @var{:width} and @var{:height} default to the bitmap
width -- (@var{array-dimension bitmap} 1) -- and the bitmap height
-- (@var{array-dimension bitmap} 0) -- respectively. @var{:depth}
defaults to the number of bitmaps.

If the @var{:data} is a @var{pixarray}, @var{:width} and
@var{:height} default to the @var{pixarray} width --
(@var{array-dimension pixarray} 1), and the pixarray height --
(@var{array-dimension pixarray} 0), respectively. @var{:depth}
defaults to (@var{pixarray-depth} @var{:data}). The
@var{:bits-per-pixel} is rounded to a valid size, if necessary. By
default, the @var{:bits-per-pixel} is equal to the @var{:depth}.

If the @var{:data} is an array of @var{card8}, the @var{:width}
and @var{:height} are required to interpret the image data
correctly. The @var{:bits-per-pixel} defaults to the @var{:depth},
and the @var{:depth} defaults to 1. @var{:bytes-per-line} defaults
to:

@lisp
(@var{floor} (@var{length :data}) (* @var{:bits-per-pixel :height}))
@end lisp

The @var{:format} defines the storage format of image data bytes
and can be one of the following values:

@table @var
@item :xy-pixmap
The @var{:data} is organized as a set of bitmaps representing image
bit planes, appearing in most-significant to least-significant bit
order.

@item :z-pixmap
The @var{:data} is organized as a set of pixel values in scanline
order.

@item :bitmap
Similar to @var{:xy-pixmap}, except that the @var{:depth} must be 1,
and 1 and 0 bits represent the foreground and background pixels,
respectively.
@end table

By default, the @var{:format} is @var{:bitmap} if @var{:depth} is
1; otherwise, @var{:z-pixmap}.

@table @var
Type @var{image}.
@end table

@end defun


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

@table @var
@item image
An @var{image} object.
@item :x
@itemx :y
@var{card16} values defining the position of the upper-left corner of the subimage
copied.
@item :width
@itemx :height
@var{card16} values defining the size of subimage copied.
@item :result-type
One of @var{'image-x}, @var{'image-xy}, or @var{'image-z}.
@end table


Returns a new image, of the given @var{:result-type}, containing a
copy of the portion of the @emph{image} defined by @var{:x},
@var{:y}, @var{:width}, and @var{:height}. By default,
@var{:width} is:

@lisp
(- (@var{image-width} @emph{image}) @var{:x})
@end lisp

and @var{:height} is:

@lisp
(- (@var{image-height} @emph{image}) @var{:y})
@end lisp

If necessary, the new image is converted to the @var{:result-type},
that can be one of the following values:

@table @code
@item 'image-x
A basic @var{image} object is returned.
@item 'image-xy
An @var{image-xy} is returned.
@item 'image-z
An @var{image-z} is returned.
@end table

@table @var
@item new-image
Type @var{image}.
@end table

@end defun


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

@table @var
@item drawable
A @var{drawable}.
@item :x
@itemx :y
@var{card16} values defining the upper-left @var{drawable} pixel returned. These
arguments are required.
@item :width
@itemx :height
@var{card16} values defining the size of the @emph{image} returned. These
arguments are required.
@item :plane-mask
A pixel mask.
@item :format
Either @var{:xy-pixmap} or @var{:z-pixmap}.
@item :result-type
One of @var{'image-x}, @var{'image-xy}, or @var{'image-z}.
@end table


Returns an @emph{image} containing pixel values from the region of
the @emph{drawable} given by @var{:x}, @var{:y}, @var{:width},
and @var{:height}. The bits for all planes selected by 1 bits in
the @var{:plane-mask} are returned as zero; the default
@var{:plane-mask} is all 1 bits. The @var{:format} of the returned
pixel values may be either @var{:xy-format} or @var{:z-format}.

The @var{:result-type} defines the type of image object returned:

@table @code
@item 'image-x
A basic @var{image} object is returned.
@item 'image-xy
An @var{image-xy} is returned.
@item 'image-z
An @var{image-z} is returned.
@end table


By default, @var{:result-type} is @var{'image-z} if @var{:format}
is @var{:z-format} and @var{'image-xy} if @var{:format} is
@var{:xy-format}.
@table @var
Type @var{image}.
@end table

@end defun

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

@table @var
@item drawable
The destination @var{drawable}.
@item gcontext
The graphics context used to display the @emph{image}.
@item image
An @var{image} object.
@item :src-x
@itemx :src-y
@var{card16} values defining the upper-left position of the @emph{image} region to
display.
@item :x
@itemx :y
The position in the @emph{drawable} where the @emph{image} region is displayed. These
arguments are required.
@item :width :height
@var{card16} values defining the size of the @emph{image} region displayed.
@item :bitmap-p
If @emph{image} is depth 1, then if true, foreground and background pixels are
used to display 1 and 0 bits of the @emph{image}.
@end table

Displays a region of the @emph{image} defined by @var{:src-x},
@var{:src-y}, @var{:width}, and @var{:height} on the destination
d@emph{rawable}, with the upper-left pixel of the @emph{image}
region displayed at the @emph{drawable} position given by @var{:x}
and @var{:y}. By default, @var{:width} is:

@lisp
(- (@var{image-width} @emph{image}) @var{:src-x})
@end lisp

and @var{:height} is:

@lisp
(- (@var{image-height} @emph{image}) @var{:src-y})
@end lisp

The following attributes of the @emph{gcontext} are used to display
the @var{image}: clip-mask, clip-x, clip-y, function, plane-mask,
and subwindow-mode.

The @var{:bitmap-p} argument applies only to images of depth 1. In
this case, if @var{:bitmap-p} is true or if the @emph{image} is a
basic @var{image} object created with @var{:format :bitmap}, the
@emph{image} is combined with the foreground and background pixels
of the @var{gcontext}. 1 bits of the @emph{image} are displayed in
the foreground pixel and 0 bits are displayed in the background
pixel.


@end defun


@node Image Files, Direct Image Transfer, Image Functions, Images
@section 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:

@itemize @bullet
@item  Read an image from a file.

@item  Write an image to a file.
@end itemize


@defun read-bitmap-file pathname

@table @var
@item pathname
An image file pathname.
@end table


Reads an image file in standard X format and returns an
@var{image} object. The returned @emph{image} can have
depth greater than one.
@table @var
@item image
Type @var{image}.
@end table

@end defun


@defun write-bitmap-file pathname image &optional name

@table @var
@item pathname
An image file pathname.
@item image
An @var{image} object.
@item name
A @var{stringable} image name.
@end table

Writes the @emph{image} to an image file in standard X
format. The @emph{image} can have depth greater than
one. The @emph{name} is an image identifier written to the
file; the default @emph{name} is (@var{or}
(@var{image-name} @emph{image}) @var{'image}).


@end defun


@node Direct Image Transfer,  , Image Files, Images
@section Direct Image Transfer


For cases where the @var{image} representation is not needed,
CLX provides functions to read and display image data
directly.
@defun get-raw-image drawable &key :data (:start 0) :x :y :width :height :plane-mask (:format :z-format) (:result-type '(vector card8))

@table @var
@item drawable
A @var{drawable}.
@item :data
An optional @var{sequence} of @var{card8}.
@item :start
The index of the first @var{:data} element modified.
@item :x
@itemx :y
@var{card16} values defining the size of the @var{image} returned. These arguments are
required.
@item :width
@itemx :height
@var{card16} values defining the size of the image returned.These
arguments are required.
@item :plane-mask
A pixel mask.
@item :format
Either @var{:xy-pixmap} or @var{:z-pixmap}. This argument is required.
@item :result-type
The type of image data sequence to return.
@end table


Returns a sequence of image data from the region of the
@emph{drawable} given by @var{:x}, @var{:y},
@var{:width}, and @var{:height}. If @var{:data} is
given, it is modified beginning with the element at the
@var{:start} index and returned. The @emph{depth} and
@emph{visua}l type ID of the @emph{drawable} are also
returned.

The bits for all planes selected by 1 bits in the
@var{:plane-mask} are returned as zero; the default
@var{:plane-mask} is all 1 bits. The @var{:format} of
the returned pixel values may be either
@var{:xy-format} or @var{:z-format}. The
@var{: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
@emph{drawable}'s display (see @var{display-byte-order}
and @var{display-image-lsb-first-p}).
@table @var
@item data
Type @var{sequence} or @var{card8}.
@item depth
Type @var{card8}.
@item visual
Type @var{card29}.
@end table

@end defun


@defun put-raw-image drawable gcontext data &key (:start 0) :depth :x :y :width :height (:left-pad 0) :format

@table @var
@item drawable
The destination @var{drawable}.
@item gcontext
The graphics context used to display the image.
@item data
A sequence of integers.
@item :start
The index of the first element of @emph{data} displayed.
@item :depth
The number of bits per pixel displayed. This argument is required.
@item :x
@itemx :y
The position in the @emph{drawable} where the image region is displayed. These
arguments are required.
@item :width
@itemx :height
@var{card16} values defining the size of the image region displayed. These
arguments are required.
@item :left-pad
A @var{card8} specifying the number of leading bits to discard for each image
scanline.
@item :format
One of @var{:bitmap}, @var{:xy-pixmap}, or @var{:z-pixmap}.
@end table

Displays a region of the image data defined by @var{:start},
@var{:left-pad}, @var{:width}, and @var{:height} on the
destination @emph{drawable}, with the upper-left pixel of the image
region displayed at the @emph{drawable} position given by @var{:x}
and @var{:y}.

The @var{:format} can be either @var{:xy-pixmap},
@var{:z-pixmap}, or @var{:bitmap}. If @var{:xy-pixmap} or
@var{:z-pixmap} formats are used, @var{:depth} must match the
depth of the destination @emph{drawable}. For @var{:xy-pixmap}, the
data must be in XY format. For @var{:z-pixmap}, the data must be in
Z format for the given @var{:depth}.

If the @var{:format} is @var{:bitmap}, the @var{:depth} must be
1. In this case, the image is combined with the foreground and
background pixels of the @emph{gcontext}. 1 bits of the image are
displayed in the foreground pixel and 0 bits are displayed in the
background pixel.

The @var{:left-pad} must be zero for @var{:z-pixmap} format. For
@var{:bitmap} and @var{:xy-pixmap} formats, the @var{:left-pad}
must be less than the bitmap-scanline-pad for the @emph{drawable}'s
display (@pxref{display-bitmap-format}). The first
@var{: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 @emph{gcontext} are used to display
the @var{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 @emph{drawable}'s display
(see @var{display-byte-order} and
@var{display-image-lsb-first-p}).


@end defun


@node Font and Characters, Colors, Images, Top
@chapter 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 @emph{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 @var{open-font} function, sending a font name string as an
identifier. @var{open-font} creates a CLX @var{font} object used to
refer to the font in subsequent functions. Afterward, calling
@var{open-font} with the same font name returns the same @var{font}
object. When a font is no longer in use, a client program can call
@var{close-font} to destroy the @var{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 @emph{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
@emph{pseudo-font} object solely for the purpose of accessing font
attributes. A pseudo-font is represented by a special type of
@var{font} object that cannot be used in a @var{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:

@itemize @bullet
@item  Open and close fonts.
@item  List available fonts.
@item  Access font attributes.
@item  Access character attributes.
@item  Return the size of a text string.
@end itemize

@menu
* Opening Fonts::
* Listing Fonts::
* Font Attributes::
* Chracter Attributes::
* Querying Text Size::
@end menu

@node Opening Fonts, Listing Fonts, Font and Characters, Font and Characters
@section Opening Fonts


The following paragraphs discuss the CLX functions for opening and
closing fonts.

@defun open-font display name

@table @var
@item display
A @var{display} object.
@item name
A font name string.
@end table

Opens the font with the given @emph{name} and returns a
@var{font} object. The name string should contain only ISO
Latin-1 characters; case is not significant.

@table @var
@item font
Type @var{font}.
@end table

@end defun


@defun close-font font

@table @var
@item font
A @var{font} object.
@end table

Deletes the association between the resource ID and the
@emph{font}. The @emph{font} is freed when no other server
resource references it. The @emph{font} can be unloaded by the X
server if this is the last reference to the @emph{font} by any
client. In any case, the @emph{font} should never again be
referenced because its resource ID is destroyed. This might not
generate a protocol request if the @emph{font} is
reference-counted locally or if it is a pseudo-font.

@end defun


@defun discard-font-info fonts

@table @var
@item font
A @var{font} object.
@end table

Discards any state that can be re-obtained with
@var{open-font}. This is simply a performance hint for
memory-limited systems.

@end defun

@node Listing Fonts, Font Attributes, Opening Fonts, Font and Characters
@section 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 @emph{wildcard} matching:

@table @code
@item #\*
Matches any sequence of zero or more characters.
@item #\?
Matches any single character.
@end table

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.

@defun font-path display &key (:result-type 'list)

@table @var
@item display
A @var{display} object.
@item :result-type
Specifies the type of resulting sequence.
@end table

Returns a @var{list} (by default) of names containing the current
search path for fonts. With @code{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.
@table @var
@item paths
Type @var{sequence} of either @var{string} or @var{pathname}.
@end table

@end defun


@defun list-font-names display pattern &key (:max-fonts 65535) (:result-type 'list)

@table @var
@item display
A @var{display} object.
@item pattern
A string used to match font names. Only font names that match the pattern are
returned.
@item :max-fonts
The maximum number of font names returned. Default is 65535.
@item :result-type
The type of sequence to return. Default is '@var{list}.
@end table

Returns a sequence of strings containing the font names that match
the @emph{pattern}. The fonts available are determined by the font
search path; see @var{font-path}). The maximum number of font names
returned is determined by @var{:max-fonts}.

@table @var
@item font-name
Type @var{sequence} of @var{string}.
@end table

@end defun


@defun list-fonts display pattern &key (:max-fonts 65535) (:result-type 'list)

@table @var
@item display
A @var{display} object.
@item pattern
A string used to match font names. Only fonts whose name matches the
pattern are returned.
@item :max-fonts
The maximum number of fonts returned. Default is 65535.
@item :result-type
The type of sequence to return. Default is @var{'list}.
@end table

Returns a sequence of pseudo-fonts corresponding to the available
fonts whose names match the @emph{pattern}. The fonts available are
determined by the font search path; see @var{font-path}). The
maximum number of @var{font} objects returned is determined by
@var{:max-fonts}.

@table @var
@item font
Type @var{sequence} of @var{font}.
@end table

@end defun


@node Font Attributes, Chracter Attributes, Listing Fonts, Font and Characters
@section Font Attributes


The following paragraphs describe the CLX functions used to access font
attributes.

@defun font-all-chars-exist-p font

@table @var
@item exists-p
Type @var{boolean}.
@end table


Returns true if glyphs exist for all indexes in the range returned
by @var{font-min-char} and @var{font-max-char}. Returns
@var{nil} if an index in the range corresponds to empty glyph.

@table @var
@item font
A @var{font} object.
@end table

@end defun


@defun font-ascent font

@table @var
@item ascent
Type @var{int16}.
@end table


Returns the vertical @emph{ascent} of the @emph{font} used for
interline spacing. The @emph{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
@emph{ascent}.
@table @var
@item font
A @var{font} object.
@end table

@end defun


@defun font-default-char font

@table @var
@item index
Type @var{card16}.
@end table


Returns the @emph{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.
@table @var
@item font
A @var{font} object.
@end table

@end defun


@defun font-descent font

@table @var
@item descent
Type @var{int16}.
@end table


Returns the vertical @emph{descent} of the @emph{font} used for
interline spacing. The @emph{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
@emph{descent}.
@table @var
@item font
A @var{font} object.
@end table

@end defun


@defun font-direction font

@table @var
@item direction
Type @var{draw-direction}.
@end table


Returns the nominal drawing @emph{direction} for the
@emph{font}. The font drawing direction is only a hint that
indicates whether the @emph{char-width} of most font glyphs is
positive (@var{:left-to-right} direction) or negative
(@var{:right-to-left} direction). Note that X does not provide
any direct support for vertical text.
@table @var
@item font
A @var{font} object.
@end table

@end defun


@defun font-display font

@table @var
@item font
A @var{font} object.
@end table

Returns the @var{display} object associated with the specified
@emph{font}.

@table @var
@item display
Type @var{display}.
@end table

@end defun


@defun font-equal font-1 font-2

@table @var
@item font-1
@itemx font-2
The @var{font} objects.
@end table

Returns true if the two arguments refer to the same server
resource and @var{nil} if they do not.


@end defun


@defun font-id font

@table @var
@item font
A @var{font} object.
@end table

Returns the unique resource ID assigned to the specified @emph{font}.

@table @var
@item id
Type @var{resource-id}.
@end table

@end defun


@defun font-max-byte1 font

@table @var
@item font
A @var{font} object.
@end table


Returns zero if the @emph{font} uses linear index
encoding. Otherwise, if the @emph{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.
@table @var
@item max-byte1
Type @var{card8}@emph{.}
@end table

@end defun


@defun font-max-byte2 font

@table @var
@item font
A @var{font} object.
@end table


Returns zero if the @emph{font} uses linear index
encoding. Otherwise, if the @emph{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.
@table @var
@item max-byte2
Type @var{card8}@emph{.}
@end table

@end defun


@defun font-max-char font

@table @var
@item font
A @var{font} object.
@end table


Returns the maximum valid value used for linear encoded
indexes. This function is not meaningful for fonts that use matrix
index encoding.
@table @var
@item index
Type @var{card16}.
@end table

@end defun


@defun font-min-byte1 font

@table @var
@item font
A @var{font} object.
@end table


Returns zero if the @emph{font} uses linear index
encoding. Otherwise, if the @emph{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.
@table @var
@item min-byte1
Type @var{card8}.
@end table

@end defun


@defun font-min-byte2 font

@table @var
@item font
A @var{font} object.
@end table


Returns zero if the @emph{font} uses linear index
encoding. Otherwise, if the @emph{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.
@table @var
@item min-byte2
Type @var{card8}.
@end table

@end defun


@defun font-min-char font

@table @var
@item font
A @var{font} object.
@end table


Returns the minimum valid value used for linear encoded
indexes. This function is not meaningful for fonts that use matrix
index encoding.
@table @var
@item index
Type @var{card16}.
@end table

@end defun


@defun font-name font

@table @var
@item font
A @var{font} object.
@end table


Returns the name of the @emph{font}, or @var{nil} if @emph{font}
is a pseudo-font.
@table @var
@item name
Type @var{string} or @var{null}.
@end table

@end defun


@defun font-p font

Returns true if the argument is a @var{font} object and
@var{nil} otherwise.

@table @var
@item font-p
Type @var{boolean}.
@end table

@end defun


@defun font-plist font

@table @var
@item font
A @var{font} object.
@end table


Returns and (with @code{setf}) sets the property list for the
specified @emph{font}. This function provides a hook where
extensions can add data.
@table @var
@item plist
Type @var{list}.
@end table

@end defun


@defun font-properties font

@table @var
@item font
A @var{font} object.
@end table


Returns the list of font @emph{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.
@table @var
@item properties
Type @var{list}.
@end table

@end defun


@defun font-property font name

@table @var
@item font
A @var{font} object.
@item name
A font property keyword.
@end table


Returns the value of the font @emph{property} specified by the
@emph{name} keyword. The property value, if it exists, is returned
as an uninterpreted 32-bit integer.
@table @var
@item property
Type @var{int32} or @var{null}.
@end table

@end defun


@defun max-char-ascent font

@table @var
@item font
A @var{font} object.
@end table


Returns the maximum @var{char-ascent} value for all characters in
@emph{font}.
@table @var
@item ascent
Type @var{int16}.
@end table

@end defun


@defun max-char-attributes font

@table @var
@item font
A @var{font} object.
@end table


Returns the maximum @var{char-attributes} value for all
characters in @emph{font}.
@table @var
@item attributes
Type @var{int16}.
@end table

@end defun


@defun max-char-descent font

@table @var
@item font
A @var{font} object.
@end table


Returns the maximum @var{char-descent} value for all characters
in @emph{font}.
@table @var
@item descent
Type @var{int16}.
@end table

@end defun


@defun max-char-left-bearing font

@table @var
@item font
A @var{font} object.
@end table


Returns the maximum @var{char-left-bearing} value for all characters in @emph{font}.
@table @var
@item left-bearing
Type @var{int16}.
@end table

@end defun


@defun max-char-right-bearing font

@table @var
@item font
A @var{font} object.
@end table


Returns the maximum @var{char-right-bearing} value for all
characters in @emph{font}.
@table @var
@item right-bearing
Type @var{int16}.
@end table

@end defun


@defun max-char-width font

@table @var
@item font
A @var{font} object.
@end table


Returns the maximum @var{char-width} value for all characters in
@emph{font}.
@table @var
@item width
Type @var{int16}.
@end table

@end defun


@defun min-char-ascent font

@table @var
@item font
A @var{font} object.
@end table


Returns the minimum @var{char-ascent} for all characters in
@emph{font}.
@table @var
@item ascent
Type @var{int16}.
@end table

@end defun


@defun min-char-attributes font

@table @var
@item font
A @var{font} object.
@end table


Returns the minimum @var{char-attributes} for all characters in @emph{font}.
@table @var
@item attributes
Type @var{int16}.
@end table

@end defun


@defun min-char-descent font

@table @var
@item font
A @var{font} object.
@end table


Returns the minimum @var{char-descent} for all characters in @emph{font}.
@table @var
@item descent
Type @var{int16}.
@end table

@end defun


@defun min-char-left-bearing font

@table @var
@item font
A @var{font} object.
@end table


Returns the minimum @var{char-left-bearing} for all characters in
@emph{font}.
@table @var
@item left-bearing
Type @var{int16}.
@end table

@end defun


@defun min-char-right-bearing font

@table @var
@item font
A @var{font} object.
@end table


Returns the minimum @var{char-right-bearing} for all characters
in @emph{font}.
@table @var
@item right-bearing
Type @var{int16}.
@end table

@end defun


@defun min-char-width font

@table @var
@item font
A @var{font} object.
@end table


Returns the minimum @var{char-width} for all characters in
@emph{font}.
@table @var
@item width
Type @var{int16}.
@end table

@end defun


@node Chracter Attributes, Querying Text Size, Font Attributes, Font and Characters
@section Chracter Attributes


The following paragraphs describe the CLX functions used to access the
attributes of individual font glyphs.

@defun char-ascent font index

@table @var
@item font
A @var{font} object.
@item index
An @var{int16} font index.
@end table


Returns the vertical distance in pixels from the baseline to the top
of the given font glyph. Returns @var{nil} if the index is invalid
or specifies an empty glyph, or if the @emph{font} is a pseudo-font.
@table @var
@item ascent
Type @var{int16} or @var{null}.
@end table

@end defun


@defun char-attributes font index

@table @var
@item font
A @var{font} object.
@item index
An @var{int16} font index.
@end table


Returns font-specific @emph{attributes} of the given glyph. The
interpretation of such attributes is server-dependent. Returns
@var{nil} if the @emph{index} is invalid or specifies an empty
glyph, or if the @emph{font} is a pseudo-font.
@table @var
@item attributes
Type @var{int16} or @var{null}.
@end table

@end defun


@defun char-descent font index

@table @var
@item font
A @var{font} object.
@item index
An @var{int16} font index.
@end table


Returns the vertical distance in pixels from the baseline to the
bottom of the given font glyph. Returns @var{nil} if the
@emph{index} is invalid or specifies an empty glyph, or if the
@emph{font} is a pseudo-font.
@table @var
@item descent
Type @var{int16} or @var{null}.
@end table

@end defun


@defun char-left-bearing font index

@table @var
@item font
A @var{font} object.
@item index
An @var{int16} font index.
@end table


Returns the left side bearing of the given font glyph. If
@var{draw-glyph} is called with horizontal position @emph{x},
the leftmost pixel of the glyph is drawn at the position
(+ @emph{x left-bearing}). Returns @var{nil} if the
@emph{index} is invalid or specifies an empty glyph, or if the
@emph{font} is a pseudo-font.
@table @var
@item left-bearing
Type @var{int16} or @var{null}.
@end table

@end defun


@defun char-right-bearing font index

@table @var
@item font
A @emph{font} object.
@item index
An @var{int16} font index.
@end table


Returns the right side bearing of the given font glyph. If
n@var{draw-glyph} is called with horizontal position @emph{x},
the rightmost pixel of the glyph is drawn at the position (+
@emph{x rightbearing}). Returns @var{nil} if the
@emph{index} is invalid or specifies an empty glyph, or if the
@emph{font} is a pseudo-font.

@table @var
@item right-bearing
Type @var{int16} or @var{null}.
@end table

@end defun


@defun char-width font index

@table @var
@item font
A @var{font} object.
@item index
An @var{int16} font index.
@end table

Returns the @emph{width} of the given font glyph. The @emph{width}
is defined to be equal to (- @emph{rightbearing
left-bearing}). Returns @var{nil} if the @emph{index} is invalid
or specifies an empty glyph, or if the @emph{font} is a pseudo-font.

@table @var
@item width
Type @var{int16} or @var{null}.
@end table

@end defun


@node Querying Text Size,  , Chracter Attributes, Font and Characters
@section Querying Text Size


CLX defines functions to return the size of text drawn in a specified
font. @xref{Drawing Text}, for a description of the
@var{:translate} function used by the functions in the following
paragraphs.

@defun text-extents font sequence &key (:start 0) :end :translate
@anchor{text-extents}

@table @var
@item font
The font (or @var{gcontext}) used for measuring characters.
@item sequence
A sequence of characters or other objects to be translated into font indexes.
@item :start
@itemx :end
Start and end indexes defining the elements to draw.
@item :translate
A function to translate text to font indexes. Default is
@var{#'translate-default}.
@end table

Returns the complete geometry of the given @emph{sequence} when
drawn in the given @emph{fon}t. The @emph{font} can be a
@var{gcontext}, in which case the font attribute of the given
graphics context is used. @var{:start} and @var{:end} define the
elements of the @emph{sequence} which are used.

The returned @emph{width} is the total pixel width of the
translated character sequence. The returned @emph{ascent} and
@emph{descent} give the vertical ascent and descent for characters
in the translated @emph{sequence}. The returned @emph{left} gives
the left bearing of the leftmost character. The returned
@emph{right} gives the right bearing of the rightmost
character. The returned @emph{font-ascent} and @emph{font-descent}
give the maximum vertical ascent and descent for all characters in
the @emph{fon}t. If @var{:translate} causes font changes, then
@emph{font-ascent} and @emph{font-descent} will be the maximums
over all fonts used. The @emph{direction} returns the preferred
draw direction for the font. If @var{:translate} causes font
changes, then the @emph{direction} will be @var{nil}. The
@emph{first-not-done} value returned is @var{nil} if all elements
of the @emph{sequence} were successfully translated; otherwise the
index of the first untranslated element is returned.

@table @var
@item width
Type @var{int32}.
@item ascent
Type @var{int16}.
@item descent
Type @var{int16}.
@item left
Type @var{int32}.
@item right
Type @var{int32}.
@item font-ascent
Type @var{int16}.
@item direction
Type @var{draw-direction}.
@item first-not-done
Type @var{array-index} or @var{null}.
@end table

@end defun


@defun text-width font sequence &key (:start 0) :end :translate

@table @var
@item font
The font (or @var{gcontext}) used for measuring characters.
@item sequence
A sequence of characters or other objects to be translated into font indexes.
@item :start
@item :end
Start and end indexes defining the elements to draw.
@item :translate
A function to translate text to font indexes. Default is
@var{#'translate-default}.
@end table


Returns the total pixel width of the given @emph{sequence} when
drawn in the given @emph{font}. The @emph{font} can be a
@var{gcontext}, in which case the font attribute of the given
graphics context is used. @var{:start} and @var{:end} define the
elements of the @emph{sequence} which are used. The second value
returned is @var{nil} if all elements of the @emph{sequence} were
successfully translated; otherwise the index of the first
untranslated element is returned.
@table @var
@item width
Type @var{int32}.
@item first-not-done
Type @var{array-index} or @var{null}.
@end table

@end defun


@node Colors, Cursors, Font and Characters, Top
@chapter Colors

@menu
* Colormaps and Colors::
* Color Functions::
* Colormap Functions::
@end menu

@node Colormaps and Colors, Color Functions, Colors, Colors
@section Colormaps and Colors


In X, a @emph{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 @emph{primary} hues. A @emph{colormap} is a list
of colors, each indexed by an integer @emph{pixel} value. Each entry in
a colormap is called a color @emph{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, @var{:gray-scale} screens use colormaps in
which colors actually specify the monochrome intensity. A typical
black-and-white monochrome display has a @var{:static-gray} screen with
a two-cell colormap.

The following list describes how pixel values and colormaps are handled
for each visual class.

@table @var
@item :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.
@item :gray-scale
A pixel value indexes a single colormap that contains monochrome
intensities. Colormap entries can be changed.
@item :pseudo-color
A pixel value indexes a single colormap that contains color
intensities. Colormap entries can be changed.
@item :static-color
Same as @var{:pseudo-color}, except that the colormap entries are
predefined by the hardware and cannot be changed.
@item :static-gray
Same as @var{:gray-scale}, except that the colormap entries are
predefined by the hardware and cannot be changed.
@item :true-color
Same as @var{: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.
@end table

CLX provides functions to create colormaps, access and modify colors and
color cells, and install colormaps in screen hardware.

@node Color Functions, Colormap Functions, Colormaps and Colors, Colors
@section 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 @var{rgb-val} -- a floating
point number between 0.0 and 1.0.  (@pxref{Data Types}). The
value 0.0 represents the minimum intensity, while 1.0 represents the
maximum intensity. CLX automatically converts @var{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 @var{: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.

@defun make-color &key (:blue 1.0) (:green 1.0) (:red 1.0) &allow-other-keys

@table @var
@item :blue
@itemx :green
@itemx :red
@var{rgb-val} values that specify the saturation for each primary.
@end table


Creates, initializes, and returns a new @var{color} object with the
specified values for red, green, and blue.
@table @var
@item color
Type @var{color}.
@end table

@end defun


@defun color-blue color

@table @var
@item color
A @var{color} object.
@end table


Returns and (with @code{setf}) sets the value for blue in the
@emph{color}.
@table @var
@item blue-intensity
Type @var{rgb-val}.
@end table

@end defun


@defun color-green color

@table @var
@item color
A @var{color} object.
@end table


Returns and (with @code{setf}) sets the value for green in the
@emph{color}.
@table @var
@item green-intensity
Type @var{rgb-val}.
@end table

@end defun


@defun color-p color

Returns non-@var{nil} if the argument is a @var{color} object and
@var{nil} otherwise.

@table @var
@item color-p
Type @var{boolean}.
@end table

@end defun

@defun color-red color

@table @var
@item color
A @var{color} object.
@end table


Returns and (with @code{setf}) sets the value for red in the
@emph{color}.
@table @var
@item red-intensity
Type @var{rgb-val}.
@end table

@end defun


@defun color-rgb color

@table @var
@item color
A @var{color} object.
@end table


Returns the values for red, green, and blue in the @emph{color}.
@table @var
@item red
@itemx green
@itemx blue
Type @var{rgb-val}.
@end table

@end defun


@node Colormap Functions,  , Color Functions, Colors
@section Colormap Functions


A colormap is represented in CLX by a @var{colormap} object. A CLX
program can create and manipulate several @var{colormap}
objects. However, the colors contained in a @var{colormap} are made
visible only when the @var{colormap} is @emph{installed}. Each window
is associated with a @var{colormap} that is used to translate window
pixels into colors (see @var{window-colormap}). However, a window will
appear in its true colors only if its associated @var{colormap} is
installed.

The total number of colormaps that can be installed depends on the
screen hardware.  Most hardware devices allow exactly one
@var{colormap} to be installed at any time. That is,
@var{screen-min-installed-maps} and @var{screen-max-installed-maps}
are both equal to 1.  Installing a new @var{colormap} can cause a
previously installed @var{colormap} to be uninstalled. It is important
to remember that the set of installed @var{colormaps} is a hardware
resource shared cooperatively among all client programs connected to an
X server.

A CLX program can control the contents of @var{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 @var{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
@var{:static-gray}, @var{:static-color}, or @var{:true-color}
classes. For screens of these classes, @var{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
@var{screen-black-pixel} and @var{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
@emph{black} and @emph{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 @var{colormap}, which is initially
installed. By conventions, clients should allocate only read-only cells
from the default @var{colormap}.

@menu
* Creating Colormaps::
* Installing Colormaps::
* Allocating Colors::
* Finding Colors::
* Changing Colors::
* Colormap Attributes::
@end menu

@node Creating Colormaps, Installing Colormaps, Colormap Functions, Colormap Functions
@subsection Creating Colormaps


CLX provides functions for creating and freeing new @var{colormap}
objects.

@defun create-colormap visual window &optional alloc-p

@table @var
@item visual
A @var{visual} type ID.
@item window
A @var{window}.
@item alloc-p
Specifies whether @var{colormap} cells are permanently allocated read-write.
@end table


Creates and returns a @emph{colormap} of the specified
@emph{visual} type for the screen containing the
@emph{window}. The @emph{visual} type must be one of those
supported by the screen.

Initial color cell values are undefined for visual types belonging
to the @var{:gray-scale}, @var{:pseudo-color}, and
@var{:direct-color} classes. Color cell values for visual types
belonging to the @var{:static-gray}, @var{:static-color}, and
@var{: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 @emph{alloc-p} is true, all colormap cells are permanently
allocated read-write and cannot be freed by @var{free-colors}. It
is an error for @emph{alloc-p} to be true when the visual type
belongs to the @var{:static-gray}, @var{:static-color}, or
@var{:true-color} classes.

@table @var
@item colormap
Type @var{colormap}.
@end table

@end defun


@defun copy-colormap-and-free colormap

@table @var
@item colormap
A @var{colormap}.
@end table

Creates and returns a new @var{colormap} by copying, then
freeing, allocated cells from the specified @emph{colormap}.

All color cells allocated read-only or read-write in the original
@var{colormap} have the same color values and the same allocation
status in the @emph{new-colormap}. The values of unallocated color
cells in the @emph{new-colormap} are undefined. After copying, all
allocated color cells in the original @var{colormap} are freed,
as if @var{free-colors} was called. The unallocated cells of the
original @var{colormap} are not affected.

If @emph{alloc-p} was true when the original @var{colormap} was
created, then all color cells of the @emph{new-colormap} are
permanently allocated read-write, and all the color cells of the
original @var{colormap} are freed.

@table @var
@item new-colormap
Type @var{colormap}.
@end table

@end defun


@defun free-colormap colormap

@table @var
@item colormap
A @var{colormap}.
@end table

Destroys the @emph{colormap} and frees its server resource. If the
@emph{colormap} is installed, it is uninstalled. For any window
associated with the @emph{colormap}, the window is assigned a
@var{nil} @var{colormap}, and a @var{:colormap-notify} event is
generated. The colors displayed for a window with a @var{nil
colormap} are undefined.

However, this function has no effect if the @emph{colormap} is a
screen default @var{colormap}.

@end defun


@node Installing Colormaps, Allocating Colors, Creating Colormaps, Colormap Functions
@subsection 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 @var{colormap} for a screen is installed (but is
not in the required list).

@defun install-colormap colormap
@anchor{install-colormap}

@table @var
@item colormap
A @var{colormap}.
@end table

Installs the @emph{colormap.} All windows associated with this
@emph{colormap} immediately display with true colors. As a
side-effect, additional colormaps might be implicitly uninstalled by
the server.

If the specified @emph{colormap} is not already installed, a
@var{:colormap-notify} event is generated on every window
associated with this @emph{colormap}. In addition, for every other
colormap that is implicitly uninstalled, a @var{:colormap-notify}
event is generated on every associated window.


@end defun


@defun installed-colormaps window &key (:result-type 'list)

@table @var
@item window
A @var{window}.
@item :result-type
A sub-type of @var{sequence} that indicates the type of sequence to return.
@end table


Returns a sequence containing the installed @var{colormaps} for the
screen of the specified @emph{window}. The order of the colormaps is
not significant.
@table @var
@item colormap
Type @var{sequence} of @var{colormap}.
@end table

@end defun


@defun uninstall-colormap colormap

@table @var
@item colormap
A @var{colormap}.
@end table

Uninstalls the @emph{colormap}. However, the @emph{colormap} is not
actually uninstalled if this would reduce the set of installed
colormaps below the value of @var{screen-min-installed-maps}. If
the @emph{colormap} is actually uninstalled, a
@var{:colormap-notify} event is generated on every associated
window.


@end defun


@node Allocating Colors, Finding Colors, Installing Colormaps, Colormap Functions
@subsection Allocating Colors


The following paragraphs describe the functions for allocating read-only
and read-write color cells, allocating color planes, and freeing color
cells.

@defun alloc-color colormap color

@table @var
@item colormap
A @var{colormap}.
@item color
A @var{color} object or a @var{stringable} containing a color name.
@end table


Returns a @emph{pixel} for a read-only color cell in the
@emph{colormap}. The color in the allocated cell is the closest
approximation to the requested @emph{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 @emph{color} can be either a @var{color} object or a
@var{stringable} containing a color name.  If a color name is
given, a corresponding color value is looked up (see
@var{lookup-color}) and used. Color name strings must contain only
ISO Latin-1 characters; case is not significant.

@table @var
@item pixel
Type @var{pixel}.
@item screen-color
@itemx exact-color
Type @var{color}.
@end table

@end defun


@defun alloc-color-cells colormap colors &key (:planes 0) :contiguous-p (:result-type 'list)

@table @var
@item colormap
A @var{colormap}.
@item colors
A positive number defining the length of the pixels sequence returned.
@item :planes
A non-negative number defining the length of the masks sequence returned.
@item :contiguous-p
If true, the masks form contiguous sets of bits.
@item :result-type
A subtype of @var{sequence} that indicates the type of sequences returned.
@end table


Returns a @var{sequence} of @emph{pixels} for read-write color
cells in the @emph{colormap}. The allocated cells contain undefined
color values. The visual type class of the @var{colormap} must be
either @var{:gray-scale}, @var{:pseudo-color}, or
@var{:direct-color}.

The @emph{colors} argument and the @var{: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 (* @emph{colors}
(@var{expt} 2 @emph{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
@var{: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 @var{logior}, (@var{expt} 2
@emph{planes}) distinct combined plane masks can be computed.

The length of the returned @emph{pixels} sequence is equal to
@emph{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 @var{logior}, (* @emph{colors} (@var{expt} 2
@emph{planes})) distinct pixel values can be produced.

If the @emph{colormap} class is @var{:gray-scale} or
@var{:pseudo-color}, each @emph{mask} will have exactly one bit
set. If the @var{colormap} class is @var{:direct-color}, each
@emph{mask} will have exactly three bits set.  If
@var{:contiguous-p} is true, combining all masks with @var{logior}
produces a plane mask with either one set of contiguous bits (for
@var{:gray-scale} and @var{:pseudo-color}) or three sets of
contiguous bits (for @var{:direct-color}).

@table @var
@item pixels
@itemx mask
Type @var{sequence} of @var{pixels}.
@end table

@end defun


@defun alloc-color-planes colormap colors &key (:reds 0) (:greens 0) (:blues 0) :contiguous-p (:result-type 'list)

@table @var
@item colormap
A @var{colormap}.
@item colors
A positive number defining the length of the pixels sequence returned.
@item :planes
A non-negative number defining the length of the masks sequence returned.
@item :contiguous-p
If true, then the masks form contiguous sets of bits.
@item :result-type
A subtype of @var{sequence} that indicates the type of sequences returned.
@end table


Returns a @var{sequence} of @emph{pixels} for read-write color
cells in the @emph{colormap}. The allocated cells contain undefined
color values. The visual type class of the @emph{colormap} must be
either @var{:gray-scale}, @var{:pseudo-color}, or
@var{:direct-color}.

The @emph{colors} argument defines the number of pixels
returned. The @var{:reds}, @var{:greens}, and @var{: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 (* @emph{colors} (@var{expt} 2 (+ @emph{reds greens}
@emph{blues}))) color cells are allocated. The pixel values for the
allocated cells can be computed by combining the returned
@emph{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 @var{logior}, (@var{expt} 2 (+ @emph{reds greens
blues}) distinct combined plane masks can be computed.

The length of the returned @emph{pixels} @var{sequence} is equal to
@emph{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 @var{logior}, (* @emph{colors} (@var{expt} 2
(+ @emph{reds greens blues})) distinct pixel values can be produced.

If @var{:contiguous-p} is true, each of returned masks consists of
a set of contiguous bits. If the @var{colormap} class is
@var{:direct-color}, each returned mask lies within the pixel
subfield for its primary.

@table @var
@item pixels
Type @var{sequence} of @var{pixel}.
@item red-mask
@itemx green-mask
@itemx blue-mask
Type @var{pixel}.
@end table

@end defun


@defun free-colors colormap pixels &optional (plane-mask 0)

@table @var
@item colormap
A @var{colormap}.
@item pixels
A @var{sequence} of pixel values.
@item plane-mask
A pixel value with no bits in common with any of the @emph{pixels}.
@end table

Frees a set of allocated color cells from the @emph{colormap}. The
pixel values for the freed cells are computed by combining the given
@emph{pixels} sequence and @var{:plane-mask}. The total number of
cells freed is:

@lisp
(* (@var{length} @emph{pixels}) (@var{expt} 2 (@var{logcount} @emph{plane-mask})))
@end lisp

The @var{:plane-mask} must not have any bits in common with any of
the given @emph{pixels}. The pixel values for the freed cells are
produced by using @var{logior} to combine each of the given pixels
with all subsets of the @var{:plane-mask}.

Note that freeing an individual pixel allocated by
@var{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.


@end defun


@node Finding Colors, Changing Colors, Allocating Colors, Colormap Functions
@subsection 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.

@defun lookup-color colormap name

@table @var
@item colormap
A @var{colormap}.
@item name
A @var{stringable} color name.
@end table


Returns the color associated by the X server with the given color
@emph{name}. The @emph{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.

@table @var
@item screen-color
@itemx exact-color
Type @var{color}.
@end table

@end defun


@defun query-colors colormap pixels &key (:result-type 'list)

@table @var
@item colormap
A @var{colormap}.
@item pixels
A @var{sequence} of @var{pixel} values.
@item :result-type
A subtype of @var{sequence} that indicates the type of sequences returned.
@end table


Returns a @var{sequence} of the colors contained in the allocated
cells of the @emph{colormap} specified by the given
@emph{pixels}. The values returned for unallocated cells are
undefined.
@table @var
@item colors
Type @var{sequence} of @var{color}.
@end table

@end defun


@node Changing Colors, Colormap Attributes, Finding Colors, Colormap Functions
@subsection Changing Colors


The following paragraphs describe the CLX functions to change the colors
in colormap cells.

@defun store-color colormap pixel color &key (:red-p t) (:green-p t) (:blue-p t)

@table @var
@item colormap
A @var{colormap}.
@item pixel
A @var{pixel}.
@item color
A color @var{object} or a @var{stringable} containing a color name.
@item :red-p
@itemx :green-p
@itemx :blue-p
@var{boolean} values indicating which color components to
store.
@end table

Changes the contents of the @emph{colormap} cell indexed by the
@emph{pixel}. Components of the given @emph{color} are stored in the
cell. The @var{:red-p}, @var{:green-p}, and @var{:blue-p}
arguments indicate which components of the given @emph{color} are
stored.

The @emph{color} can be either a @var{color} object or a
@var{stringable} containing a color name. If a color name is given,
a corresponding color value is looked up (see @var{lookup-color})
and used.  Color name strings must contain only ISO Latin-1
characters; case is not significant.


@end defun


@defun store-colors colormap pixel-colors &key (:red-p t) (:green-p t) (:blue-p t)

@table @var
@item colormap
A @var{colormap}.
@item pixel-colors
A list of the form (@{@emph{pixel color}@}*).
@item :red-p
@itemx :green-p
@itemx :blue-p
@var{boolean} values indicating which color components to
store.
@end table

Changes the contents of multiple @emph{colormap}
cells. @emph{pixel-colors} is a list of the form (@{ @emph{pixel
color}@}*), indicating a set of pixel values and the colors to store
in the corresponding cells. The @var{:red-p}, @var{:green-p}, and
@var{:blue-p} arguments indicate which components of the given colors
are stored.

Each color can be either a @var{color} object or a
@var{stringable} containing a color name. If a color name is given,
a corresponding color value is looked up (see @var{lookup-color})
and used.  Color name strings must contain only ISO Latin-1
characters; case is not significant.


@end defun


@node Colormap Attributes,  , Changing Colors, Colormap Functions
@subsection Colormap Attributes


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

@defun colormap-display colormap

@table @var
@item colormap
A @var{colormap}.
@end table


Returns the @var{display} object associated with the specified
@emph{colormap}.
@table @var
@item display
Type @var{display}.
@end table

@end defun


@defun colormap-equal colormap-1 colormap-2

@table @var
@item colormap-1
@itemx colormap-2
A @var{colormap}.
@end table

Returns true if the two arguments refer to the same server resource
and @var{nil} if they do not.


@end defun


@defun colormap-id colormap

@table @var
@item colormap
A @var{colormap}.
@end table

Returns the unique ID assigned to the specified @emph{colormap}.

@table @var
@item id
Type @var{resource-id}.
@end table

@end defun


@defun colormap-p colormap

Returns non-@var{nil} if the argument is a @var{colormap} and
@var{nil} otherwise.

@table @var
@item map-p
Type @var{boolean}.
@end table

@end defun

@defun colormap-plist colormap

@table @var
@item colormap
A @var{colormap}.
@end table




Returns and (with @code{setf}) sets the property list for the
specified @emph{colormap}. This function provides a hook where
extensions can add data.

@table @var
@item colormap-p
Type @var{boolean}.
@end table

@end defun


@node Cursors, Atoms, Colors, Top
@chapter Cursors

A @emph{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 @var{window-cursor}.

A cursor image is composed of a source bitmap, a mask bitmap, a @emph{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 @var{cursor} object. This section
describes the CLX functions to:

@itemize @bullet
@item  Create and free cursor objects

@item  Change cursor colors

@item  Inquire the best cursor size

@item  Access cursor attributes
@end itemize

@menu
* Creating Cursors::
* Cursor Functions::
* Cursor Attributes::
@end menu

@node Creating Cursors, Cursor Functions, Cursors, Cursors
@section Creating Cursors


The following paragraphs describe the CLX functions used to create and
free @var{cursor} objects.

@defun create-cursor &key :source :mask :x :y :foreground :background

@table @var
@item :source
The source pixmap. This argument is required.
@item :mask
The mask pixmap.
@item :x
@itemx :y
The hot spot position in the @var{:source}. This argument is required.
@item :foreground
A @var{color} object specifying the foreground color. This argument is required.
@item :background
A @var{color} object specifying the background color. This argument is required.
@end table


Creates and returns a cursor. @var{:x} and @var{:y} define the
position of the hot spot relative to the origin of the
@var{:source. :foreground} and @var{:background} colors must be
specified, even if the server only has a @var{:static-gray} or
@var{:gray-scale} screen. The @var{:source}, @var{:x}, and
@var{:y} arguments must also be specified.

The cursor image is drawn by drawing a pixel from the @var{:source}
bitmap at every position where the corresponding bit in the
@var{:mask} bitmap is 1. If the corresponding @var{:source} bit is
1, a pixel is drawn in the @var{:foreground} color; otherwise, a
pixel is drawn in the @var{:back-ground} color. If the @var{:mask}
is omitted, all @var{:source} pixels are drawn. If given, the
@var{:mask} must be the same size as the @var{: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 @var{:source} and @var{:mask} can be freed immediately after
the cursor is created. Subsequent drawing in the @var{:source} or
@var{:mask} pixmap has an undefined effect on the cursor.

@table @var
@item cursor
Type @var{cursor}.
@end table

@end defun


@defun create-glyph-cursor &key :source-font :source-char :mask-font (:mask-char 0) :foreground :background

@table @var
@item :source-font
The source font. This is a required argument.
@item :source-char
An index specifying a glyph in the source font. This is a required argument.
@item :mask-font
The mask font.
@item :mask-char
An index specifying a glyph in the mask font.
@item :foreground
A @var{color} object specifying the foreground color. This is a required argument.
@item :background
A @var{color} object specifying the background color. This is a required argument.
@end table


Creates and returns a cursor defined by font glyphs. The source
bitmap is defined by the @var{:source-font} and
@var{:source-char}. The mask bitmap is defined by the
@var{:mask-font} and @var{:mask-char}. It is an error if the
@var{:source-char} and @var{:mask-char} are not valid indexes for
the @var{:source-font} and @var{:mask-font}, respectively. The hot
spot position is defined by the "character origin" of the source
glyph, that is, the position [- @emph{char-left-bearing},
@emph{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
@var{: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 @var{:source-font} or @var{:mask-font} can be closed
after the cursor is created.

@table @var
@item cursor
Type @var{cursor}.
@end table

@end defun


@defun free-cursor cursor

@table @var
@item cursor
A @var{cursor} object.
@end table

Destroys the @var{cursor} object. Cursor server resources are freed
when no other references remain.


@end defun


@node Cursor Functions, Cursor Attributes, Creating Cursors, Cursors
@section Cursor Functions


The following paragraphs describe the CLX functions used to operate on
@var{cursor} objects.

@defun query-best-cursor width height display

@table @var
@item display
A @var{display} object.
@item width
@itemx height
The requested cursor size.
@end table

Returns the cursor size closest to the requested @emph{width} and
@emph{height} that is best suited to the display. The @emph{width}
and @emph{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.

@table @var
@item width
@itemx height
Type @var{card16}.
@end table

@end defun


@defun recolor-cursor cursor foreground background

@table @var
@item cursor
A @var{cursor} object.
@item foreground
A @var{color} object specifying the new foreground color.
@item background
A @var{color} object specifying the new background color.
@end table

Changes the color of the specified @emph{cursor}. If the cursor is
displayed on a screen, the change is visible immediately.


@end defun


@node Cursor Attributes,  , Cursor Functions, Cursors
@section Cursor Attributes


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

@defun cursor-display cursor

@table @var
@item cursor
A @var{cursor} object.
@end table


Returns the @var{display} object associated with the specified
@emph{cursor}.

@table @var
@item display
Type @var{display}.
@end table

@end defun


@defun cursor-equal cursor-1 cursor-2

@table @var
@item cursor-1
@itemx cursor-2
@var{cursor} objects.
@end table

Returns true if the two arguments refer to the same server resource
and @var{nil} if they do not.


@end defun


@defun cursor-id cursor

@table @var
@item cursor
A @var{cursor} object.
@end table


Returns the unique resource ID that has been assigned to the
specified @emph{cursor}.

@table @var
@item id
Type @var{resource-id.}
@end table

@end defun


@defun cursor-p cursor

@table @var
@item cursor-p
Type @var{boolean}.
@end table

Returns true if the argument is a @var{cursor} object and
@var{nil} otherwise.

@end defun

@defun cursor-plist cursor

@table @var
@item cursor
A @var{cursor} object.
@end table


Returns and (with @code{setf}) sets the property list for the
specified @emph{cursor}. This function provides a hook where
extensions can add data.

@table @var
@item plist
A property list.
@end table

@end defun


@node Atoms, Events and Input, Cursors, Top
@chapter Atoms, Properties and Selections

@menu
* Atoms (Atoms)::
* Properties::
* Selections::
@end menu

@node Atoms (Atoms), Properties, Atoms, Atoms
@section Atoms


In X, an @emph{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. @var{xatom} is a CLX data type that permits either string or
symbol values. A string is equivalent to the @var{xatom} given by
(@var{intern} @emph{string} @var{'keyword}). A symbol is equivalent to
the @var{xatom} given by ( @var{intern} (@var{symbol-name}
@emph{symbol}) @var{'keyword}). The symbol name string of an
@var{xatom} must consist only of ISO Latin characters. Note that the
case of @var{xatom} strings is important; the @var{xatom} "Atom" is
not the same as the @var{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 @var{xatom} and @var{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 @var{xatom} objects
predefined by CLX are listed below.

@multitable @columnfractions 0.3 0.3 0.3
@item @var{:arc} @tab @var{:italic_angle} @tab @var{:string}
@item @var{:atom} @tab @var{:max_space} @tab @var{:subscript_x}
@item @var{:bitmap} @tab @var{:min_space} @tab @var{:subscript_y}
@item @var{:cap_height} @tab @var{:norm_space} @tab @var{:superscript_x}
@item @var{:cardinal} @tab @var{:notice} @tab @var{:superscript_y}
@item @var{:colormap} @tab @var{:pixmap} @tab @var{:underline_position}
@item @var{:copyright} @tab @var{:point} @tab @var{:underline_thickness}
@item @var{:cursor} @tab @var{:point_size} @tab @var{:visualid}
@item @var{:cut_buffer0} @tab @var{:primary} @tab @var{:weight}
@item @var{:cut_buffer1} @tab @var{:quad_width} @tab @var{:window}
@item @var{:cut_buffer2} @tab @var{:rectangle} @tab @var{:wm_class}
@item @var{:cut_buffer3} @tab @var{:resolution} @tab @var{:wm_client_machine}
@item @var{:cut_buffer4} @tab @var{:resource_manager} @tab @var{:wm_command}
@item @var{:cut_buffer5} @tab @var{:rgb_best_map} @tab @var{:wm_hints}
@item @var{:cut_buffer6} @tab @var{:rgb_blue_map} @tab @var{:wm_icon_name}
@item @var{:cut_buffer7} @tab @var{:rgb_color_map}@tab @var{:wm_icon_size}
@item @var{:drawable} @tab @var{:rgb_default_map} @tab @var{:wm_name}
@item @var{:end_space} @tab @var{:rgb_gray_map} @tab @var{:wm_normal_hints}
@item @var{:family_name} @tab @var{:rgb_green_map}@tab @var{:wm_size_hints}
@item @var{:font} @tab @var{:rgb_red_map} @tab @var{:wm_transient_for}
@item @var{:font_name} @tab @var{:secondary} @tab @var{:wm_zoom_hints}
@item @var{:full_name} @tab @var{:strikeout_ascent} @tab @var{:x_height}
@item @var{:integer} @tab @var{:strikeout_descent} @tab
@end multitable


When creating a new atom, the following conventions should be obeyed in
order to minimize the conflict between atom names:

@itemize @bullet
@item
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.

@item
Symbol names beginning with two underscores should be used for atoms
that are private to a single application or end user.
@end itemize


CLX provides functions to convert between an @var{xatom} and its
corresponding ID integer.  The data type of an atom ID is
@var{card29}. The @var{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 @var{xatom}.

@defun atom-name display atom-id

@table @var
@item display
A @var{display} object.
@item atom-id
A @var{card29}.
@end table

Returns the atom keyword for the @emph{atom-id} on the given
@emph{display} server.

@table @var
@item atom-name
Type @var{keyword}.
@end table

@end defun


@defun find-atom display atom-name

@table @var
@item display
A @var{display} object.
@item atom-name
An @var{xatom}.
@end table

Returns the atom ID for the given @emph{atom-name}, if it exists. If
no atom of that name exists for the display server, @var{nil} is
returned.

@table @var
@item atom-id
Type @var{card29} or @var{null}.
@end table

@end defun


@defun intern-atom display atom-name

@table @var
@item display
A @var{display} object.
@item atom-name
An @var{xatom}.
@end table

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.

@table @var
@item atom-id
Type @var{card29} or @var{null}.
@end table

@end defun


@node Properties, Selections, Atoms (Atoms), Atoms
@section Properties


For each window, an X server can record a set of
@emph{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:

@itemize @bullet
@item  Create or change a property

@item  Return property data

@item  List window properties

@item  Delete a property
@end itemize


@defun change-property window property data type format &key (:mode :replace) (:start 0) :end :transform

@table @var
@item window
A @var{window}.
@item property
A property name @var{xatom}.
@item data
A sequence of property data elements.
@item type
The property type @var{xatom}.
@item format
One of 8, 16, or 32.
@item :mode
One of @var{:replace}, @var{:append}, or @var{:prepend}.
@item :start
@itemx :end
Specify the subsequence of previous data replaced when @var{:mode} is @var{:replace}.
@item :transform
A function that transforms each data element into a data value to store.
@end table

Creates a new window property or changes an existing property. A
@var{:property-notify} event is generated for the @emph{window}.

If the @var{:mode} is @var{:replace}, the new @emph{data},
@emph{type}, and @emph{format} replace any previous values.  The
subsequence of previous data elements that are replaced is defined
by the @var{:start} and @var{:end} indexes.

If the @var{:mode} is @var{:prepend} or @var{:append}, no
previous data is changed, but the new @emph{data} is added at the
beginning or the end, respectively. For these modes, if the
@emph{property} already exists, the new @emph{type} and
@emph{format} must match the previous values.

The @var{:transform}, if given, is a function used to compute the
actual property data stored.  The @var{:transform}, which must
accept a single data element and return a single transformed data
element, is called for each data element. If the @emph{data} is a
string, the default @var{:transform} function transforms each
character into its ASCII code; otherwise, the default is to store
the @emph{data} unchanged.


@end defun


@defun delete-property window property

@table @var
@item window
A @var{window}.
@item property
A property name @var{xatom}.
@end table

Deletes the @emph{window property}. If the @emph{property} already
exists, a @var{:property-notify} event is generated for the
@emph{window}.


@end defun


@defun get-property window property &key :type (:start 0) :end :delete-p (:result-type 'list) :transform
@anchor{get-property}

@table @var
@item window
A @var{window}.
@item property
A property name @var{xatom}.
@item :type
The requested type @var{xatom} or @var{nil}.
@item :start
@itemx :end
Specify the subsequence of property @emph{data} returned.
@item :transform
A function that transforms each data element into a data value to return.
@item :delete-p
If true, the existing @emph{property} can be deleted.
@item :result-type
The t@emph{ype} of data sequence to return. Default is @var{'list}.
@end table

Returns a subsequence of the data for the window property. The
@var{:start} and @var{:end} indexes specify the property
@emph{data} elements returned. The @var{:transform} function is
called for elements of the specified subsequence to compute the
@emph{data} sequence returned. The property @emph{type} and
@emph{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 @emph{property} does not exist, the returned @emph{data} and
@emph{type} are @var{nil} and the returned @emph{format} and
@emph{bytes-after} are zero.

If the given @var{:type} is non-@var{nil} but does not match the
actual property type, then the @emph{data} returned is @var{nil},
the @emph{type} and @emph{format} returned give the actual property
values, and the @emph{bytes-after} returned gives the total number
of bytes (not elements) in the property data.

If the given @var{:type} is @var{nil} or if it matches the actual
property type, then:

@itemize @bullet
@item
The @emph{data} returned is the transformed subsequence of the
property data.

@item
The @emph{type} and @emph{format} returned give the actual
property values.

@item
The @emph{bytes-after} returned gives the actual number of data
bytes (not elements) following the last data element returned.
@end itemize


In this case, the @var{:delete-p} argument is also examined. If
@var{:delete-p} is true and @emph{bytes-after} is zero, the
property is deleted and a @var{:property-notify} event is generated
for the @emph{window}.

@table @var
@item data
Type @var{sequence}.
@item type
Type @var{xatom}.
@item format
Type (@var{member 8 16 32}).
@item bytes-after
Type @var{card32}.
@end table

@end defun


@defun list-properties window &key (:result-type 'list)

@table @var
@item window
A @var{window}.
@item :result-type
The type of sequence to return. Default is @var{'list}.
@end table


Returns a sequence containing the names of all @emph{window
properties}.
@table @var
@item properties
Type @var{sequence} of @var{keyword}.
@end table

@end defun


@defun rotate-properties window properties &optional (delta 1)

@table @var
@item window
A @var{window}.
@item properties
A sequence of @var{xatom} values.
@item delta
The index interval between source and destination elements of @emph{properties}.
@end table

Rotates the values of the given @emph{window properties}. The value
of property @emph{i} in the given sequence is changed to the value
of the property at index (@var{mod} (+ @emph{i delta})
(@var{length} @emph{properties})). This function operates much like
the @var{rotatef} macro in Common Lisp.

If (@var{mod} @emph{delta} (@var{length} @emph{properties})) is
non-zero, a @var{:property-notify} event is generated on the window
for each property, in the same order as they appear in the
@emph{properties} sequence.


@end defun


@node Selections,  , Properties, Atoms
@section 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 @emph{selection owner}. The server always knows
which window is the owner of a selection.  Selections can be created
freely by clients using @var{intern-atom} to create an atom. CLX
provides functions to inquire or change the owner of a selection and to
@emph{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 @emph{S} into his window @emph{WA}. Client A calls
@var{convert-selection} on selection atom @emph{S}, sending a
conversion request to the server. The server, in turn, sends a
@var{:selection-request} event to the current owner of @emph{S}, which
is window @emph{WB} belonging to Client B. The @var{:selection-request}
event contains the @emph{requestor} window (@emph{WA}), the selection
atom (@emph{S}), an atom identifying a requested data type, and the name
of a property of @emph{WA} into which the value of @emph{S} will be
stored.

Since @emph{WB} is the owner of @emph{S}, it must be associated with the
data defined by Client B as the value of @emph{S}. When @emph{WB} gets
the @var{:selection-request} event, Client B is expected to convert the
value of @emph{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 @var{:selection-notify} event to the requestor
window @emph{WA}, informing the requestor that the converted value for
@emph{S} is ready. Upon receiving the @var{:selection-notify} event,
Client A can call @var{get-property} to retrieve the converted value
and to paste it into @emph{WA}.

@var{NOTE:} Clients using selections must always be prepared to handle
@var{:selection-request} events and/or @var{: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 @emph{S} is a text string, Client A might request
its typeface by requesting conversion to the @var{:font} type. A type
@var{atom} can also represent a request to the selection owner to
perform some action as a side-effect of conversion (for example,
@var{:delete}). Some of the predefined atoms of an X server are
intended to be used as selection types (for example, @var{:colormap},
@var{:bitmap}, @var{: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 @var{: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 @emph{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:

@table @var
@item :primary
The @emph{primary selection}. The main vehicle for inter-client cut
and paste operations.
@item :secondary
The @emph{secondary selection}. In some environments, clients can use
this as an auxiliary to @var{:primary}.
@item :clipboard
Analogous to akill ring. Represents the most recently deleted data
item.
@end table


@defun convert-selection selection type requestor &optional property time

@table @var
@item selection
The @var{xatom} for the selection name.
@item type
The @var{xatom} for the requested data type.
@item requestor
The @var{window} to receive the converted @emph{selection} value.
@item property
The @var{xatom} for the requestor property to receive the converted value.
@item time
A @var{timestamp}.
@end table

Requests that the value of the @emph{selection} be converted to the
specified @emph{type} and stored in the given @emph{property} of the
@emph{requestor} window.

If the @emph{selection} has an owner, the X server sends a
@var{:selection-request} event to the owner window. Otherwise, if
no owner exists, the server generates on the requestor a
@var{:selection-notify} event containing a @var{nil}
@emph{property} atom.

The given @emph{property} specifies the requestor property that will
receive the converted value. If the @emph{property} is omitted, the
@emph{selection} owner will define a property to use. The
@emph{time} furnishes a timestamp representing the time of the
conversion request; by default, the current server time is used.

@var{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 @var{change-property} to append zero-length
data to some property; the timestamp in the resulting
@var{:property-notify} event can then be used.


@end defun


@defun selection-owner display selection &optional time

@table @var
@item display
A @var{display}.
@item selection
The @var{xatom} for the selection name.
@item time
A @var{timestamp}.
@end table


Returns and (with @code{setf}) changes the owner and the
last-changed @emph{time} for the @emph{selection}. If the owner is
@var{nil}, no owner for the @emph{selection} exists. When the owner
window for a @emph{selection} is destroyed, the @emph{selection}
owner is set to @var{nil} without affecting the last-changed
@emph{time}.

The @emph{time} argument is used only when changing the
@emph{selection} owner. If the @emph{time} is @var{nil}, the
current server time is used. If the @emph{time} is earlier than the
current last-changed time of the @emph{selection} or if the
@emph{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 @var{selection-owner}. If the
change in ownership is successful, the last-changed time of the
@emph{selection} is set to the specified @emph{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
@var{nil}, a @var{:selection-clear} event is generated for the
previous owner window.

@var{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 @var{:property-notify} event can then be
used.
@table @var
@item owner
Type @var{window} or @var{null}.
@end table

@end defun


@node Events and Input, Resources, Atoms, Top
@chapter Events and Input

A client application uses CLX functions to send @emph{requests} to an X
server over a display connection returned by the @var{open-display}
function. In return, the X server sends back @emph{replies} and
@emph{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

@table @asis
@item Keyboard
@var{:key-press} @var{:key-release}
@item Pointer
@var{:button-press}
@var{:button-release}
@var{:enter-notify}
@var{:leave-notify}
@var{:motion-notify}
@end table

Side-Effect Events

@table @asis
@item Client communication
@var{:client-message}
@var{:property-notify}
@var{:selection-clear}
@var{:selection-notify}
@var{:selection-request}
@item Color map state
@var{:colormap-notify}

@item Exposure
@var{:exposure}
@var{:graphics-exposure}
@var{:no-exposure}

@item Input focus
@var{:focus-in}
@var{:focus-out}

@item Keyboard and pointer state
@var{:keymap-notify}
@var{:mapping-notify}

@item Structure control
@var{:circulate-request}
@var{:configure-request}
@var{:map-request}

@item Window state
@var{:resize-request}
@var{:circulate-notify}
@var{:configure-notify}
@var{:create-notify}
@var{:destroy-notify}
@var{:gravity-notify}
@var{:map-notify}
@var{:reparent-notify}
@var{:unmap-notify}
@var{:visibility-notify}
@end table

Client programs can override the server's normal distribution of events
by@emph{ 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 @emph{freeze} the grabbed device, sending queued events
only when explicitly requested by the grabbing client. Two kinds of
grabs are possible:
@itemize @bullet

@item  Active -- Events are immediately grabbed.

@item  Passive -- Events are grabbed later, as soon as a specified device event occurs.
@end itemize

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:
@itemize @bullet

@item  Select events (@pxref{Selecting Events})

@item  Process an event on the event queue (@pxref{Processing Events})

@item  Manage the event queue (@pxref{Managing the Event Queue})

@item  Send events to other applications (@pxref{Sending Events})

@item  Read and change the pointer position (@pxref{Pointer Position})

@item  Manage the keyboard input focus (@pxref{Managing Input Focus})

@item  Grab pointer and keyboard events (@pxref{Grabbing the Pointer})

@item  Release queued events (@pxref{Releasing Queued Events})
@end itemize

This section also contains a detailed description of the content of each type of event.

@menu
* Selecting Events::
* Processing Events::
* Managing the Event Queue::
* Sending Events::
* Pointer Position::
* Managing Input Focus::
* Grabbing the Pointer::
* Grabbing a Button::
* Grabbing the Keyboard::
* Grabbing a Key::
* Event Types::
* Releasing Queued Events::
@end menu

@node Selecting Events, Processing Events, Events and Input, Events and Input
@section Selecting Events


A client @emph{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 @var{window-event-mask}
in @ref{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
@var{event-mask-class} keywords. The functions @var{make-event-keys}
and @var{make-event-mask} can be used to convert between these two
forms of an event-mask. In general, including an @var{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
@var{event-mask-class} keyword.

@multitable @columnfractions 0.5 0.5
@item Event Mask Keyword @tab Event Types Selected
@item @var{:button-1-motion}
@tab @var{:motion-notify} when @var{:button-1} is down
@item @var{:button-2-motion}
@tab @var{:motion-notify} when @var{:button-2} is down
@item @var{:button-3-motion}
@tab @var{:motion-notify} when @var{:button-3} is down
@item @var{:button-4-motion}
@tab @var{:motion-notify} when @var{:button-4} is down
@item @var{:button-5-motion}
@tab @var{:motion-notify} when @var{:button-5} is down
@item @var{:button-motion}
@tab @var{:motion-notify} when any pointer button is down
@item @var{:button-press}
@tab @var{:button-press}
@item @var{:button-release}
@tab @var{:button-release}
@item @var{:colormap-change}
@tab @var{:colormap-notify}
@item @var{:enter-window}
@tab @var{:enter-notify}
@item @var{:exposure}
@tab @var{:exposure}
@item @var{:focus-change}
@tab @var{:focus-in} @var{:focus-out}
@item @var{:key-press}
@tab @var{:key-press}
@item @var{:key-release}
@tab @var{:key-release}
@item @var{:keymap-state}
@tab @var{:keymap-notify}
@item @var{:leave-window}
@tab @var{:leave-notify}
@item @var{:owner-grab-button}
@tab Pointer events while button is grabbed
@item @var{:pointer-motion}
@tab @var{:motion-notify}
@item @var{:pointer-motion-hint}
@tab Single @var{:motion-notify} only
@item @var{:property-change}
@tab @var{:property-notify}
@item @var{:resize-redirect}
@tab @var{:resize-request}
@item @var{:structure-notify}
@tab @var{:circulate-notify} @var{:configure-notify} @var{:destroy-notify} @var{:gravity-notify} @var{:map-notify} @var{:reparent-notify} @var{:unmap-notify}
@item @var{:substructure-redirect}
@tab @var{:circulate-request} @var{:configure-request} @var{:map-request}
@item @var{:visibility-change}
@tab @var{:visibility-notify}
@end multitable


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
@var{copy-plane} and @var{copy-area} functions cause
@var{:graphics-exposure} and @var{:no-exposure} events to be reported,
unless exposures are turned @var{:off} in the graphics context (see
@var{copy-area} and @var{copy-plane} in @ref{Area and Plane Operations},
and @var{gcontext-exposures} in paragraph 5.4.6, Exposures).  Also, @var{:selection-clear}, @var{:selection-request},
@var{:selection-notify} and @var{:client-message} events can be
received at any time, but they are generally sent only to clients using
selections (@pxref{Client Communications Events}). @var{: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:
@itemize @bullet

@item  Only one client at a time can include @var{:substructure-redirect} in its event-mask

@item  Only one client at a time can can include @var{:button-press} in its event-mask

@item  Only one client at a time can include @var{:resize-redirect} in its event-mask
@end itemize

@node Processing Events, Managing the Event Queue, Selecting Events, Events and Input
@section Processing Events


Events received by a CLX client are stored in an @emph{event queue}
until they are read and processed. Events are processed by @emph{handler
functions}.

@defun handler-function &rest event-slots &key :display :event-key :send-event-p &allow-other-keys

@table @var
@item :display
A @var{display} for the connection that returned the event.
@item :event-key
An @var{event-key} keyword specifying the event type.
@item :send-event-p
If true, the event was sent from another application using the
@var{send-event} function.
@end table


The arguments to a handler function are keyword-value pairs that
describe the contents of an event. The actual @emph{event-slots}
passed depend on the event type, except that @var{:display},
@var{:event-key}, and @var{:send-event-p} are given for all event
types. The keyword symbols used for each event type are event slot
names defined by the @var{declare-event} macro and are described in
@ref{Declaring Event Types}.

If a handler returns non-@var{nil}, the event is considered
@emph{processed} and can be removed from the event queue. Otherwise,
if a handler function returns @var{nil}, the event can remain in
the event queue for later processing.
@table @var
@item handled-p
Type @var{boolean}.
@end table

@end defun


@defun process-event display &key :handler :timeout :peek-p :discard-p (:force-output-p t)

@table @var
@item display
A @var{display}.
@item :handler
A handler function or a sequence of handler functions.
@item :timeout
Specifies the timeout delay in seconds.
@item :peek-p
If @var{nil}, events are removed from the event queue after processing.
@item :discard-p
If true, unprocessed events are discarded.
@item :force-output-p
If true, buffered output requests are sent.
@end table


Invokes @var{:handler} on each queued event until @var{:handler}
returns non-@var{nil}. Then, the non-@var{nil :handler} value is
returned by @var{process-event}. If @var{:handler} returns
@var{nil} for each event in the event queue, @var{process-event}
waits for another event to arrive. If timeout is non-@var{nil} and
no event arrives within the specified timeout interval (given in
seconds), @var{process-event} returns @var{nil}; if timeout is
@var{nil}, @var{process-event} will not return until
@var{:handler} returns non-@var{nil}. @var{process-event} may
wait only once on network data, and therefore timeout prematurely.

If @var{:force-output-p} is true, @var{process-event} first
invokes @var{display-force-output} to send any buffered
requests. If @var{:peek-p} is true, a processed event is not
removed from the queue. If @var{:discard-p} is true, unprocessed
events are removed from the queue; otherwise, unprocessed events are
left in place.

If @var{: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 ( @var{position
event-key *event-key-vector*}).
@table @var
@item handled-p
Type @var{boolean}.
@end table

@end defun


@defmac event-case display &key :timeout :peek-p :discard-p (:force-output-p t) &body clauses
@anchor{event-case}

@table @var
@item display
A @var{display}.
@item :handler
A handler function or a sequence of handler functions.
@item :timeout
Specifies the timeout delay, in seconds.
@item :peek-p
If @var{nil}, events are removed from the event queue after processing.
@item :discard-p
If true, unprocessed events are discarded.
@item :force-output-p
If true, buffered output requests are sent.
@item clauses
Code to process specified event types.
@end table

Executes the matching clause for each queued event until a clause
returns non-@var{nil}. The non-@var{nil} clause value is then
returned. Each of the clauses is a list of the form
(@emph{event-match} [@emph{event-slots}] &rest @emph{forms}),
where:
@itemize @bullet

@item
@emph{event-match} -- Either an @var{event-key}, a list of
@var{event-keys}, otherwise, or @var{t}. It is an error for the
same key to appear in more than one clause.

@item
@emph{event-slots} -- If given, a list of (non-keyword) event slot
symbols defined for the specified event type(s). @xref{Declaring Event Types}.

@item
@emph{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.
@end itemize

A clause matches an event if the @var{event-key} is equal to or a
member of the @emph{event-match}, or if the @emph{event-match} is
@var{t} or @var{otherwise}. If no @var{t} or @var{otherwise}
clause appears, it is equivalent to having a final clause that
returns @var{nil}. If @emph{event-slots} is given, these symbols
are bound to the value of the corresponding event slot in the clause
forms. Each element of @emph{event-slots} can also be a list of the
form (@emph{event-slot-keyword variable}), in which case the
@emph{variable} symbol is bound to the value of the event slot
specified by the @emph{event-slot-keyword}.

If every clause returns @var{nil} for each event in the event
queue, @var{event-case} waits for another event to arrive. If
@var{:timeout} is non-@var{nil} and no event arrives within the
specified timeout interval (given in seconds), @var{event-case}
returns @var{nil}; if @var{:timeout} is @var{nil},
@var{event-case} will not return until a clause returns
non-@var{nil}. @var{event-case} may wait only once on network data
and therefore timeout prematurely.

If @var{:force-output-p} is true, @var{event-case} first invokes
@var{display-force-output} to send any buffered requests. If
@var{:peek-p} is true, a processed event is not removed from the
queue. If @var{:discard-p} is true, unprocessed events are removed
from the queue; otherwise, unprocessed events are left in place.

@table @var
@item handled-p
Type @var{boolean}.
@end table

@end defmac



@defmac event-cond display &key :timeout :peek-p :discard-p (:force-output-p t) &body clauses

@table @var
@item handled-p
Type @var{boolean}.
@end table


Similar to @var{event-case} except that each of the clauses is a
list of the form (@emph{event-match} [@emph{event-slots}]
@emph{test-form} &rest @emph{forms}). Executes the
@emph{test-form} of the clause that matches each queued event until
a @emph{test-form} returns non-@var{nil}. The body @emph{forms} of
the clause are then executed. The values returned by the last clause
body form are then returned by @var{event-cond}.

When a @emph{test-form} returns true and @var{:peek-p} is
@var{nil}, or when a @emph{test-form} returns @var{nil} and
@var{:discard-p} is true, the matching event is removed from the
event queue before the body @emph{forms} are executed.
@table @var
@item display
A @var{display}.
@item :handler
A handler function or a sequence of handler functions.
@item :timeout
Specifies the timeout delay in seconds.
@item :peek-p
If @var{nil}, events are removed from the event queue after processing.
@item :discard-p
If true, unprocessed events are discarded.
@item :force-output-p
If true, buffered output requests are sent.
@item clauses
Code to process specified event types.
@end table

@end defmac



@node Managing the Event Queue, Sending Events, Processing Events, Events and Input
@section Managing the Event Queue


The following paragraphs describe CLX functions and macros used to:
@itemize @bullet

@item  Put a new event on the event queue

@item  Discard the current event

@item  Return the current length of the event queue

@item  Gain exclusive access to the event queue for a client process
@end itemize

@defun queue-event display event-key &rest event-slots &key :append-p &allow-other-keys

@table @var
@item display
A @var{display}.
@item event-key
Specifies the type of event placed in the queue.
@item event-slots
Keyword-value pairs that describe the contents of an event.
@item :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.
@end table

Places an event of the type given by @emph{event-key} into the event
queue. When @var{: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 @emph{event-slots} passed depend on the event
type. The keyword symbols used for each event type are event slot
names defined by the @var{declare-event} macro and are described in
@ref{Declaring Event Types}.



@end defun


@defun discard-current-event display

@table @var
@item display
A @var{display}.
@end table


Discards the current event for the @emph{display}. Returns
@var{nil} when the event queue is empty; otherwise, returns
@var{t}. This function provides extra flexibility for discarding
events, but it should be used carefully; use @var{event-cond}
instead, if possible. Typically, @var{discard-current-event} is
called inside a handler function or a clause of an @var{event-case}
form and is followed by another call to @var{process-event},
@var{event-case}, or @var{event-cond}.
@table @var
@item discarded-p
Type @var{boolean}.
@end table

@end defun


@defun event-listen display &optional (timeout 0)

@table @var
@item display
A @var{display}.
@item timeout
The number of seconds to wait for events.
@end table


Returns the number of events queued locally. If the event queue is
empty, @var{event-listen} waits for an event to arrive. If timeout
is non-@var{nil} and no event arrives within the specified timeout
interval (given in seconds), @var{event-listen} returns @var{nil};
if timeout is @var{nil}, @var{event-listen} will not return until
an event arrives.
@table @var
@item event-count
Type @code{(or null integer)}.
@end table

@end defun

@defmac with-event-queue display &body body
@anchor{with-event-queue}

@table @var
@item display
A @var{display}.
@item body
Forms to execute.
@end table

Executes the @emph{body} in a critical region in which the executing
client process has exclusive access to the event queue.

@end defmac



@node Sending Events, Pointer Position, Managing the Event Queue, Events and Input
@section 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.

@defun send-event window event-key event-mask &rest event-slots &key :propagate-p :display &allow-other-keys

@table @var
@item window
The destination @var{window} for the event.
@item event-key
An @var{event-key} defining the type of event to send.
@item event-mask
Specifies the event types that receiving clients must select.
@item event-slots
Keyword-value pairs that describe the contents of an event.
@item :propagate-p
If true, the event can be propagated to ancestors of the destination window.
@item :display
A @var{display}.
@end table

Sends an event specified by the @emph{event-key} and
@emph{event-slots} to the given destination @emph{window}. Any
active grabs are ignored. The @emph{event-slots} passed depend on
the event type. The keyword symbols used for each event type are
event slot names defined by the @var{declare-event} macro and are
described in @ref{Declaring Event Types}.

If the @emph{window} is @var{:pointer-window}, the destination
@emph{window} is replaced with the window containing the
pointer. If the @emph{window} is @var{:input-focus}, the
destination @emph{window} is replaced with the descendant of the
focus window that contains the pointer or (if no such descendant
exists) the focus window. The @var{:display} keyword is only
required if the @emph{window} is @var{:pointer-window} or
@var{:input-focus}.

The @emph{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
@var{send-event-p} event slot is set to true.

If the @emph{event-mask} is @var{nil}, the event is sent to the
client that created the destination @emph{window} with an
@emph{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 @emph{event-mask} on the
destination @emph{window}.

If @var{:propagate-p} is true and no clients have selected any of
the event types in @emph{event-mask} on the destination
@emph{window}, the destination is replaced with the closest
ancestor of @emph{window} for which some client has selected a
type in @emph{event-mask} and no intervening window has that type
in its do-not-propagate mask. If no such window exists, or if the
@emph{window} is an ancestor of the focus window and
@var{: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 @emph{event-mask}.


@end defun


@node Pointer Position, Managing Input Focus, Sending Events, Events and Input
@section Pointer Position


The CLX functions affecting pointer position are discussed in the
following paragraphs.

@defun query-pointer window

@table @var
@item window
A @var{window} specifying the coordinate system for the returned position.
@end table


Returns the current pointer coordinates relative to the given
@emph{window}. If @var{query-pointer} returns @var{nil} for
@emph{same-screen-p}, the pointer is not on the same screen as the
@emph{window}. In this case, @var{query-pointer} returns a value
of @var{nil} for @emph{child} and a value of zero for @emph{x}
and @emph{y}. If @var{query-pointer} returns true for
@emph{same-screen-p}, the returned @emph{x} and @emph{y} are
relative to the origin of window. The @emph{child} is the child of
the window containing the pointer, if any. The @emph{state-mask}
returned gives the current state of the modifier keys and pointer
buttons. The returned @emph{root} is the root window currently
containing the pointer. The returned @emph{root-x} and
@emph{root-y} specify the pointer coordinates relative to
@emph{root}.
@table @var
@item x
Type @var{int16}.
@item y
Type @var{int16}.
@item same-screen-p
Type @var{boolean}.
@item child
Type @var{window} or @var{null}.
@item state-mask
Type @var{card16}.
@item root-x
Type @var{int16}.
@item root-y
Type @var{int16}.
@item root
Type @var{window}.
@end table

@end defun


@defun global-pointer-position display

@table @var
@item display
A @var{display}.
@end table


Returns the @emph{root} window currently containing the @emph{display} pointer and the current
position of the pointer relative to the @emph{root}.
@table @var
@item root-x
Type @var{int16}.
@item root-y
Type @var{int16}.
@item root
Type @var{window}.
@end table

@end defun


@defun pointer-position window

@table @var
@item window
A @var{window} specifying the coordinate system for the returned position.
@end table


Returns the current pointer coordinates relative to the given
@emph{window}. If @var{pointer-position} returns @var{nil} for
@emph{same-screen-p}, the pointer is not on the same screen as the
@emph{window}.  In this case, @var{pointer-position} returns a
value of @var{nil} for @emph{child} and a value of zero for
@emph{x} and @emph{y}. If @var{pointer-position} returns true for
@emph{same-screen-p}, the returned @emph{x} and @emph{y} are
relative to the origin of @emph{window}.
@table @var
@item x
Type @var{int16}.
@item y
Type @var{int16}.
@item same-screen-p
Type @var{boolean}.
@item child
Type @var{window} or @var{null}.
@end table

@end defun


@defun motion-events window &key :start :stop (:result-type 'list)

@table @var
@item window
The @var{window} containing the returned motion events.
@item :start
@itemx :stop
@var{timestamp} values for the time interval for returned motion events.
@item :result-type
The form of the returned motion events.
@end table


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 @emph{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 @var{motion-events} function returns all events in the motion
history buffer that fall between the specified @var{:start} and
@var{:stop} timestamps (inclusive) and have coordinates that lie
within the specified @emph{window} (including borders) at its
present placement. If the @var{:start} time is later than the
@var{:stop} time or if the @var{:start} time is in the future,
no events are returned.
@table @var
@item motion-events
Type @code{(repeat-seq (int16 x) (int16 y) (timestamp time))}.
@end table

@end defun


@defun warp-pointer destination destination-x destination-y

@table @var
@item destination
The @var{window} into which the pointer is moved.
@item destination-x
@itemx destination-y
The new position of the pointer relative to the destination.
@end table

Moves the pointer to the given coordinates relative to the
@emph{destination} window.  @var{warp-pointer} should be rarely be
used since the user should normally be in control of the pointer
position. @var{warp-pointer} generates events just as if the user
had instantaneously moved the pointer from one position to another.

@var{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.


@end defun


@defun warp-pointer-relative display x-offset y-offset

@table @var
@item display
A @var{display}.
@item x-offset
@itemx y-offset
The offsets used to adjust the pointer position.
@end table

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. @var{warp-pointer-relative} generates events just as if
the user had instantaneously moved the pointer from one position to
another.

@var{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.


@end defun


@defun warp-pointer-if-inside destination destination-x destination-y source source-x source-y &optional (source-width 0) (source-height 0)

@table @var
@item destination
The @var{window} into which the pointer is moved.
@item destination-x
@itemx destination-y
The new position of the pointer relative to the @emph{destination}.
@item source
The @var{window} that must currently contain the pointer.
@item source-x
@itemx source-y
@itemx source-width
@itemx source-height
The source rectangle that must currently contain the pointer.
@end table

Moves the pointer to the given position relative to the
@emph{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 @emph{source} window. If
@emph{source-height} is zero, it is replaced with the current height
of @emph{source} window minus @emph{source-y}. If
@emph{source-width} is zero, it is replaced with the current width
of @emph{source} window minus @emph{source-x}.

@var{warp-pointer-if-inside} generates events just as if the user
had instantaneously moved the pointer from one position to
another. @var{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.


@end defun

@defun warp-pointer-relative-if-inside x-offset y-offset source source-x source-y &optional (source-width 0) (source-height 0)

@table @var
@item x-offset
@itemx y-offset
The offsets used to adjust the pointer position.
@item source
The @var{window} that must currently contain the pointer.
@item source-x
@itemx source-y
@itemx source-width
@itemx source-height
The source rectangle that must currently contain the pointer.
@end table

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 @emph{source} window. If
@emph{source-height} is zero, it is replaced with the current height
of @emph{source-window} minus @emph{source-y}. If
@emph{source-width} is zero, it is replaced with the current width
of @emph{source-window} minus @emph{source-x}.

@var{warp-pointer-relative-if-inside} generates events just as if
the user had instantaneously moved the pointer from one position to
another. @var{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.



@end defun


@node Managing Input Focus, Grabbing the Pointer, Pointer Position, Events and Input
@section Managing Input Focus


CLX provides the @var{set-focus-input} and @var{focus-input} functions
to set and get the keyboard input focus window.

@defun set-input-focus display focus revert-to &optional time

@table @var
@item display
A @var{display}.
@item focus
The new input focus @var{window}.
@item revert-to
The focus @var{window} when focus is no longer viewable.
@item time
A @var{timestamp}.
@end table

Changes the keyboard input focus and the last-focus-change
time. The function has no effect if the specified @emph{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 @emph{time}. The @var{set-input-focus}
function causes the X server to generate @var{:focus-in} and
@var{:focus-out} events.

If @var{:none} is specified as the @emph{focus}, all keyboard
events are discarded until a new focus window is set. In this
case, the @emph{revert-to} argument is ignored.

If a window is specified as the @emph{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 @var{:pointer-root} is specified as the @emph{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 @emph{revert-to} argument is ignored.

The specified @emph{focus} window must be viewable at the time of
the request. If the @emph{focus} window later becomes not
viewable, the new focus window depends on the @emph{revert-to}
argument. If @emph{revert-to} is specified as @var{:parent}, the
@emph{focus} reverts to the parent (or the closest viewable
ancestor) and the new @emph{revert-to} value is take to be
@var{:none}. If @emph{revert-to} is @var{:pointer-root} or
@var{:none}, the @emph{focus} reverts to that value. When the
@emph{focus} reverts, @var{:focus-in} and @var{:focus-out}
events are generated, but the last-focus-change time is not
affected.


@end defun


@defun input-focus display

@table @var
@item display
A @var{display}.
@end table


Returns the @emph{focus} window, @var{:pointer-root}, or
@var{:none}, depending on the current state of the focus
window. @emph{revert-to} returns the current focus revert-to
state.
@table @var
@item focus
Type (@var{or window} (@var{member :none :pointer-root})).
@item revert-to
Type (@var{or window} (@var{member :none :pointer-root :parent})).
@end table

@end defun


@node Grabbing the Pointer, Grabbing a Button, Managing Input Focus, Events and Input
@section Grabbing the Pointer


CLX provides the @var{grab-pointer} and @var{ungrab-pointer} functions
for grabbing and releasing pointer control.

@defun grab-pointer window event-mask &key :owner-p :sync-pointer-p :sync-keyboard-p :confine-to :cursor :time

@table @var
@item window
The @var{window} grabbing the pointer.
@item event-mask
A @var{pointer-event-mask}.
@item :owner-p
If true, all client windows receive pointer events normally.
@item :sync-pointer-p
Indicates whether the pointer is in synchronous or asynchronous mode.
@item :sync-keyboard-p
Indicates whether the keyboard is in synchronous or asynchronous mode.
@item :confine-to
A @var{window} to which the pointer is confined.
@item :cursor
A @var{cursor}.
@item :time
A @var{timestamp}. A @var{nil} value means the current server time is used.
@end table


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 @var{:owner-p} is @var{nil}, all generated pointer events are
reported with respect to @emph{window}, and are only reported if
selected by @emph{event-mask}. If @var{: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 @emph{window}, and is only reported if selected by
@emph{event-mask}. For either value of @var{:owner-p}, unreported
events are simply discarded.

If @var{:sync-pointer-p} is @var{nil}, pointer event processing
continues normally (asynchronously); if the pointer is currently
frozen by this client, then processing of pointer events is
resumed. If @var{: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 @var{allow-events} request.
Actual pointer changes are not lost while the pointer is frozen;
they are simply queued for later processing.

If @var{:sync-keyboard-p} is @var{nil}, keyboard event processing
is unaffected by activation of the grab. If @var{: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 @var{allow-events}
request. Actual keyboard changes are not lost while the keyboard is
frozen; they are simply queued for later processing.

If @var{:cursor} is specified, it is displayed regardless of what
window the pointer is in.  Otherwise, the normal cursor for the
@emph{window} is displayed.

If a @var{:confine-to} window is specified, the pointer is
restricted to stay within that window.  The @var{:confine-to}
window does not need to have any relationship to the
@emph{window}. If the pointer is not initially in the
@var{:confine-to} window, it is warped automatically to the closest
edge (with @var{:enter}/@var{:leave-events} generated normally)
just before the grab activates.  If the @var{:confine-to} window is
subsequently reconfigured, the pointer is warped automatically as
necessary to keep it contained in the window.

@var{grab-pointer} generates @var{:enter-notify} and
@var{:leave-notify} events. @var{grab-pointer} can fail with a
status of:
@itemize @bullet

@item
@var{:already-grabbed} if the pointer is actively grabbed by some
other client

@item
@var{:frozen} if the pointer is frozen by an active grab of
another client

@item
@var{:not-viewable} if the @emph{window} or the
@var{:confine-to} window is not viewable, or if the
@var{:confine-to} window lies completely outside the boundaries
of the root window.

@item
@var{: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 @var{:success} is returned by
@var{grab-pointer}.
@end itemize
@table @var
@item grab-status
One of @var{:already-grabbed}, @var{:frozen}, @var{:invalid-time},
@var{:not-viewable}, or @var{:success}.
@end table

@end defun


@defun ungrab-pointer display &key :time

@table @var
@item display
A @var{display}.
@item :time
A @var{timestamp}.
@end table

Releases the pointer if this client has it actively grabbed (from
either @var{grab-pointer}, @var{grab-button}, or from a normal
button press), and releases any queued events. The request has no
effect if the specified @var{:time} is earlier than the
last-pointer-grab time or is later than the current server time. An
@var{ungrabpointer} is performed automatically if the event window
or @var{:confine-to} window for an active pointer grab becomes not
viewable.

This request generates @var{:enter-notify} and @var{:leave-notify}
events.


@end defun


@defun change-active-pointer-grab display event-mask &optional cursor time

@table @var
@item display
A @var{display}.
@item event-mask
A @var{pointer-event-mask}.
@item cursor
A @var{cursor} or @var{nil}.
@item time
A @var{timestamp}.
@end table

Changes the specified dynamic parameters if the pointer is actively
grabbed by the client and the specified @emph{time} is no earlier
than the last-pointer-grab time and no later than the current server
time. The interpretation of @emph{event-mask} and @emph{cursor} are
as in @var{grab-pointer}.  @var{change-active-pointer-grab} has no
effect on the passive parameters of a @var{grab-button}.


@end defun


@node Grabbing a Button, Grabbing the Keyboard, Grabbing the Pointer, Events and Input
@section Grabbing a Button


CLX provides the @var{grab-button} and @var{ungrab-button} functions
for passively grabbing and releasing pointer control.

@defun grab-button window button event-mask &key (:modifiers 0) :owner-p :sync-pointer-p :sync-keyboard-p :confine-to :cursor

@table @var
@item window
A @var{window}.
@item button
The button (type @var{card8}) pressed or @var{:any}.
@item event-mask
A @var{pointer-event-mask}.
@item :modifiers
A @var{modifier-mask}.
@item :owner-p
If true, all client windows receive pointer events normally.
@item :sync-pointer-p
Indicates whether the pointer is handled in a synchronous or asynchronous fashion.
@item :sync-keyboard-p
Indicates whether the keyboard is in synchronous or asynchronous mode.
@item :confine-to
A @var{window} to which the pointer is confined.
@item :cursor
A @var{cursor}.
@end table

This request establishes a passive grab. If the specified
@emph{button} is pressed when the specified modifier keys are down
(and no other buttons or modifier keys are down), and:
@itemize @bullet

@item  @emph{window} contains the pointer

@item  The @var{:confine-to} window (if any) is viewable

@item  These constraints are not satisfied for any ancestor of @emph{window}
@end itemize

then:
@itemize @bullet

@item
The pointer is actively grabbed as described with
@var{grab-pointer}

@item
The last-pointer-grab time is set to the time that the button was
pressed (as transmitted in the @var{:button-press} event)

@item
The @var{:button-press} event is reported
@end itemize

The interpretation of the remaining arguments is the same as with
@var{grab-pointer}. The active grab is terminated automatically
when all buttons are released (independent of the state of modifier
keys).

A zero @emph{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 @emph{button} of @var{:any} is
equivalent to issuing the request for all possible
buttons. Otherwise, it is not required that the specified
@emph{button} currently be assigned to a physical button.


@end defun


@defun ungrab-button window button &key (:modifiers 0)

@table @var
@item window
A @var{window}.
@item button
The button (type @var{card8}) that is released or @var{:any}.
@item :modifiers
A @var{modifier-mask}.
@end table

Releases the passive button/key combination on the specified
@emph{window} if it was grabbed by this client. A zero
@emph{modifier} mask is equivalent to issuing the request for all
possible modifier combinations including the combination of no
modifiers. A @emph{button} of @var{:any} is equivalent to issuing
the request for all possible buttons. This has no effect on an
active grab.


@end defun


@node Grabbing the Keyboard, Grabbing a Key, Grabbing a Button, Events and Input
@section Grabbing the Keyboard


CLX provides the @var{grab-keyboard} and @var{ungrab-keyboard}
functions for actively grabbing and releasing control of the keyboard.

@defun grab-keyboard window &key :owner-p :sync-pointer-p :sync-keyboard-p :time

@table @var
@item window
A @var{window}.
@item :owner-p
If true, all client windows receive keyboard input normally.
@item :sync-pointer-p
Indicates whether the pointer is in synchronous or asynchronous mode.
@item :sync-keyboard-p
Indicates whether the keyboard is in synchronous or asynchronous mode.
@item :time
A @var{timestamp}.
@end table


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.  @var{grab-keyboard} generates
@var{:focus-in} and @var{:focus-out} events.

If @var{:owner-p} is @var{nil}, all generated key events are
reported with respect to @emph{window}. If @var{: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 @emph{window}.  Both @var{:key-press} and
@var{:key-release} events are always reported, independent of any
event selection made by the client.

If @var{:sync-keyboard-p} is @var{nil}, keyboard event processing
continues normally (asynchronously); if the keyboard is currently
frozen by this client, then processing of keyboard events is
resumed. If @var{: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 @var{allow-events} request. Actual keyboard changes are
not lost while the keyboard is frozen; they are simply queued for
later processing.

If @var{:sync-pointer-p} is @var{nil}, pointer event processing is
unaffected by activation of the grab. If @var{: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 @var{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:
@itemize @bullet

@item
@var{:already-grabbed} if the keyboard is actively grabbed by
some other client

@item
@var{:frozen} if the keyboard is frozen by an active grab from
another client

@item
@var{:not-viewable} if @emph{window} is not viewable

@item
@var{:invalid-time} if the specified time is earlier than the
last-keyboard-grab time or later than the current server
time. Otherwise, @var{grab-keyboard} returns a status of
@var{:success} and last-keyboard-grab time is set to the
specified time, with current-time replaced by current server time.
@end itemize
@table @var
@item grab-status
One of @var{:already-grabbed}, @var{:frozen}, @var{:invalid-time},
@var{:not-viewable}, or @var{:success}.
@end table

@end defun


@defun ungrab-keyboard display &key :time

@table @var
@item display
A @var{display}.
@item :time
A @var{timestamp}.
@end table

Releases the keyboard if this client has it actively grabbed (from
either @var{grab-keyboard} or @var{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 @var{ungrab-keyboard} is performed
automatically if the event window for an active keyboard grab
becomes not viewable.


@end defun


@node Grabbing a Key, Event Types, Grabbing the Keyboard, Events and Input
@section Grabbing a Key


The following paragraphs describe the functions used for passively
grabbing and releasing the keyboard.

@defun grab-key window key &key (:modifiers 0) :owner-p :sync-pointer-p :sync-keyboard-p :time

@table @var
@item window
A @var{window}.
@item key
The key (type @var{card8}) to be grabbed or @var{:any}.
@item :modifiers
A @var{modifier-mask}.
@item :owner-p
If true, all client windows receive keyboard input normally.
@item :sync-pointer-p
Indicates whether the pointer is in synchronous or asynchronous mode.
@item :sync-keyboard-p
Indicates whether the keyboard is in synchronous or asynchronous mode.
@item :time
A @var{timestamp}.
@end table

This request establishes a passive grab on the keyboard. If the
specified @emph{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:
@itemize @bullet

@item
@emph{window} is an ancestor of (or is) the focus window

@item
@emph{window} is a descendant of the focus window and contains the
pointer

@item
These constraints are not satisfied for any ancestor of
@emph{window}, then the following occurs:
@itemize @bullet

@item
The keyboard is actively grabbed as described in
@var{grab-keyboard}

@item
The last-keyboard-grab time is set to the time that the
@emph{key} was pressed (as transmitted in the
@var{:key-press} event)

@item
The @var{:key-press} event is reported
@end itemize
@end itemize
The interpretation of the remaining arguments is as for
@var{grab-keyboard}. The active grab is terminated automatically when
the specified @emph{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 @emph{key} of @var{:any} is
equivalent to issuing the request for all possible
keycodes. Otherwise, the @emph{key} must be in the range specified
by @var{display-min-keycode} and @var{display-max-keycode} in the
connection setup.


@end defun


@defun ungrab-key window key &key (:modifiers 0)

@table @var
@item window
A @var{window}.
@item key
The key (type @var{card8}) to be released or @var{:any}.
@item :modifiers
A @var{modifier-mask}.
@end table

Releases the @emph{key} combination on the specified @emph{window}
if it was grabbed by this client. A zero modifier mask of
@var{:any} is equivalent to issuing the request for all possible
modifier combinations (including the combination of no modifiers). A
@emph{key} of @var{:any} is equivalent to issuing the request for
all possible keycodes. @var{ungrab-key} has no effect on an active
grab.


@end defun


@node Event Types, Releasing Queued Events, Grabbing a Key, Events and Input
@section 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
@var{event-case} and @var{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 @var{declare-event} macro to define event slot symbols and to
map these symbols to specific event data items returned by the X
server (@pxref{Declaring Event Types}).

The following paragraphs describe each event type, listing its
@var{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 @var{send-event} or to an event
handler function; it can also appear in the @emph{event-match} form of
an @var{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 @var{send-event} or to
an event handler function; as non-keyword symbols, they can also be in
the @emph{event-slots} form of an @var{event-case} clause.

In certain cases, more than one name symbol is defined for the same
event slot. For example, in @var{:key-press} events, the symbols
@emph{window} and @emph{event-window} both refer to the same event data
item.

@menu
* Keyboard and Pointer Events::
* Input Focus Events::
* Keyboard and Pointer State Events::
* Exposure Events::
* Window State Events::
* Structure Control Events::
* Client Communications Events::
* Declaring Event Types::
@end menu

@node Keyboard and Pointer Events, Input Focus Events, Event Types, Event Types
@subsection Keyboard and Pointer Events


The keyboard and pointer events are: @var{:key-press} @var{:key-release},
@var{:button-press}, @var{:button-release}, @var{:motion-notify},
@var{:enter-notify}, and @var{:leave-notify}.

@deftp {Event Type} :key-press
@deftpx {Event Type} :key-release
@deftpx {Event Type} :button-press
@deftpx {Event Type} :button-release

Selected by @var{:key-press}, @var{:key-release}, @var{:button-press},
or @var{:button-release}.

@var{:key-press}, and @var{:key-release} events are generated when
a key or pointer button changes state. Note that @var{:key-press}
and @var{: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 @emph{source} window. The @emph{event}
@emph{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 @var{:button-press} event has the effect of a temporary
@var{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 @emph{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
@var{:button-press} event, and the last-pointer-grab time is set to
the current server time. The effect is essentially equivalent to
calling @var{grab-button} with the following arguments:

@table @var
@item @emph{window}
The event window.
@item @emph{button}
The button that was pressed.
@item @emph{event-mask}
The client's selected pointer events on the event window.
@item @var{:modifiers}
0
@item @var{:owner-p}
@var{t} if the client has @var{:owner-grab-button} selected on the event window; otherwise @var{nil}.
@item @var{:sync-pointer-p}
@var{nil}
@item @var{:sync-keyboard-p}
@var{nil}
@item @var{:confine-to}
@var{nil}
@item @var{:cursor}
@var{nil}
@end table


The @var{:button-press} grab is terminated automatically when all
buttons are released. The functions @var{ungrab-pointer} and
@var{change-active-pointer-grab} can both be used to modify the
@var{:button-press} grab.

@table @var
@item window
@item event-window
Type @var{window}.

The window receiving the event.

@item code
Type @var{card8}.

The @emph{code} argument varies with the event type. For @var{:key-press} and
@var{:key-release}, @emph{code} is the keycode (@pxref{Keyboard Encodings}). For
@var{:button-press} and @var{:button-release}, @emph{code} is the pointer button number.

@item x
Type @var{int16}.

If @emph{event-window} is on the same screen as root, then @emph{x} and @emph{y} are the pointer
coordinates relative to the @emph{event-window}; otherwise @emph{x} and @emph{y} are zero.

@item y
Type @var{int16}.

If @emph{event-window} is on the same screen as root, then @emph{x} and @emph{y} are the pointer
coordinates relative to the @emph{event-window}; otherwise @emph{x} and @emph{y} are zero.

@item state
Type @var{card16}.

A mask that gives the state of the buttons and modifier keys just before the
event.

@item time
Type @var{card32}.

A timestamp for the moment when the event occurred.

@item root
Type @var{window}.

The root window of the source window.

@item root-x
Type @var{int16}.

The x coordinate of the pointer position relative to root at the time of the event.

@item root-y
Type @var{int16}.

The y coordinate of the pointer position relative to root at the time of the event@emph{.}

@item child
Type (@var{or null window}).

If the source window is an inferior of the @emph{event-window}, @emph{child} is set to the child
of @emph{event-window} that is an ancestor of (or is) the source window; otherwise, it is
set to @var{nil}@emph{.}

@item same-screen-p
Type @var{boolean}.

True if @emph{event-window} and root are on the same screen.
@end table

@end deftp


@deftp {Event Type} :motion-notify

Selected by: @var{:button-1-motion}, @var{:button-2-motion},
@var{:button-3-motion}, @var{:button-4-motion},
@var{:button-5-motion}, @var{:button-motion}, or
@var{:pointer-motion}.


The @var{:motion-notify} event is generated when the pointer
moves. A @var{:motion-notify} event has the same slots as
@var{:button-press} @var{:button-release}, @var{:key-press}, and
@var{:key-release} events, with the exception that the @emph{code}
slot is replaced by the @emph{hint-p} slot. As with these other
events, the event window for @var{: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 @var{:motion-notify} in its do-not-propagate-mask).The
actual window used for reporting can be modified by active grabs.

@var{: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 @var{:pointer-motion} generates
@var{:motion-notify} events regardless of the state of the pointer
buttons. By selecting some subset of @var{:button[1-5]-motion}
instead, @var{:motion-notify} events are only received when one or
more of the specified buttons are pressed. By selecting
@var{:button-motion}, @var{:motion-notify} events are only
received when at least one button is pressed. If
@var{:pointer-motion-hint} is also selected, the server is free to
send only one @var{:motion-notify}, until either the key or button
state changes, the pointer leaves the event window, or the client
calls @var{query-pointer} or @var{motion-events}.

@table @var
@item hint-p
Type @var{boolean}.

True if the event is a hint generated by selecting @var{:pointer-motion-hint}.
@end table

@end deftp



@deftp {Event Type} :enter-notify
@deftpx {Event Type} :leave-notify
@anchor{:enter-notify}

Selected by: @var{:enter-window} or @var{:leave-window}.

If pointer motion or a window hierarchy change causes the pointer to
be in a different window than before, @var{:enter-notify} and
@var{:leave-notify} events are generated instead of a
@var{:motion-notify} event. All @var{:enter-notify} and
@var{:leave-notify} events caused by a hierarchy change are
generated after any hierarchy event (@var{:unmap-notify},
@var{:map-notify}, @var{:configure-notify},
@var{:gravity-notify}, or @var{:circulate-notify}) caused by that
change, but the ordering of @var{:enter-notify} and
@var{:leave-notify} events with respect to @var{:focus-out},
@var{:visibility-notify}, and @var{:exposure} events is not
constrained by the X protocol. An @var{:enter-notify} or
@var{:leave-notify} event can also be generated when a client
application calls @var{change-active-pointer-grab},
@var{grab-pointer}, or @var{ungrab-pointer}.

@table @var
@item window
@itemx event-window
Type @var{window}.

The window receiving the event.

@item x
Type @var{int16}.

The final pointer position. If @emph{event-window} is on the same screen as root, then @emph{x}
and @emph{y} are the pointer coordinates relative to the @emph{event-window}; otherwise @emph{x} and
@emph{y} are zero.

@item y
Type @var{int16}.

The final pointer position. If @emph{event-window} is on the same screen as root, then @emph{x}
and @emph{y} are the pointer coordinates relative to the @emph{event-window}; otherwise @emph{x} and
@emph{y} are zero.

@item mode
Type (@var{member :normal :grab :ungrab}).

Events caused when the pointer is actively grabbed have mode @var{:grab}. Events
caused when an active pointer grab deactivates have mode @var{:ungrab}. In all
other cases, mode is @var{:normal}.

@item kind
Type (@var{member :ancestor :virtual :inferior :nonlinear} @var{:nonlinear-virtual}).

When the pointer moves from window A to window B, and A is an inferior of
B:
@itemize @bullet

@item
@var{:leave-notify} with @emph{kind} @var{:ancestor} is generated on A

@item
@var{:leave-notify} with @emph{kind} @var{:virtual} is generated on each window between A
and B exclusive (in that order)

@item
@var{:enter-notify} with @emph{kind} @var{:inferior} is generated on B
@end itemize

When the pointer moves from window A to window B, and
B is an inferior of A:
@itemize @bullet

@item
@var{:leave-notify} with @emph{kind} @var{:inferior} is generated on A

@item
@var{:enter-notify} with @emph{kind}
@var{:virtual} is generated on each window between
A and B exclusive (in that order)

@item
@var{:enter-notify} with @emph{kind} @var{:ancestor} is generated on B
@end itemize

When the pointer moves from window A to window B, with
window C being their least common ancestor:
@itemize @bullet

@item
@var{:leave-notify} with @emph{kind} @var{:nonlinear} is generated on A

@item
@var{:leave-notify} with @emph{kind}
@var{:nonlinear-virtual} is generated on each
window between A and C exclusive (in that order)

@item
@var{:enter-notify} with @emph{kind}
@var{:nonlinear-virtual} is generated on each
window between C and B exclusive (in that order)

@item
@var{:enter-notify} with @emph{kind}
@var{:nonlinear} is generated on B
@end itemize

When the pointer moves from window A to window B, on different screens:
@itemize @bullet

@item
@var{:leave-notify} with @emph{kind} @var{:nonlinear} is generated on A

@item
If A is not a root window, @var{:leave-notify} with @emph{kind} @var{:nonlinear-virtual} is
generated on each window above A up to and including its root (in order)

@item
If B is not a root window, @var{:enter-notify} with
@emph{kind} @var{:nonlinear-virtual} is generated
on each window from B's root down to but not
including B (in order)

@item
@var{:enter-notify} with @emph{kind} @var{:nonlinear} is generated on B
@end itemize

When a pointer grab activates (but after any initial warp into a
confine-to window, and before generating any actual
@var{:button-press} event that activates the grab), with
@emph{G} the @var{grab-window} for the grab and @emph{P} the
window the pointer is in, then @var{:enter-notify} and
@var{:leave-notify} events with mode @var{:grab} are generated
(as for @var{:normal} above) as if the pointer were to suddenly
warp from its current position in @emph{P} to some position in
@emph{G}. However, the pointer does not warp, and the pointer
position is used as both the @emph{initial} and @emph{final}
positions for the events.

When a pointer grab deactivates (but after generating any actual
@var{:button-release} event that deactivates the grab), with
@emph{G} the @var{grab-window} for the grab and @emph{P} the
window the pointer is in, then @var{:enter-notify} and
@var{:leave-notify} events with mode @var{:ungrab} are
generated (as for @var{:normal} above) as if the pointer were
to suddenly warp from from some position in @emph{G} to its
current position in @emph{P}.  However, the pointer does not
warp, and the current pointer position is used as both the
@emph{initial} and @emph{final} positions for the events.

@item focus-p
Type @var{boolean}.

If @emph{event-window} is the focus window or an inferior of the focus window, then
@emph{focus-p} is @var{t}; otherwise, @emph{focus-p} is @var{nil}.

@item state
Type @var{card16}.

A mask that gives the state of the buttons and modifier keys just before the
event.

@item time
Type @var{card32}.

A timestamp for the moment when the event occurred.

@item root
Type @var{window}.

The root window containing the final pointer position.

@item root-x
Type @var{int16}.

The x coordinate of the pointer position relative to root at the time of the event.

@item root-y
Type @var{int16}.

The y coordinate of the pointer position relative to root at the time of the event.

@item child
Type (@var{or null window}).

In a @var{:leave-notify} event, if a child of the @emph{event-window} contains the initial
position of the pointer, the @emph{child} slot is set to that child; otherwise, the @emph{child} slot is
@var{nil}. For an @var{:enter-notify} event, if a child of the @emph{event-window} contains the final
pointer position, the @emph{child} slot is set to that child; otherwise, the @emph{child} slot is @var{nil}.

@item same-screen-p
Type @var{boolean}.

True if @emph{event-window} and root are on the same screen.
@end table

@end deftp


@node Input Focus Events, Keyboard and Pointer State Events, Keyboard and Pointer Events, Event Types
@subsection Input Focus Events


The input focus events are @var{:focus-in} and @var{:focus-out}.

@deftp {Event Type} :focus-in
@deftpx {Event Type} :focus-out

Selected by: @var{:focus-change}.

@var{:focus-in} and @var{:focus-out} events are generated when the
input focus changes. All @var{:focus-out} events caused by a window
@var{:unmap} are generated after any @var{:unmap-notify} event,
but the ordering of @var{:focus-out} with respect to generated
@var{:enter-notify}, @var{:leave-notify},
@var{:visibility-notify}, and @var{:expose} events is not
constrained.

@table @var
@item window
@itemx event-window
Type @var{window}.

For @var{:focus-in}, the new input focus window. For @var{:focus-out}, the previous input
focus window.

@item mode
Type @code{(member :normal :while-grabbed :grab :ungrab)}.

Events generated by @var{set-input-focus} when the keyboard is not grabbed have
mode @var{:normal}. Events generated by @var{set-input-focus} when the keyboard is
grabbed have mode @var{:while-grabbed}. Events generated when a keyboard grab
activates have mode @var{:grab}, and events generated when a keyboard grab
deactivates have mode @var{:ungrab}.

@item kind
Type (@var{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:
@itemize @bullet

@item
@var{:focus-out} with @emph{kind} @var{:ancestor} is
generated on A

@item
@var{:focus-out} with @emph{kind} @var{:virtual} is
generated on each window between A and B exclusive (in that
order)

@item
@var{:focus-in} with @emph{kind} @var{:inferior} is
generated on B

@item
If P is an inferior of B, but P is not A or an inferior of
A or an ancestor of A, @var{:focus-in} with @emph{kind}
@var{:pointer} is generated on each window below B down
to and including P (in order)
@end itemize

When the focus moves from window A to window B, and B is an inferior of A,
with the pointer in window P:
@itemize @bullet

@item
If P is an inferior of A, but P is not A or an inferior of
B or an ancestor of B, @var{:focus-out} with @emph{kind}
@var{:pointer} is generated on each window from P up to
but not including A (in order)

@item
@var{:focus-out} with @emph{kind} @var{:inferior} is
generated on A

@item
@var{:focus-in} with @emph{kind} @var{:virtual} is
generated on each window between A and B exclusive (in
that order)

@item
@var{:focus-in} with @emph{kind} @var{:ancestor} is
generated on B
@end itemize

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:
@itemize @bullet

@item
If P is an inferior of A, @var{:focus-out} with
@emph{kind} @var{:pointer} is generated on each window
from P up to but not including A (in order)

@item
@var{:focus-out} with @emph{kind} @var{:nonlinear} is
generated on A

@item
@var{:focus-out} with @emph{kind}
@var{:nonlinear-virtual} is generated on each window
between A and C exclusive (in that order)

@item
@var{:focus-in} with @emph{kind}
@var{:nonlinear-virtual} is generated on each window
between C and B exclusive (in that order)

@item
:focus-in with @emph{kind} @var{:nonlinear} is generated
on B

@item
If P is an inferior of B, @var{:focus-in} with
@emph{kind} @var{:pointer} is generated on each window
below B down to and including P (in order)
@end itemize

When the focus moves from window A to window B, on different
screens, with the pointer in window P:
@itemize @bullet

@item
If P is an inferior of A, @var{:focus-out} with
@emph{kind} @var{:pointer} is generated on each window
from P up to but not including A (in order)

@item
@var{:focus-out} with @emph{kind} @var{:nonlinear} is
generated on A

@item
If A is not a root window, @var{:focus-out} with
@emph{kind} @var{:nonlinear-virtual} is generated on each
window above A up to and including its root (in order)

@item
If B is not a root window, @var{:focus-in} with
@emph{kind} @var{:nonlinear-virtual} is generated on each
window from B's root down to but not including B (in
order)

@item
@var{:focus-in} with @emph{kind} @var{:nonlinear} is
generated on B

@item
If P is an inferior of B, @var{:focus-in} with
@emph{kind} @var{:pointer} is generated on each window
below B down to and including P (in order)
@end itemize

When the focus moves from window A to @var{:pointer-root}
(or @var{:none}), with the pointer in window P:
@itemize @bullet

@item
If P is an inferior of A, @var{:focus-out} with
@emph{kind} @var{:pointer} is generated on each window
from P up to but not including A (in order)

@item
@var{:focus-out} with @emph{kind} @var{:nonlinear} is
generated on A

@item
If A is not a root window, @var{:focus-out} with
@emph{kind} @var{:nonlinear-virtual} is generated on each
window above A up to and including its root (in order)

@item
@var{:focus-in} with @emph{kind} @var{:pointer-root} (or
@var{:none}) is generated on all root windows

@item
If the new focus is @var{:pointer-root}, @var{:focus-in}
with @emph{kind} @var{:pointer} is generated on each
window from P's root down to and including P (in order)
@end itemize

When the focus moves from @var{:pointer-root} (or
@var{:none}) to window A, with the pointer in window P:
@itemize @bullet

@item
If the old focus is @var{:pointer-root},
@var{:focus-out} with @emph{kind} @var{:pointer} is
generated on each window from P up to and including P's
root (in order)

@item
@var{:focus-out} with @emph{kind} @var{:pointer-root}
(or @var{:none}) is generated on all root windows

@item
If A is not a root window, @var{:focus-in} with
@emph{kind} @var{:nonlinear-virtual} is generated on each
window from A's root down to but not including A (in
order)

@item
@var{:focus-in} with @emph{kind} @var{:nonlinear} is
generated on A

@item
If P is an inferior of A, @var{:focus-in} with
@emph{kind} @var{:pointer} is generated on each window
below A down to and including P (in order)
@end itemize

When the focus moves from @var{:pointer-root} to
@var{:none} (or vice versa), with the pointer in window P:
@itemize @bullet

@item
If the old focus is @var{:pointer-root},
@var{:focus-out} with @emph{kind} @var{:pointer} is
generated on each window from P up to and including P's
root (in order)

@item
@var{:focus-out} with @emph{kind} @var{:pointer-root}
(or @var{:none}) is generated on all root windows

@item
@var{:focus-in} with @emph{kind} @var{:none} (or
@var{:pointer-root}) is generated on all root windows

@item
If the new focus is @var{:pointer-root}, @var{:focus-in}
with @emph{kind} @var{:pointer} is generated on each
window from P's root down to and including P (in order)
@end itemize
@end table


When a keyboard grab activates (but before generating any actual
@var{:key-press} event that activates the grab), with @emph{G}
the @var{grab-window} for the grab and @emph{F} the current
focus, then @var{:focus-in} and @var{:focus-out} events with
mode @var{:grab} are generated (as for @var{:normal} above) as
if the focus were to change from @emph{F} to @emph{G}.

When a keyboard grab deactivates (but after generating any
actual @var{:key-release} event that deactivates the grab),
with @emph{G} the @var{grab-window} for the grab and @emph{F}
the current focus, then @var{:focus-in} and @var{:focus-out}
events with mode @var{:ungrab} are generated (as for
@var{:normal} above) as if the focus were to change from
@emph{G} to @emph{F}.
@end deftp

@node Keyboard and Pointer State Events, Exposure Events, Input Focus Events, Event Types
@subsection Keyboard and Pointer State Events


The keyboard and pointer state events are @var{:keymap-notify} and @var{:mapping-notify}.

@deftp {Event Type} :keymap-notify


Selected by: @var{:keymap-state}.

The @var{:keymap-notify} event returns the current state of the
keyboard. @var{:keymap-notify} is generated immediately after every
@var{:enter-notify} and @var{:focus-in}.

@table @var
@item window
@itemx event-window
Type @var{window}.

The window receiving an @var{:enter-notify} or @var{:focus-in} event.

@item keymap
Type (@var{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 @emph{n} from 0 to 7, byte @emph{n} (from 0) contains the bits for keys 8@emph{n} to
8@emph{n}+7, with the least significant bit in the byte representing key 8@emph{n}.
@end table

@end deftp


@deftp {Event Type} :mapping-notify

The X server reports @var{: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:
@itemize @bullet

@item
@var{set-modifier-mapping} to indicate which keycodes to use as
modifiers (the status reply must be @var{:mapping-success})

@item
@var{change-keyboard-mapping} to change the keyboard mapping

@item
@var{set-pointer-mapping} to set the pointer mapping (the status
reply must be @var{:mapping-success})
@end itemize

@table @var
@item request
Type (@code{member :modifier :keyboard :pointer}).

Indicates the kind of change that occurred--@var{:modifier} for a successful
@var{set-modifier-mapping}, @var{:keyboard} for a successful @var{change-keyboard-mapping},
and @var{:pointer} for a successful @var{set-pointer-mapping}.

@item start
Type @var{card8}.

If request is @var{:keyboard}, then @emph{start} and @emph{count} indicate the range of altered
keycodes.

@item count
Type @var{card8}.

If request is @var{:keyboard}, then @emph{start} and @emph{count} indicate the range of altered
keycodes.
@end table
@end deftp


@node Exposure Events, Window State Events, Keyboard and Pointer State Events, Event Types
@subsection 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.

@deftp {Event Type} :exposure
@anchor{:exposure}

Selected by: @var{:exposure}.

An @var{: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:
@itemize @bullet

@item
A region is exposed for a window and the X server has no backing
store for the region

@item
A region of a viewable window is obscured and the X server
begins to honor the window's backing-store attribute of
@var{:always} or @var{:when-mapped}

@item
The X server begins to honor an unviewable window's
backing-store attribute of @var{:always} or
@var{:when-mapped}.
@end itemize

The regions needing redisplay are decomposed into an arbitrary set
of rectangles, and an @var{:exposure} event is generated for each
rectangle. For a given action causing @var{:exposure} events, the
set of events for a given window are guaranteed to be reported
contiguously.

@var{:exposure} events are never generated for @var{:input-only}
windows.

All @var{:exposure} events caused by a hierarchy change are
generated after any hierarchy event (@var{:unmap-notify},
@var{:map-notify},
@var{:configure-notify},@var{:gravity-notify}, or
@var{:circulate-notify}) caused by that change. All
@var{:exposure} events on a given window are generated after any
@var{:visibility-notify} event on that window, but it is not
required that all @var{:exposure} events on all windows be
generated after all visibility events on all windows. The ordering
of @var{:exposure} events with respect to @var{:focus-out},
@var{:enter-notify}, and @var{:leave-notify} events is not
constrained.

@table @var
@item window
@itemx event-window
Type @var{window}.

The window needing redisplay.

@item x
Type @var{card16}.

The position of the left edge of the region to redisplay, relative to the
@emph{event-window}.

@item y
Type @var{card16}.

The position of the top edge of the region to redisplay, relative to the
@emph{event-window}.

@item width
Type @var{card16}.

The width of the region to redisplay.

@item height
Type @var{card16}.

The height of the region to redisplay.

@item count
Type @var{card16}.

If count is zero, then no more @var{:exposure} events for this window follow. If
count is nonzero, then at least that many more @var{:exposure} events for this
window follow (and possibly more).
@end table

@end deftp


@deftp {Event Type} :graphics-exposure

A @var{:graphics-exposure} event is generated by a call to
@var{copy-area} or @var{copy-plane} when the exposures attribute
of the graphics context is @var{:on}. A @var{: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 @var{:graphics-exposure} events, the set of events for a
given destination are guaranteed to be reported contiguously.

@table @var
@item drawable
@itemx event-window
Type @var{drawable}.

The destination drawable for the @var{copy-area} or @var{copy-plane} function.

@item x
Type @var{card16}.

The position of the left edge of the destination region, relative to the @emph{drawable}.

@item y
Type @var{card16}.

The position of the top edge of the destination region, relative to the @emph{drawable}.

@item width
Type @var{card16}.

The width of the destination region.

@item height
Type @var{card16}.

The height of the destination region.

@item count
Type @var{card16}.

If count is zero then no more @var{:graphics-exposure} events for the @emph{drawable}
follow. If count is nonzero then at least that many more @var{:graphics-exposure}
events for the @emph{drawable} follow (and possibly more).

@item major
Type @var{card8}.

The major opcode for the graphics request generating the event
(62 for @var{copy-area}, 63 for @var{copy-plane}).

@item minor
Type @var{card16}.

The minor opcode for the graphics request generating the event
(0 for both @var{copy-area} and @var{copy-plane}).
@end table

@end deftp


@deftp {Event Type} :no-exposure

A @var{:no-exposure} event is generated by a call to
@var{copy-area} or @var{copy-plane} when the exposures attribute
of the graphics context is @var{:on}. If no
@var{:graphics-exposure} events are generated, then a single
@var{:no-exposure} event is sent.

@table @var
@item drawable
@itemx event-window
Type @var{drawable}.

The destination drawable for the @var{copy-area} or @var{copy-plane} function.

@item major
Type @var{card8}.

The major opcode for the graphics request generating the event
(62 for @var{copy-area}, 63 for @var{copy-plane}).

@item minor
Type @var{card16}.

The minor opcode for the graphics request generating the event
(0 for both @var{copy-area} and @var{copy-plane}).
@end table

@end deftp


@node Window State Events, Structure Control Events, Exposure Events, Event Types
@subsection Window State Events


The following paragraphs describe the events that can be received when a
window becomes:
@itemize @bullet

@item  Created

@item  Destroyed

@item  Invisible

@item  Mapped

@item  Moved

@item  Reparented

@item  Resized

@item  Restacked

@item  Unmapped

@item  Visible
@end itemize

@deftp {Event Type} :circulate-notify

Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.

A @var{:circulate-notify} event is generated whenever a window is
actually restacked as a result of a client application calling
@var{circulate-window-up} or @var{circulate-window-down}.

@table @var
@item event-window
Type @var{window}.

The window receiving the event.

@item window
Type @var{window}.

The window that was restacked.

@item place
Type (@var{member :top :bottom}).

If place is @var{:top}, the @emph{window} is now on top of all siblings. Otherwise, it is below
all siblings.
@end table

@end deftp


@deftp {Event Type} :configure-notify

Selected by: @var{:structure-notify} on a window or
@var{:substructure-notify} on its parent.


The @var{:configure-notify} event is generated when the position or
size of a window actually changes as a result of a client
application setting its @emph{x}, @emph{y}, @emph{width},
@emph{height}, or @emph{border-width} attributes.

@table @var
@item event-window
Type @var{window}.

The window receiving the event.

@item window
Type @var{window}.

The window that was moved or resized.

@item x
Type @var{int16}.

@emph{x} and @emph{y} specify the new upper-left corner position of the @emph{window} relative to its
parent.

@item y
Type @var{int16}.

@emph{x} and @emph{y} specify the new upper-left corner position of the @emph{window} relative to its
parent.

@item width
Type @var{card16}.

@emph{width} and @emph{height} specify the new size of the @emph{window} interior.

@item height
Type @var{card16}.

@emph{width} and @emph{height} specify the new size of the @emph{window} interior.

@item border-width
Type @var{card16}.

The new @emph{window} border width.

@item above-sibling
Type (@var{or null window}).

The sibling immediately below the @emph{window}. If above-sibling is @var{nil}, then the
@emph{window} is below all of its siblings.

@item override-redirect-p
Type @var{boolean}.

@emph{override-redirect-p} is true if the override-redirect attribute of the @emph{window} is
@var{:on}; otherwise, it is @var{nil}. See @var{window-override-redirect} in @ref{Window Attributes}.
@end table


The X server can report @var{: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 @var{create-window}.

To receive this event type in a client application, you @code{setf}
the @var{:substructure-notify} as the event-mask in the parent
window's event-mask slot.

@end deftp


@deftp {Event Type} :create-notify

Selected by: @var{:substructure-notify}.


The @var{:create-notify} event is generated when a @emph{window} is
created and is sent to the @emph{parent} window.

@table @var
@item parent
@itemx event-window
Type @var{window}.

The parent window receiving the event.

@item window
Type @var{window}.

The new window created.

@item x
Type @var{int16}.

@emph{x} and @emph{y} specify the initial upper-left corner position of the @emph{window} relative to
the parent.

@item y
Type @var{int16}.

@emph{x} and @emph{y} specify the initial upper-left corner position of the @emph{window} relative to
the parent.

@item width
Type @var{card16}.

@emph{width} and @emph{height} specify the initial size of the @emph{window} interior.

@item height
Type @var{card16}.

@emph{width} and @emph{height} specify the initial size of the @emph{window} interior.

@item border-width
Type @var{card16}.

The initial @emph{window} border width.

@item override-redirect-p
Type @var{boolean}.

@emph{override-redirect-p} is true if the override-redirect attribute of the @emph{window} is
@var{:on}; otherwise, it is @var{nil}. See @var{window-override-redirect} in @ref{Window Attributes}.

@end table

@end deftp


@deftp {Event Type} :destroy-notify

Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.

The @var{:destroy-notify} event is generated when a @emph{window}
is destroyed. The ordering of the @var{:destroy-notify} events is
such that for any given window, @var{:destroy-notify} is generated
on all inferiors of a window before @var{:destroy-notify} is
generated on the @emph{window}. The ordering among siblings and
across subhierarchies is not otherwise constrained.

@table @var
@item event-window
Type @var{window}.

The window receiving the event.

@item window
Type @var{window}.

The window that was destroyed.
@end table

@end deftp


@deftp {Event Type} :gravity-notify

Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.

The X server can report @var{:gravity-notify} events to clients
wanting information about when a @emph{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 @var{with-state} with the
appropriate arguments set.

@table @var
@item event-window
Type @var{window}.

The window receiving the event.

@item window
Type @var{window}.

The window that was moved.

@item x
Type @var{int16}.

x and y specify the new upper-left corner position of the @emph{window} relative to its
parent.

@item y
Type @var{int16}.

x and y specify the new upper-left corner position of the @emph{window} relative to its
parent.
@end table

@end deftp


@deftp {Event Type} :map-notify

Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.

The X server can report @var{: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
@emph{window}'s state from unmapped to mapped by calling
@var{map-window} or @var{map-subwindow}.

To receive this event type, you @var{setf :structure-notify} as the
event-mask on the @emph{window}'s @var{event-mask} slot. You can
also receive this event type by @code{setf}ing the
@var{:substructure-notify} event-mask on the parent window.

@table @var
@item event-window
Type @var{window}.

The window receiving the event.

@item window
Type @var{window}.

The window that was mapped.

@item override-redirect-p
Type @var{boolean}.

@emph{override-redirect-p} is true if the override-redirect attribute of the @emph{window} is
@var{:on}; otherwise, it is @var{nil}. See @var{window-override-redirect} in @ref{Window Attributes}.
@end table

@end deftp


@deftp {Event Type} :reparent-notify
Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its old or new parent.

The @var{:reparent-notify} event is generated when a @emph{window}
is reparented.

@table @var
@item event-window
Type @var{window}.

The window receiving the event.

@item window
Type @var{window}.

The window that was reparented.

@item parent
Type @var{window}.

The new parent of the @emph{window}.

@item x
Type @var{int16}.

x and y specify the upper-left corner position of the @emph{window} relative to its new
@emph{parent}.

@item y
Type @var{int16}.

x and y specify the upper-left corner position of the @emph{window} relative to its new
@emph{parent}.

@item override-redirect-p
Type @var{boolean}.

@emph{override-redirect-p} is true if the override-redirect attribute
of the @emph{window} is @var{:on}; otherwise, it is @var{nil}. See
@var{window-override-redirect} in @ref{Window Attributes}.
@end table

@end deftp


@deftp {Event Type} :unmap-notify

Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.

The @var{:unmap-notify} event is generated when a mapped
@emph{window} is unmapped.

@table @var
@item event-window
Type @var{window}.

The window receiving the event.

@item window
Type @var{window}.

The window that was unmapped.

@item configure-p
Type @var{boolean}.

@emph{configure-p} is true if the @emph{window} has a win-gravity
attribute of @var{:unmap}, and the event was generated because
@emph{window}'s parent was resized.
@end table

@end deftp


@deftp {Event Type} :visibility-notify

Selected by: @var{:visibility-change}.

The @var{:visibility-notify} event is sent when the visibility of a
@emph{window} changes.  @var{:visibility-notify} events are never
generated on @var{:input-only} windows. For the purposes of this
event, the visibility of the @emph{window} is not affected by its
subwindows.

All @var{:visibility-notify} events caused by a hierarchy change
are generated after any hierarchy event caused by that change (for
example, @var{:unmap-notify}, @var{:map-notify},
@var{:configure-notify}, @var{:gravity-notify}, or
@var{:circulate-notify}). Any @var{:visibility-notify} event on a
given window is generated before any @var{:exposure} events on that
window, but it is not required that all @var{:visibility-notify}
events on all windows be generated before all @var{:exposure}
events on all windows. The ordering of @var{:visibility-notify}
events with respect to @var{:focus-out}, @var{:enter-notify}, and
@var{:leave-notify} events is not constrained.

@table @var
@item window
@itemx event-window
Type @var{window}.

The window that changed in visibility.

@item state
Type (@var{member :unobscured :partially-obscured} @var{:fully-obscured}).

When the @emph{window} was either unviewable or it was viewable and at least
partially obscured, and the @emph{window} changed to viewable and completely
unobscured, then @emph{state} is @var{:unobscured}.

When the @emph{window} was either unviewable or it was viewable and completely
obscured, and the @emph{window} changed to viewable and partially obscured, then
@emph{state} is @var{:partially-obscured}.

When the @emph{window} was either unviewable or it was at least partially visible, and
the @emph{window} changed to viewable and completely obscured, then @emph{state} is
@var{:fully-obscured}.
@end table

@end deftp


@node Structure Control Events, Client Communications Events, Window State Events, Event Types
@subsection Structure Control Events


The following paragraphs describe events used to @emph{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 @var{:on}, then no requests are redirected
and no structure control events are generated.

@deftp {Event Type} :circulate-request

The @var{:circulate-request} event is generated when a client
application calls @var{circulate-window-up} or
@var{circulate-window-down} with a window that has the
override-redirect attribute @var{:off}. The @emph{window} argument
specifies the window to be restacked, and @emph{place} specifies
what the new position in the stacking order should be (either
@var{:top} or @var{:bottom}).

Selected by: @var{:substructure-redirect} on @emph{parent}.

@table @var
@item parent
@itemx event-window
Type @var{window}.

The window receiving the event. The receiving client must have selected
@var{:substructure-redirect} on this window.

@item window
Type @var{window}.

The window to be restacked.

@item place
Type @code{(member :top :bottom)}.

The new stacking priority requested for @emph{window}.
@end table

@end deftp


@deftp {Event Type} :colormap-notify
Selected by: @var{:colormap-change}.

The @var{:colormap-notify} event is generated with @emph{new-p}
@var{t} when the @emph{colormap} associated with a @emph{window} is
changed, installed, or uninstalled.

@table @var
@item window
@itemx event-window
Type @var{window}.

The window receiving the event.

@item colormap
Type @code{(or null colormap)}.

The colormap attribute of the window.

@item new-p
Type @var{boolean}.

If @emph{new-p} is true, then the @emph{window}'s colormap attribute has changed to the given
@emph{colormap}. Otherwise, the @emph{window}'s colormap attribute has not, but the
@emph{colormap} has been installed or uninstalled.

@item installed-p
Type @var{boolean}.

If @emph{installed-p} is true, then the @emph{colormap} is currently installed.
@end table

@end deftp


@deftp {Event Type} :configure-request

Selected by:@var{:substructure-redirect} on parent.

The @var{:configure-request} event is generated when a client
program sets the @emph{x}, @emph{y}, @emph{width}, @emph{heigh}t,
@emph{border-width} or stacking priority attributes of a window that
has the override-redirect attribute @var{:off}.

@table @var
@item parent
@itemx event-window
Type @var{window}.

The window receiving the event. The receiving client must have selected
@var{:substructure-redirect} on this window.

@item window
Type @var{window}.

The window to be reconfigured.

@item x
Type @var{int16}.

@emph{x} and @emph{y} specify the requested upper-left corner position of the @emph{window} relative
to the parent. If either @emph{x} or @emph{y} is not specified in the value-mask, then it is set to
the current window position.

@item y
Type @var{int16}.

@emph{x} and @emph{y} specify the requested upper-left corner position of the @emph{window} relative
to the @emph{parent}. If either @emph{x} or @emph{y} is not specified in the @emph{value-mask}, then it is set to
the current window position.

@item width
@itemx height
Type @var{card16}.

@emph{width} and @emph{height} specify the requested size of the @emph{window} interior. If either
@emph{width} or @emph{height} is not specified in the @emph{value-mask}, then it is set to the current
window size.

@item border-width
Type @var{card16}

The requested @emph{window} border width. If @emph{border-width} is not specified in the
@emph{value-mask}, then it is set to the current window @emph{border-width}.

@item stack-mode
Type @code{(member :above :below :top-if :bottom-if :opposite)}.

@emph{stack-mode} and @emph{above-sibling} specify the requested stacking priority of the
@emph{window}. If @emph{stack-mode} is not specified in the @emph{value-mask}, then it is set to
@var{:above}.

@item above-sibling
Type (@var{or null window}).

@emph{stack-mode} and @emph{above-sibling} specify the requested stacking priority of the
@emph{window}. If @emph{above-sibling} is not specified in the @emph{value-mask}, then it is set to @var{nil}.

@item value-mask
Type @var{mask16}.

Specifies the changed @emph{window} attributes contained in the redirected client
request. Each 1 bit specifies that the corresponding attribute was changed.
@end table

@end deftp


@deftp {Event Type} :map-request

Selected by: @var{:substructure-redirect} on parent.

The @var{:map-request} event is generated when a client application
maps a @emph{window} that has the override-redirect attribute
@var{:off}.

@table @var
@item parent
@itemx event-window
Type @var{window}.

The window receiving the event. The receiving client must have selected
@var{:substructure-redirect} on this window.

@item window
Type @var{window}.

The window to be mapped.
@end table

@end deftp


@deftp {Event Type} :resize-request

Selected by: @var{:resize-redirect}.

The @var{:resize-request} event is generated when a client program
sets the @emph{width} or @emph{height} attributes of a @emph{window}
that has the override-redirect attribute @var{:off}.

@table @var
@item window
@itemx event-window
Type @var{window}.

The window to be resized.

@item width
@itemx height
Type @var{card16}.

@emph{width} and @emph{height} specify the requested size of the wi@emph{ndow} interior. If either
@emph{width} or @emph{height} was unchanged in the client request, then it is set to the current
window size.
@end table

@end deftp


@node Client Communications Events, Declaring Event Types, Structure Control Events, Event Types
@subsection Client Communications Events


The client communications events discussed in the following paragraphs
are: @var{:client-message}, @var{:property-notify},
@var{:selection-clear}, @var{:selection-request}, and
@var{:selection-notify}.

@deftp {Event Type} :client-message

The @var{:client-message} event is generated exclusively by client
calls to @var{send-event}. The X server places no interpretation on
the @emph{type} or content of @emph{data} sent in a
@var{:client-message}. A client can neither select
@var{:client-message} events nor avoid receiving them.

@table @var
@item window
@itemx event-window
Type @var{window}.

The window receiving the event.

@item type
Type @var{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.

@item format
Type (@var{member 8 16 32}).

An integer that specifies whether @emph{data} should be viewed as a sequence of 8-bit,
16-bit, or 32-bit quantities.

@item data
Type @code{(sequence integer)}.

The data content of the client message. @emph{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.
@end table

@end deftp


@deftp {Event Type} :property-notify
Selected by: @var{:property-change}.

The @var{:property-notify} event is generated when a window
property is changed or deleted.

@table @var
@item window
@itemx event-window
Type @var{window}.

The window receiving the event.

@item atom
Type @var{keyword}.

The property that was changed or deleted.

@item state
Type @code{(member :new-value :deleted)}.

@emph{state} is @var{:new-value} if the property was changed using @var{change-property} or
@var{rotate-properties}, even if zero-length data was added or if all or part of the
property was replaced with identical data. @emph{state} is @var{:deleted} if the property was
deleted using @var{delete-property} or @var{get-property}.

@item time
Type @var{timestamp}.

The server time when the property was changed or deleted.
@end table

@end deftp


@deftp {Event Type} :selection-clear

The @var{:selection-clear} event is reported to the previous owner
of a @emph{selection} when the owner of the @emph{selection} is
changed. The selection owner is changed by a client using
@code{setf}.  A client can neither select @var{:selection-clear}
events nor avoid receiving them.
@table @var
@item window
@itemx event-window
Type @var{window}.

The window losing ownership of the @emph{selection}.

@item selection
Type @var{keyword}.

The name of the selection.

@item time
Type @var{timestamp}.

The last-change time recorded for the @emph{selection}.
@end table

@end deftp

@deftp {Event Type} :selection-notify

The @var{:selection-notify} event is sent to a client calling
@var{convert-selection}.  @var{:selection-notify} reports the
result of the client request to return the current value of a
@emph{selection} into a particular form. @var{:selection-notify} is
sent using @var{send-event} by the owner of the selection or (if no
owner exists) by the X server. A client can neither select
@var{:selection-notify} events nor avoid receiving them.

@var{NOTE:} Standard conventions for inter-client communication require the following
additional steps in processing a @var{:selection-notify} event:

@enumerate

@item
The client receiving this event should call @var{get-property} to
return the converted selection value.

@item
After receiving the selection value, the property should then be
deleted (either by using the @var{:delete-p} argument to
@var{get-property} or by calling @var{delete-property}).
@end enumerate

@table @var
@item window
@itemx event-window
Type @var{window}.

The requestor window given in the call to @var{convert-selection}.

@item selection
Type @var{keyword}.

The selection to be converted.

@item target
Type @var{keyword}.

An @var{xatom} specifying the type of the converted selection value. This is the same
target type given in the call to @var{convert-selection}.

@item property
Type @code{(or null keyword)}.

The window property containing the converted selection. If the property is @var{nil},
then either the @emph{selection} has no owner or the owner could not perform the
conversion to the @emph{target} type.

@item time
Type @var{timestamp}.

The timestamp from the client call to @var{convert-selection}.
@end table

@end deftp


@deftp {Event Type} :selection-request

The @var{:selection-request} event is reported to the owner of a
selection when a client calls @var{convert-selection}. This event
requests the selection owner to convert the current value of a
@emph{selection} into a specified form and to return it to the
requestor. A client can neither select @var{:selection-request}
events nor avoid receiving them.

The selection owner should respond to a @var{:selection-request} event by performing the
following steps:

@enumerate

@item
Convert the current @emph{selection} value to the @emph{target}
type.

@item
Store the converted selection value in the @emph{property}. If
@emph{property} is @var{nil}, then the owner should choose the
@emph{property}.

@item
Call @var{send-event} to send a @var{:selection-notify} event to
the @emph{requestor} containing the @emph{property} with the
converted value. If the @emph{selection} could not be converted to
the @emph{target} type, then a @var{nil} @emph{property} should
be sent. The @var{:selection}, @var{:target}, and @var{:time}
arguments to @var{send-event} should be the same as those
received in the @var{:selection-request} event. The event-mask
argument to @var{send-event} should be @var{nil}; that is, the
@var{:selection-notify} event should be sent to client that
created the @emph{requestor}.
@end enumerate


@var{NOTE:} Standard conventions for inter-client communication
require the following additional steps in processing a
@var{:selection-request} event:

@enumerate

@item
The property used to store the selection value must belong to the
requestor.

@item
If the property is @var{nil}, the target type @var{atom} should
be used as the property name.

@item
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.
@end enumerate

@table @var
@item window
@itemx event-window
Type @var{window}.

The selection owner receiving the event.

@item requestor
Type @var{window}.

The window requesting the converted @emph{selection}.

@item selection
Type @var{keyword}.

The selection to be converted.

@item target
Type @var{keyword}.

An @var{xatom} specifying the type of the converted @emph{selection} value.

@item property
Type @code{(or null keyword)}.

A requestor window property.

@item time
Type @var{timestamp}.

The timestamp sent in the client @var{convert-selection} request.
@end table

@end deftp


@node Declaring Event Types,  , Client Communications Events, Event Types
@subsection Declaring Event Types


CLX uses the @var{declare-event} macro to define the event slot symbols
that access the contents of X events. Most client applications do not
need to use @var{declare-event} because the declarations for all core X
events are already defined by CLX.  Programmers using extensions to the
X protocol can use @var{declare-event} to allow CLX to handle new event
types returned by an extended X server.

@defmac 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 @emph{event-codes} argument gives the event type keyword for the
event described. If several event types share the same slots, then
@emph{event-codes} can be a list of event type
keywords. @emph{slot-declarations} is a list containing an element
for each event data item. The order of @emph{slot-declarations}
corresponds to the order of event data items defined by the X
protocol.

Each element of @emph{slot-declarations} is a list of the form
(@emph{type slot-name}*), where @emph{type} is a Common Lisp type
specifier and @emph{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 @emph{type} and are associated with the given
@emph{slot-name} symbols. @emph{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.

@table @var
@item event-codes
An event type keyword or a list of event type keywords.
@item slot-declarations
A list of clauses defining event slot symbols.
@end table

@end defmac


@node Releasing Queued Events,  , Event Types, Events and Input
@section 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 @var{allow-events} function to release
queued events from a frozen input device.

@defun allow-events display mode &optional time

@table @var
@item display
A @var{display}.

@item mode
One of: @var{:async-pointer}, @var{:sync-pointer},
@var{:reply-pointer}, @var{:async-keyboard}, @var{:sync-keyboard},
@var{:replay-keyboard}, @var{:async-both}, @var{:sync-both}.

@item time
A @var{timestamp}.
@end table

Releases some queued events if the client has caused a device to
freeze. The request has no effect if the @emph{time} is earlier than
the last-grab time of the most recent active grab for the client, or
if the @emph{time} is later than the current server time. If
@emph{time} is @var{nil}, the current server time is used. The
effect of this function depends on the specified @emph{mode}.
@itemize @bullet

@item
@var{: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,
@var{:async-pointer} releases events for both
grab@emph{s}. @var{:async-pointer} has no effect if the pointer
is not frozen by the client, but the pointer need not be grabbed
by the client.

@item
@var{:sync-pointer} -- If the pointer is frozen and actively
grabbed by the client, pointer event processing continues normally
until the next @var{:button-press} or @var{: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. @var{:sync-pointer} has no effect if the pointer is not
frozen by the client, or if the pointer is not grabbed by the
client.

@item
@var{: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
@var{grab-button}, or from a previous @var{allow-events} with
mode @var{:sync-pointer}, but not from a @var{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 @var{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.

@item
@var{: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,
@var{:async-keyboard} releases events for both grabs.
@var{:async-keyboard} has no effect if the keyboard is not frozen
by the client, but the keyboard need not be grabbed by the client.

@item
@var{:sync-keyboard} -- If the keyboard is frozen and actively
grabbed by the client, keyboard event processing continues
normally until the next @var{:key-press} or @var{: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. @var{:sync-keyboard} has no effect if the keyboard is not
frozen by the client, or if the keyboard is not grabbed by the
client.

@item
@var{: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 @var{allow-events} with mode
@var{:sync-keyboard}, but not from a @var{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 @var{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.

@item
@var{:sync-both} -- If both pointer and keyboard are frozen by
the client, event processing (for both devices) continues normally
until the next @var{:button-press}, @var{:button-release},
@var{:key-press}, or @var{: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. @var{: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, @var{:sync-both} @emph{thaws} for both, but a subsequent
freeze for @var{:sync-both} will only freeze each device once.

@item
@var{: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, @var{:async-both} @emph{thaws} for
both. @var{:async-both} has no effect unless both pointer and
keyboard are frozen by the client.
@end itemize

@var{:async-pointer}, @var{:sync-pointer}, and
@var{:replay-pointer} have no effect on processing of keyboard
events. @var{:async-keyboard}, @var{:sync-keyboard}, and
@var{: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.



@end defun

@node Resources, Control Functions, Events and Input, Top
@chapter 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 @emph{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.

@var{NOTE:} The general term @emph{resource} refers to any application
user interface value stored in a resource database. The term @emph{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).

@menu
* Resource Binings::
* Basic Resource Database Functions::
* Accessing Resource Values::
* Resource Database Files::
@end menu

@node Resource Binings, Basic Resource Database Functions, Resources, Resources
@section Resource Binings


Conceptually, a resource database is a set of resource name-value pairs
(or @emph{resource bindings}). The name in a resource binding is a list
that is the concatenation of a @emph{path list} and an @emph{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:

@lisp
'(top middle bottom)
@end lisp


corresponds to a three-level hierarchy in which @code{middle} is
the child of @code{top}, and @code{bottom} is the child of
@code{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:

@lisp
'(top * bottom)
@end lisp


corresponds to a hierarchy of two or more levels in which
@code{top} is at the top level and @code{bot-}
@code{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 @code{mail} is the resource name of a mail reading
application. @code{mail} uses a window of the class
@code{button} whose name is @code{reply}.

@multitable {Resource Name} {Resource Value}
@item @code{(mail screen-1 reply background)} @tab @code{'green}
@item @code{(mail * background)} @tab @code{'red}
@item @code{(* button background)} @tab @code{'blue}
@end multitable

These resource bindings specify the following:
@itemize @bullet

@item
The @code{background} attribute resource of @code{mail}
application@emph{'}s @code{reply} button has the value of
@code{green} on @code{screen-1}.

@item
The @code{background} attribute for the rest of the
@code{mail} application is always @code{red} on all
screens.

@item
In general, the @code{background} attribute for all
@code{button} windows is @code{blue}.
@end itemize

@node Basic Resource Database Functions, Accessing Resource Values, Resource Binings, Resources
@section Basic Resource Database Functions


A @var{resource-database} structure is a CLX object that represents a
set of resource bindings. The following paragraphs describe the CLX
functions used to:
@itemize @bullet

@item  Create a resource database

@item  Add a resource binding

@item  Remove a resource binding

@item  Merge two resource databases

@item  Map a function over the contents of a resource database
@end itemize

@defun make-resource-database

@table @var
@item resource-database
Type @var{resource-database}.
@end table

Returns an empty resource database.
@end defun


@defun add-resource database name-list value

@table @var
@item database
The @var{resource-database} for the new resource binding.
@item name-list
A list containing strings or symbols specifying the name for the resource binding.
@item value
The value associated with the @emph{name-list} in the resource binding. This can be an object of any type.
@end table

Adds the resource binding specified by @emph{name-list} and
@emph{value} to the given @emph{database}. Only one value can be
associated with the @emph{name-list} in the @emph{database}. This
function replaces any value previously associated with the
@emph{name-list}.



@end defun


@defun delete-resource database name-list

@table @var
@item database
The @var{resource-database} containing the resource binding.
@item name-list
A list containing strings or symbols specifying the name for the deleted resource binding.
@end table

Removes the resource binding specified by @emph{name-list} from the given @emph{database}.



@end defun


@defun map-resource database function &rest args

@table @var
@item database
A @var{resource-database}.
@item function
A @var{function} object or function symbol.
@item args
A list of arguments to the @emph{function}.
@end table

Calls the function for each resource binding in the
@emph{database}. For each resource binding consisting of a
@emph{name-list} and a @emph{value}, the form
(@var{apply} @emph{function name-list value args})
is executed.



@end defun


@defun merge-resources from-database to-database

@table @var
@item from-database
The @var{resource-database} from which resource bindings are read.
@item to-database
The @var{resource-database} to which resource bindings are added.
@end table


Merges the contents of the @emph{from-database} with the
@emph{to-database}. @var{map-resource} invokes @var{add-resource}
in order to add each resource binding in the @emph{from-database} to
the @emph{to-database}. The updated @emph{to-database} is returned.

@table @var
@item to-database
Type @var{resource-database}.
@end table

@end defun


@node Accessing Resource Values, Resource Database Files, Basic Resource Database Functions, Resources
@section 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 @emph{complete resource
name} and a @emph{complete} @emph{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 @emph{closest match} takes into account the top-down,
parent-child hierarchy of resource names and also the distinction
between individual names and class names.

@menu
* Complete Names and Classes::
* Matching Resource Names::
* Resource Access Functions::
@end menu

@node Complete Names and Classes, Matching Resource Names, Accessing Resource Values, Accessing Resource Values
@subsection 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 @emph{complete resource name} and a
@emph{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,
@code{'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 @code{mail} application
can attempt to look up the value of the @code{background} resource
for the @code{reply button} window by using the following complete
resource name:

@lisp
(mail screen-1 reply background)
@end lisp

and the following complete resource class:

@lisp
(application root button fill)
@end lisp


This complete resource name contains a path list identifying the reply
button window -- @code{(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.

@node Matching Resource Names, Resource Access Functions, Complete Names and Classes, Accessing Resource Values
@subsection 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 @emph{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:

@multitable {Resource Name} {Resource Value}
@item @code{(mail * background)} @tab @code{'red}
@item @code{(* reply background)} @tab @code{'blue}
@end multitable


Suppose an application program searched by using the following complete
resource name:

@lisp
(mail screen-1 reply background)
@end lisp


then the closest matching value returned would be @code{'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:

@multitable {Resource Name} {Resource Value}
@item @code{(mail * background)} @tab @code{'red}
@item @code{(mail * fill)} @tab @code{'blue}
@end multitable


Suppose an application program searched by using the following complete
resource name and complete resource class:

@lisp
(mail screen-1 reply background)
(application root button fill)
@end lisp


then the closest matching value returned would be
@code{'red}. However, suppose the resource database contained the
following resource bindings:

@multitable {Resource Name} {Resource Value}
@item @code{(mail * background)} @tab @code{'red}
@item @code{(mail * button background)} @tab @code{'blue}
@end multitable


then the closest matching value returned would be @code{'blue}.

@node Resource Access Functions,  , Matching Resource Names, Accessing Resource Values
@subsection Resource Access Functions


The following paragraphs describe the CLX functions used to return a
value from a resource database.

@defun get-resource database attribute-name attribute-class path-name path-class

@table @var
@item database
A @var{resource-database}.
@item attribute-name
A string or symbol giving an attribute name from a complete resource name.
@item attribute-class
A string or symbol giving an attribute class name from a complete resource class.
@item path-name
The path list from a complete resource name. @emph{path-name} and @emph{path-class} must have the same length.
@item path-class
The path list from a complete resource class. @emph{path-name} and @emph{path-class} must have the same length.
@end table


Returns the value of the resource binding in the @emph{database}
whose resource name most closely matches the complete resource
name/class given by the @emph{path-name}, @emph{path-class},
@emph{attribute-name}, and @emph{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.

@table @var
@item value
Type @var{t}.
@end table

@end defun





@defun get-search-table database path-name path-class

@table @var
@item database
A @var{resource-database}.
@item path-name
The path list from a complete resource name. @emph{path-name} and @emph{path-class}must have the same length.
@item path-class
The path list from a complete resource class. @emph{path-name} and @emph{path-class} must have the same length.
@end table


Returns a table containing the subset of the @emph{database} that
matches the @emph{path-name} and @emph{path-class}. Resources using
the same @emph{path-name} and @emph{path-class} can be accessed much
more efficiently by using this table as an argument to
@var{get-search-resource}.

@table @var
@item search-table
Type @var{list}.
@end table

@end defun


@defun get-search-resource table attribute-name attribute-class

@table @var
@item table
A search table returned by @var{get-search-table}.
@item attribute-name
A string or symbol giving an attribute name from a complete resource name.
@item attribute-class
A string or symbol giving an attribute class name from a complete resource class.
@end table


Returns the value of the resource binding in the search @emph{table}
that most closely matches the @emph{attribute-name} and
@emph{attribute-class}. The @emph{table} is computed by
@var{get-search-table} and represents a set of resource
bindings. The closest match is determined by the same algorithm used
in @var{get-resource}.

The following two forms are functionally equivalent:

@lisp
(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)
@end lisp


However, the hard part of the search is done by
@var{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 @var{get-search-resource}.
@table @var
@item value
Type @var{t}.
@end table

@end defun

@node Resource Database Files,  , Accessing Resource Values, Resources
@section 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.

@defun read-resources database pathname &key :key :test :test-not

@table @var
@item database
The @var{resource-database} to merge.
@item pathname
A pathname for the resource file to read.
@item :key
A function used to convert a value from the resource file into a resource binding value.
@item :test
@itemx :test-not
Functions used to select which resource bindings from the resource file are merged with the @emph{database}.
@end table




Reads resource bindings from a resource file in standard X11 format
and merges them with the given resource @emph{database}. The
@var{:key} function is called to convert a file resource value into
the value stored in the @emph{database}. By default, @var{:key} is
@var{#'identity}. The @var{:test} and @var{:test-not} functions
are predicates that select resource bindings to merge, based on the
result of the @var{:key} function. For each file resource binding
consisting of a @emph{resource-name} and a @emph{resource-value},
the @var{:test} (or @var{:test-not}) function is called with the
arguments @emph{resource-name} and (@var{funcall} @emph{key
resource-value}).

@table @var
@item database
Type @var{resource-database}.
@end table

@end defun


@defun write-resources database pathname &key :write :test :test-not

@table @var
@item database
The @var{resource-database} to write.
@item pathname
A pathname of the file to write.
@item :write
A function for writing resource values.
@item :test
@itemx :test-not
Functions used to select which resource bindings from the resource file are merged with the @emph{database}.
@end table

Writes resource bindings found in the @emph{database} to the file
given by the @emph{pathname}. The output file is written in the
standard X11 format. The @var{:write} function is used for writing
resource values; the default is @var{#'princ}. The @var{:write}
function is passed two arguments: a @emph{resource-value} and a
@emph{stream}. The @var{:test} and @var{:test-not} functions are
predicates which select resource bindings to write. For each
resource binding consisting of a @emph{resource-name} and a
@emph{resource-value}, the @var{:test} (or @var{:test-not})
function is called with the arguments @emph{resource-name} and
@emph{resource-value}.


@end defun


@node Control Functions, Extensions, Resources, Top
@chapter Control Functions

@menu
* Grabbing the Server::
* Pointer Control::
* Keyboard Control::
* Keyboard Encodings::
* Client Termination::
* Managing Host Access::
* Screen Saver::
@end menu

@node Grabbing the Server, Pointer Control, Control Functions, Control Functions
@section 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 @emph{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.

@defun grab-server display

@table @var
@item display
A @var{display}.
@end table

Disables processing of requests and close-downs on all connections
other than the one on which this request arrived.


@end defun

@defun ungrab-server display

@table @var
@item display
A @var{display}.
@end table

Restarts processing of requests and close-downs on other
connections.


@end defun


@defmac with-server-grabbed display &body body

Grabs the @emph{display} server only within the dynamic extent of
the @emph{body}. @var{ungrab-server} is automatically called upon
exit from the @emph{body}. This macro provides the most reliable way
for CLX clients to grab the server.

@table @var
@item display
A @var{display}.
@item body
The forms to execute while the server is grabbed.
@end table

@end defmac


@node Pointer Control, Keyboard Control, Grabbing the Server, Control Functions
@section Pointer Control


The following paragraphs describe the CLX functions used to:
@itemize @bullet

@item  Return or change the pointer acceleration and acceleration threshold

@item  Return or change the mapping of pointer button numbers
@end itemize

@defun change-pointer-control display &key :acceleration :threshold

@table @var
@item display
A @var{display}.
@item :acceleration
A number for the acceleration ratio.
@item :threshold
The number of pixels required for acceleration to take effect.
@end table

Changes the acceleration and/or the acceleration threshold of the
pointer for the @emph{display}.  The @var{:acceleration} number is
used as a multiplier, typically specified as a rational number of
the form @emph{C/P}, where @emph{C} is the number of pixel positions
of cursor motion displayed for @emph{P} units of pointer device
motion. The acceleration only occurs if the pointer moves more that
@var{:threshold} pixels at once, and only applies to the motion
beyond the @var{:threshold}. Either @var{:acceleration} or
@var{:threshold} can be set to @var{:default}, that restores the
default settings of the server.


@end defun


@defun pointer-control display

@table @var
@item display
A @var{display}.
@end table


Returns the acceleration and threshold for the @emph{display}
pointer.
@table @var
@item acceleration
@itemx threshold
Type @var{number}.
@end table

@end defun


@defun pointer-mapping display &key (:result-type 'list)

@table @var
@item display
A @var{display}.
@item :result-type
The type of sequence to return.
@end table


Returns or (with @code{setf}) changes the mapping of button numbers
for the @emph{display} pointer.  The @var{:result-type} is not used
when changing the mapping. If element @emph{i} of the mapping
sequence is @emph{j}, then the events from pointer button @emph{j}
are reported by the server as events for button @emph{i}+1. (Note
that pointer buttons are numbered beginning with one, while the
mapping sequence itself is indexed normally from zero.) If element
@emph{i} of the mapping sequence is zero, then button @emph{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.
@table @var
@item mapping
Type @var{sequence} or @var{card8}@emph{.}
@end table

@end defun


@node Keyboard Control, Keyboard Encodings, Pointer Control, Control Functions
@section Keyboard Control


The following paragraphs describe the CLX functions used to:
@itemize @bullet

@item  Return or change keyboard controls

@item  Ring the keyboard bell

@item  Return or change the mapping of modifiers

@item  Return the current up/down state of all keys
@end itemize

@defun bell display &optional (percent-from-normal 0)

@table @var
@item display
A @var{display}.
@item percent-from-normal
An integer (-100 through 100).
@end table

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:

@lisp
(- (+ @emph{base percent}) (@var{quotient} (* @emph{base percent}) 100))
@end lisp

and when percent is negative:

@lisp
(+ @emph{base} (@var{quotient} (* @emph{base percent}) 100))
@end lisp



@end defun


@defun change-keyboard-control display &key :key-click-percent :bell-percent :bell-pitch :bell-duration :led :led-mode :key :auto-repeat-mode

@table @var
@item display
A @var{display}.
@item :key-click-percent
An integer (0 100).
@item :bell-percent
An integer (0 100).
@item :bell-pitch
A @var{card16}.
@item :bell-duration
A @var{card16}.
@item :led
A @var{card8}.
@item :led-mode
Either @var{:on} or @var{:off}.
@item :key
A @var{card8} keycode.
@item :auto-repeat-mode
Either @var{:on}, @var{:off}, or @var{:default}.
@end table

Changes the various aspects of the keyboard. The keyword arguments
specify which controls to change.

The @var{: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 @var{:key-click-percent} to @var{:default}
restores the default value.

The @var{:bell-percent} sets the base volume for the bell between 0
(off) and 100 (loud) if possible. Setting @var{:bell-percent} to
@var{:default} restores the default value.

The @var{:bell-pitch} sets the pitch (specified in Hz) of the bell,
if possible. Setting the @var{:bell-pitch} to @var{:default}
restores the default value. The @var{:bell-duration} sets the
duration ( specified in milliseconds) of the bell, if
possible. Setting @var{:bell-pitch} to @var{: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 @var{:led-mode} and @var{:led} are specified, then the
state of that LED is changed, if possible. If only @var{: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 @var{:auto-repeat-mode} and @var{:key} are specified, the
auto-repeat mode of that key is changed, if possible. If only
@var{: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 @var{:key} is specified
without @var{:auto-repeat-mode}.


@end defun


@defun keyboard-control display

@table @var
@item display
A @var{display}.
@end table


Returns the current control values for the keyboard. For the LEDs,
the least significant bit of @emph{led-mask} corresponds to LED one,
and each one bit in @emph{led-mask} indicates an LED that is
lit. @emph{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 @emph{n} (from 0) contains the bits
for keys 8@emph{n} to 8@emph{n}+7, with the least significant bit in
the byte representing key 8@emph{n}.
@table @var
@item key-click-percent
@itemx bell-percent
Type @var{card8}.
@item bell-pitch
@itemx bell-duration
Type @var{card16}.
@item led-mask
Type @var{card32}.
@item global-auto-repeat
Either @var{:on} or @var{:off}.
@item auto-repeats
Type @var{bit-vector}.
@end table

@end defun


@defun modifier-mapping display

@table @var
@item display
A @var{display}.
@end table


Returns the set of keycodes used for each modifier on the
@emph{display} keyboard. Each return value is a list of the
@var{card8} keycodes used for each modifier key. The order of
keycodes within each list is server-dependent.
@table @var
@item shift-keycodes
@itemx lock-keycodes
@itemx control-keycodes
@itemx mod1-keycodes
@itemx mod2-keycodes
@itemx mod3-keycodes
@itemx mod4-keycodes
@itemx mod5-keycodes
Type @var{list} of @var{card8}.
@end table

@end defun


@defun query-keymap display

@table @var
@item display
A @var{display}.
@end table

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 @emph{n} (from
0) contains the bits for keys 8@emph{n} to 8@emph{n}+7, with the
least significant bit in the byte representing key 8@emph{n}.
@table @var
@item keymap
Type @var{bit-vector} 256.
@end table

@end defun


@defun set-modifier-mapping display &key :shift :lock :control :mod1 :mod2 :mod3 :mod4 :mod5

@table @var
@item display
A @var{display}.
@item :shift
@itemx :lock
@itemx :control
@itemx :mod1
@itemx :mod2
@itemx :mod3
@itemx :mod4
@itemx :mod5
A sequence of @var{card8} keycodes for the given modifier.
@end table


Changes the set of keycodes mapped to the specified modifier keys on
the @emph{display} keyboard. Each keyword argument contains a
sequence of new @var{card8} keycodes for a specific modifier. The
return value indicates whether the change was completed
successfully.

A status of @var{: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 @var{:failed} is returned, the mappings for all
modifiers remain unchanged.

A status of @var{: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.
@table @var
@item status
One of @var{:success}, @var{:failed}, or @var{:device-busy}.
@end table

@end defun


@node Keyboard Encodings, Client Termination, Keyboard Control, Control Functions
@section 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 (@emph{keycodes}) and for character symbols
(@emph{keysyms}). Each X server maintains a @emph{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:
@enumerate

@item
Receive a @var{:key-press} (or @var{:key-release}) event containing
a keycode.

@item
Convert the keycode into its corresponding keysym, based on the
current keyboard mapping. See @var{keycode-&gt;keysym}.

@item
Convert the keysym into the corresponding Common Lisp character. See
@var{keysym-&gt;character}.
@end enumerate

@menu
* Keycodes and Keysyms::
* Keyboard Mapping::
* Using Keycodes and Keysyms::
@end menu

@node Keycodes and Keysyms, Keyboard Mapping, Keyboard Encodings, Keyboard Encodings
@subsection Keycodes and Keysyms


A @emph{keycode} represents a physical (or logical) key. In CLX,
keycodes are values of type (@var{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 @emph{keysym} is an encoding of a symbol on the cap of a key. In CLX,
keysyms are values of type @var{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 @var{:shift}
modifier is on, or when the @var{:lock} modifier is on and @var{:lock}
is interpreted as @var{:shift-lock}. When the @var{:lock} modifier is
on and is interpreted as @var{:caps-lock}, it is suggested that the
@var{: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 @var{:caps-lock} are possible; for example, it
may be viewed as equivalent to @var{: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.

@node Keyboard Mapping, Using Keycodes and Keysyms, Keycodes and Keysyms, Keyboard Encodings
@subsection 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.

@defun change-keyboard-mapping display keysyms &key (:start 0) :end

@table @var
@item display
A @var{display}.
@item keysyms
A two-dimensional array of keysym (@var{card32}) values.
@item :start
@itemx :end
Indexes for the subsequence of @emph{keysyms} used.
@item :first-keycode
A @var{card8} defining the first keycode mapping changed.
@end table

(@var{:first-keycode :start})

Changes the mapping of keycodes to @emph{keysyms}. A
@var{:mapping-notify} event is generated for all clients.

The new @emph{keysyms} are specified as a two-dimensional array in
which:

(@var{aref} @emph{keysyms} (+ @var{:start} @emph{i}) @emph{j})

is @emph{keysym j} associated with keycode (+ @var{:first-keycode}
@emph{i}). The maximum number of @emph{keysyms} associated with any
one keycode is given by:

(@var{array-dimension} @emph{keysyms} 1)

@emph{keysyms} should contain @var{nil} elements to represent those
keysyms that are undefined for a given keycode. @var{:start} and
@var{:end} define the subsequence of the @emph{keysyms} array that
defines the new mapping, and the number of keycode mappings
changed. By default, @var{:end} is given by:

(@var{array-dimension} @emph{keysyms} 0)

The keycodes whose mappings are changed are given by
@var{:first-keycode} through the following:

(+ @var{:first-keycode} (- @var{:end :start}) -1)

keycodes outside this range of are not
affected. @var{:first-keycode} must not be less than
(@var{display-min-keycode} @emph{display}), and the last keycode
modified must not be greater than (@var{display-max-keycode}
@emph{display}).


@end defun



@defun keyboard-mapping display &key :first-keycode :start :end :data

@table @var
@item display
A @var{display}.
@item :first-keycode
A @var{card8} defining the first keycode mapping returned.
@item :start
@itemx :end
Indexes for the subsequence of the returned array which is modified.
@item :data
If given, a two-dimensional array to receive the returned keysyms.
@end table
Returns the keysyms mapped to the given range of keycodes for the
@emph{display} keyboard.  The mappings are returned in the form of a
two-dimensional array of @var{card32} keysym values. The
@var{:data} argument, if given, must be a two-dimensional array in
which the returned mappings will be stored. In this case:

(@var{array-dimension :data} 1)

defines the maximum number of keysyms returned for any
keycode. Otherwise, a new array is created and returned.

Upon return:

(@var{aref} @emph{mappings} (+ @emph{:start i}) @emph{j})

will contain keysym @emph{j} associated with keycode (+
@var{:first-keycode i}) (or @var{nil}, if keysym @emph{j} is
undefined for that keycode).

@var{:first-keycode} specifies the first keycode whose mapping is
returned; by default, @var{:first-keycode} is
(@var{display-min-keycode} @emph{display}). @var{:start} and
@var{:end} define the subsequence of the returned array in which
the returned mappings are stored. By default, @var{:start} is given
by @var{:first-keycode} and @var{:end} is given by:

(1+ (@var{display-max-keycode} @emph{display}))

@var{:first-keycode} must not be less than
(@var{display-min-keycode} @emph{display}), and the last keycode
returned must not be greater than (@var{display-max-keycode}
@emph{display}).
@table @var
@item mappings
Type (@var{array card32} (* *)).
@end table

@end defun


@node Using Keycodes and Keysyms,  , Keyboard Mapping, Keyboard Encodings
@subsection Using Keycodes and Keysyms


The following paragraphs describe the CLX functions used to:
@itemize @bullet

@item  Convert a keycode into a keysym

@item  Convert a keysym into a character
@end itemize

@defun keycode->keysym display keycode keysym-index

@table @var
@item display
A @var{display}.
@item keycode
A @var{card8}.
@item keysym-index
A @var{card8}.
@end table


Returns the @emph{keysym} at the given @emph{keysym-index} from the
keysym list for the @emph{keycode} in the current keyboard mapping
for the @emph{display} server.
@emph{This function was called keycode-keysym in X11R4 and older versions of CLX.}
@table @var
@item keysym
Type @var{keysym}.
@end table

@end defun


@defun keysym->character display keysym &optional (state 0)

@table @var
@item display
A @var{display}.
@item keysym
A @var{keysym}.
@item state
A @var{mask16}.
@end table

Returns the @emph{character} associated with the @emph{keysym} and
the @emph{state}. The @emph{state} is a @var{mask16} bit mask
representing the state of the @emph{display} modifier keys and
pointer buttons. See @var{state-mask-key} in @ref{Data Types}. If the @emph{keysym} does not represent a Common Lisp
character, then @var{nil} is returned.
@emph{This function was called keysym-character in X11R4 and older versions of CLX.}

The @emph{state} determines the bits attribute of the returned
@emph{character}, as follows:
@table @var
@item :control
@var{char-control-bit}
@item :mod-1
@var{char-meta-bit}
@item :mod-2
@var{char-super-bit}
@item :mod-3
@var{char-hyper-bit}
@end table

@c Of course *we* know that this mapping is bull shit!
@table @var
@item character
Type @var{character} or @var{null}.
@end table

@end defun


@node Client Termination, Managing Host Access, Keyboard Encodings, Control Functions
@section 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 @var{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 @emph{close-down mode} and the
@emph{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:
@enumerate

@item
For each selection owned by a window created on the connection, the
selection owner is set to @var{nil}.

@item
An active or passive grab established for a window created on the
connection is released.

@item
If the connection has grabbed the server, the server is ungrabbed.

@item
Server resources and colormap cells allocated by the connection are
freed and destroyed, depending on the close-down mode, as follows:
@itemize @bullet

@item
@var{:retain-permanent} -- All resources are marked
@emph{permanent}, and no resources are destroyed. These resources
can later be destroyed by a call to @var{kill-client}.

@item
@var{:retain-temporary} -- All resources are marked
@emph{temporary}, and no resources are destroyed. These resources
can later be destroyed by a call to @var{kill-client} or
@var{kill-temporary-clients}.

@item
@var{:destroy} -- All resources are destroyed.
@end itemize
@end enumerate

When server resources allocated by a display connection are destroyed --
whether by closing the connection with close-down mode @var{:destroy}
or by later calling @var{kill-client} or @var{kill-temporary-clients}
-- then an X server performs the following operations on each member of
the save-set before actually destroying resources.
@enumerate

@item
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.

@item
If the save-set window is unmapped, then it is mapped.
@end enumerate

If the last connection open to an X server is closed with close-down
mode @var{: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:
@itemize @bullet

@item
All permanent and temporary server resources from previously-closed
connections are destroyed.

@item
All but the predefined atoms are deleted.

@item
All root window properties are deleted.

@item
All device control attributes and mappings are restored to their
original default values.

@item
The default background and cursor for all root windows are restored.

@item
The default font path is restored.

@item
The input focus is set to @var{:pointer-root}.

@item
The access control list is reset.
@end itemize

The following paragraphs describe the CLX functions used to:
@itemize @bullet

@item
Add or remove a window from a display save-set.

@item
Return or change the display close-down mode.

@item
Force a connection to be closed or all its server resources to be
destroyed.

@item
Force a connection to be closed and all temporary resources to be
destroyed.
@end itemize

@defun add-to-save-set window

@table @var
@item window
A @var{window}.
@end table

Adds the specified @emph{window} to the save-set of the
@emph{window} display. The @emph{window} must have been created by
some other display. Windows are removed automatically from the
save-set when they are destroyed.


@end defun


@defun close-down-mode display

@table @var
@item display
A @var{display}.
@end table
Returns and (with @code{setf}) sets the close-down mode of the
client's resources at connection close.
@table @var
@item mode
One of @var{:destroy}, @var{:retain-permanent}, or @var{:retain-temporary}.
@end table

@end defun


@defun kill-client display resource-id

@table @var
@item display
A @var{display}.
@item resource-id
A valid @var{card29} resource ID.
@end table

Closes the display connection which created the given
@emph{resource-id}. The @emph{resource-id} must be valid, but need
not belong to the given @emph{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
@var{:retain-permanent} or @var{:retain-temporary}, then all its
retained server resources -- both permanent and temporary -- are
destroyed.


@end defun


@defun kill-temporary-clients display

@table @var
@item display
A @var{display}.
@end table

Closes the @emph{display} connection and destroys all retained
temporary server resources for this and all previously-terminated
connections.

If the @emph{display} connection was previously open, the connection
is closed according to its close-down mode. Otherwise, if the
@emph{display} connection had been previously terminated with
close-down mode @var{:retain-permanent} or
@var{:retain-temporary}, then all its retained server resources --
both permanent and temporary -- are destroyed.


@end defun


@defun remove-from-save-set window

@table @var
@item window
A @var{window}.
@end table

Removes the specified @emph{window} from the save-set of the
@emph{window} display. The @emph{window} must have been created by
some other display. Windows are removed automatically from the
save-set when they are destroyed.


@end defun


@node Managing Host Access, Screen Saver, Client Termination, Control Functions
@section 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 @emph{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:
@itemize @bullet

@item  Add or remove hosts on the access control list.

@item  Return the hosts on the access control list.

@item  Return or change the state of the access control list mechanism
@end itemize

@defun access-control display

@table @var
@item display
A @var{display}.
@end table
Returns and (with @code{setf}) changes the state of the access
control list mechanism for the @emph{display} server. Returns true
if access control is enabled; otherwise, @var{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.
@table @var
@item enabled-p
Type @var{boolean}.
@end table

@end defun


@defun access-hosts display &key (:result-type 'list)

@table @var
@item display
A @var{display}.
@item :result-type
The type of hosts sequence to return.
@end table
Returns a sequence containing the @emph{hosts} that belong to the
access control list of the @emph{display} server. Elements of the
returned @emph{hosts} sequence are either strings or some other type
of object recognized as a host name by @var{add-access-host} and
@var{remove-access-host}.  The second returned value specifies
whether the access control list mechanism is currently enabled or
disabled (see @var{access-control}).
@table @var
@item hosts
@var{sequence} of @var{string}.
@item enabled-p
Type @var{boolean}.
@end table

@end defun


@defun add-access-host display host

@table @var
@item display
A @var{display}.
@item host
A host name. Either a string or some other implementation-dependent type.
@end table

Adds the specified @emph{host} to the access control list. Only a
client running on the same host as the server can change the access
control list.


@end defun


@defun remove-access-host display host

@table @var
@item display
A @var{display}.
@item host
A host name. Either a string or some other implementation-dependent type.
@end table

Removes the specified @emph{host} from the access control list. Only
a client running on the same host as the server can change the
access control list.


@end defun


@node Screen Saver,  , Managing Host Access, Control Functions
@section 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:
@itemize @bullet

@item
Disabled -- No screen blanking is done and screen content remains unchanged.

@item
Deactivated -- The server is being used. When the server input devices
are unused for a specific amount of time, the screen saver becomes
activated.

@item
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.
@end itemize

The following paragraphs describe the CLX functions used to:
@itemize @bullet

@item
Return or change screen saver control values.

@item
Activate or reset the screen saver
@end itemize

@defun activate-screen-saver display

@table @var
@item display
A @var{display}.
@end table

Activates the screen saver for the @emph{display} server.


@end defun


@defun reset-screen-saver display

@table @var
@item display
A @var{display}.
@end table

Deactivates the screen saver for the @emph{display} server (if
necessary) and resets its timer, just as if a pointer or keyboard
event had occurred.


@end defun


@defun screen-saver display

@table @var
@item display
A @var{display}.
@end table
Returns the current control values for the @emph{display} server
screen saver. See @var{set-screen-saver}.
@table @var
@item timeout
@itemx period
Type @var{int16}.
@item blanking
@itemx exposures
One of @var{:yes} or @var{:no}.
@end table

@end defun


@defun set-screen-saver display timeout period blanking exposures

@table @var
@item display
A @var{display}.
@item timeout
Specifies the delay until timeout takes over.
@item period
Specifies the periodic change interval, if used.
@item blanking
Specifies whether the blanking option is available.
@item exposures
Specifies whether exposures are allowed during blanking.
@end table

Changes the current control values for the @emph{display} server
screen saver. The screen saver is reset. The screen saver is also
disabled if:
@itemize @bullet

@item
@emph{timeout} is zero, or

@item
Both @emph{blanking} and @emph{exposures} are disabled and the
server cannot regenerate the screen contents without sending
@var{:exposure} events.
@end itemize

The @emph{timeout} specifies the (non-negative) number of seconds of
input device inactivity that must elapse before the screen saver is
activated. The @emph{timeout} can be set to @var{:default} to
restore the server default timeout interval.

If @emph{blanking} is @var{:yes} and the screen hardware supports
blanking, blanking is enabled; that is, the screen saver will simply
blank all screens when it is activated. @emph{blanking} can be set
to @var{:default} to restore the server default state for blanking.

If @emph{exposures} is @var{:yes}, exposures are enabled. If
exposures are enabled, or if the server is capable of regenerating
screen contents without sending @var{: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 @emph{period} specifies the (
non-negative) number of seconds for each repetition. A @emph{period}
of zero is a hint that no repetition should occur.


@end defun



@node Extensions, Errors, Control Functions, Top
@chapter Extensions
@menu
* Extensions (Extensions)::     
* SHAPE - The X11 Nonrectangular Window Shape Extension::  
* RENDER - A new rendering system for X11::  
* DPMS - The X11 Display Power Management Signaling Extension::  
* BIG-REQUESTS - Big Requests Extension::  
@end menu

@node Extensions (Extensions), SHAPE - The X11 Nonrectangular Window Shape Extension, Extensions, Extensions
@section 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 @var{open-display}. The X Consortium maintains a registry
of standard extension names and protocol numbers.

The following paragraphs describe the CLX functions used to:
@itemize @bullet

@item  List all supported extensions.

@item  Find out if a given extension is supported.
@end itemize


@defun list-extensions display &key (:result-type 'list)

@table @var
@item display
A @var{display}.
@item :result-type
The type of name sequence to return.
@end table
Returns a sequence containing the @emph{names} of all extensions
supported by the @emph{display} server.
@table @var
@item names
Type @var{sequence} of @var{string}.
@end table

@end defun


@defun query-extension display name

@table @var
@item display
A @var{display}.
@item name
An extension name string.
@end table


Returns the @emph{major-opcode} for the given extension @emph{name}
support by the @emph{display} server. If the extension is not
supported, only @var{nil} values are returned. The extension
@emph{name} must contain only ISO Latin-1 characters; case is
significant.

If the extension involves additional event types, the
@emph{first-event} returned is the base event type code for new
events; otherwise, the @emph{first-event} is @var{nil}. If the
extension involves additional error codes, the @emph{first-error}
returned is the base code for new errors; otherwise, the
@emph{first-error} is @var{nil}. The formats of error and event
messages sent by the server are completely defined by the extension.
@table @var
@item major-opcode
@itemx first-event
@itemx first-error
Type @var{card8} or @var{null}.
@end table

@end defun


@node SHAPE - The X11 Nonrectangular Window Shape Extension, RENDER - A new rendering system for X11, Extensions (Extensions), Extensions
@section SHAPE - The X11 Nonrectangular Window Shape Extension


This documentation is yet to be written.

@node RENDER - A new rendering system for X11, DPMS - The X11 Display Power Management Signaling Extension, SHAPE - The X11 Nonrectangular Window Shape Extension, Extensions
@section 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.

@menu
* Picture formats::
* The picture object::
* Glyphs and Glyphsets::
* Using glyphs::
* Errors (Extensions)::
@end menu

@node Picture formats, The picture object, RENDER - A new rendering system for X11, RENDER - A new rendering system for X11
@subsection Picture formats

The following is what the X protocol rendering spec has to say about picture formats.
@url{http://www.xfree86.org/~keithp/render/protocol.html}


The @var{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 @var{picture-format} with 8 bits each of red, green,
blue and alpha as well as a direct @var{picture-format} with 8 bits of red, green and
blue and 0 bits of alpha.  The server must also support direct @var{picture-format}s
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 @var{picture-format} with zero bits of alpha component is declared to have
alpha == 1 everywhere.  A direct @var{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
@var{picture-format}s never have colormaps and are therefore screen independent.


Indexed @var{picture-format}s never have alpha channels and the direct component is all
zeros.  Indexed @var{picture-format}s 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.

@table @var
@item picture-format-display
A display
@item picture-format-id
The X protocol @var{resource-id}
@item picture-format-type
@code{(member :indexed :direct)}
@item picture-format-depth
Bitdepth as @var{card8}
@item picture-format-red-byte
A bitmask
@item picture-format-green-byte
@itemx picture-format-blue-byte
@itemx picture-format-alpha-byte
@itemx picture-format-colormap
A @var{colormap} or nil
@end table

@node The picture object, Glyphs and Glyphsets, Picture formats, RENDER - A new rendering system for X11
@subsection The picture object


The @var{picture} object contains a @var{drawable}, a @var{picture-format} and some
rendering state.  More than one @var{picture} can refer to the same @var{drawable}.


A @var{picture} is almost like a @var{gcontext}, except that it is tied in use to
a single @var{drawable}. Another similarity it has with @var{gcontext} is that it is
a cached object. Updates are not processed until the @var{picture} is used. This also
makes it possible to query state, as there is no such request in XRENDER to do so.


The @var{picture} object is also a lot like a @var{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.

@defun render-create-picture drawable &key format picture ...

@table @var
@item drawable
A @var{Drawable}
@item format
A @var{picture-format}
@item picture
An existing @var{picture} object to use,
one is created if not specified.
@item repeat
@code{(member :off :on)}
@item alpha-map
A @var{picture} or @var{:none}
@item alpha-x-origin
@var{int16}
@item alpha-y-origin
@var{int16}
@item clip-x-origin
@var{int16}
@item clip-y-origin
@var{int16}
@item clip-mask
A @var{Pixmap} or @var{:none}
@item graphics-exposures
@code{(member :off :on)}
@item subwindow-mode
@code{(member :clip-by-children :include-inferiors)}
@item poly-edge
@code{(member :sharp :smooth)}
@item poly-mode
@code{(member :precise :imprecise)}
@item dither
@var{xatom} or @var{:none}
@item component-alpha
@code{(member :off :on)}
@end table
This request creates a Picture object.  If the @emph{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.

@table @var
@item picture
A @var{picture}
@end table

@end defun



@defun render-free-picture picture This request deletes all server resources associated with the picture object.

@table @var
@item picture
The @var{picture} object to free
@end table



@end defun

@node Glyphs and Glyphsets, Using glyphs, The picture object, RENDER - A new rendering system for X11
@subsection 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.

@defun render-create-glyph-set format &key glyph-set

@table @var
@item format
A @var{picture-format} for the alpha masks that this font will use.
@item glyph-set
An optional @var{glyph-set} object to initialize with a server side glyphset resource.
@end table



Creates an initially empty glyph-set for the client to use.
@emph{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.
@end defun


@defun render-reference-glyph-set existing-glyph-set &key glyph-set

@table @var
@item existing-glyph-set
An existing @var{glyph-set}
@item glyph-set
An optional @var{glyph-set}, just like in @var{render-create-glyph-set}
@end table



Creates a new id refering to the existing-glyph-set. The glyph-set itself will not be freed until all
ids has been removed.
@end defun

@defun render-free-glyph-set glyph-set

@table @var
@item glyph-set
A glyphset resource to free
@end table

Removes an id to a glyph-set. When all ids have been removed the glyph-set itself is removed.



@end defun

@defun render-add-glyph glyph-set id &key x-origin y-origin x-advance y-advance data

@table @var
@item glyph-set
A @var{glyph-set}
@item id
@var{card32}
@item x-orgin
@var{int16}
@item y-orgin
@var{int16}
@item x-advance
@var{int16}
@item y-advance
@var{int16}
@item data
An @var{array} of @var{card8} bytes.
@end table

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.



@end defun

@defun render-add-glyph-from-picture glyph-set picture &key x-origin y-origin x-advance y-advance width height

@table @var
@item glyph-set
glyph-set
@item picture
picture
@item x-origin
int16
@item y-origin
int16
@item x-advance
int16
@item y-advance
int16
@item x
int16
@item y
int16
@item width
card16
@item height
card16
@end table



This request add a glyph to @emph{glyph-set} by copying it from the @emph{x,y} location in the @emph{picture}.

Existing glyphs with the same names are replaced.
The source @emph{picture} may be in a different @var{picture-format} than @emph{glyph-set}, in which case the images are converted to the glyph-set's format.
@end defun

@defun render-free-glyphs glyph-set glyphs

@table @var
@item glyph-set
A @var{glyph-set}
@item glyphs
sequence of @var{card32}
@end table




This request removes @emph{glyphs} from @emph{glyph-set}.
Each glyph must exist in @emph{glyph-set} (else a @var{Match} error results).
@end defun

@node Using glyphs, Errors (Extensions), Glyphs and Glyphsets, RENDER - A new rendering system for X11
@subsection Using glyphs

@defun render-composite-glyph dest glyph-set source dest-x dest-y sequence &key op src-x src-y mask-format start end

@table @var
@item dest
picture
@item glyph-set
glyph-set
@item source
picture
@item dest-x
int16
@item dest-y
int16
@item sequence

@item op
(member clear :src :dst :over :over-reverse :in :in-reverse :out :out-reverse :atop :atop-reverse :xor :add :saturate :maximum)
@item src-x
int16
@item src-y
iny16
@item mask-format
picture-format
@item start
blah
@item end
blah
@end table




Requests the sequence of glyphs to be drawn with the glyph-set.
@end defun



@node Errors (Extensions),  , Using glyphs, RENDER - A new rendering system for X11
@subsection Errors

What new errors Xrender defines...


@node  DPMS - The X11 Display Power Management Signaling Extension, BIG-REQUESTS - Big Requests Extension, RENDER - A new rendering system for X11, Extensions
@section DPMS - The X11 Display Power Management Signaling Extension

@defun dpms-get-version display &optional (major-version 1) (minor-version 1)
@table @var
@item display
@var{display}
@item major-version
@var{card16}
@item minor-version
@var{card16}
@end table


Return two values: the major and minor version of the DPMS
implementation the server supports.

If supplied, the @var{major-version} and @var{minor-version}
indicate what version of the protocol the client wants the server to
implement.
@end defun

@defun dpms-capable display
@table @var
@item display
@var{display}
@end table


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.
@end defun


@defun dpms-get-timeouts display
@table @var
@item display
@var{display}
@end table


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.
@end defun

@defun dpms-set-timeouts display standby suspend off
@table @var
@item display
@var{display}
@item standby
@var{card16}
@item suspend
@var{card16}
@item off 
@var{card16}
@end table


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.
@end defun
 
@defun dpms-enable display
@table @var
@item display
@var{display}
@end table


Enable the DPMS characteristics of the server using the server's
currently stored timeouts.  If DPMS is already enabled, no change is
affected.
@end defun

@defun dpms-disable display
@table @var
@item display
@var{display}
@end table


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.
@end defun

@defun dpms-force-level display power-level
@table @var
@item display
@var{display}
@item power-level
(member :dpms-mode-on :dpms-mode-standby :dpms-mode-suspend :dpms-mode-off)
@end table


Forces a specific DPMS level on the server.
@end defun

@defun dpms-info display
@table @var
@item display
@var{display}
@end table


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.
@end defun

@node BIG-REQUESTS - Big Requests Extension, , DPMS - The X11 Display Power Management Signaling Extension, Extensions
@section BIG-REQUESTS - Big Requests Extension

@defun display-extended-max-request-length display
@end defun
@defun enable-big-requests display
@end defun

@chapter Errors
@node Errors, Undocumented, Extensions, Top

@menu
* Introduction (Errors)::
@end menu

@node Introduction (Errors),  , Errors, Errors
@section Introduction

CLX error conditions are hierarchial. The base error condition is
@var{x-error}, and all other conditions are built on top of
@var{x-error}. @var{x-error} can be built on a lower-level condition
that is implementation dependent (this is probably the @var{error}
condition).

@defmac define-condition name (parent-types*) [({slot-specifier*}) {option*}]

Any new condition type must be defined with the
@var{define-condition} macro. A condition type has a name, parent
types, report message, and any number of slot items. See the
@emph{Lisp} @emph{Reference} manual for further information
regarding @var{define-condition}.

The following are the predefined error conditions that can occur in CLX.
@end defmac


@deftp {Condition} access-error

An @var{access-error} can occur for several reasons:
@itemize @bullet

@item
A client attempted to grab a key/button combination already
grabbed by another client

@item
A client attempted to free a colormap entry that it did not already allocate

@item
A client attempted to store into a read-only colormap entry

@item
A client attempted to modify the access control list from other
than the local (or otherwise authorized) host

@item
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
@end itemize

An @var{access-error} is a special case of the more general
@var{request-error} (@pxref{request-error}).
@end deftp


@deftp {Condition} alloc-error

The server failed to allocate the requested resource or server memory.

An @var{alloc-error} is a special case of the more general
@var{request-error} (@pxref{request-error}).
@end deftp


@deftp {Condition} atom-error

A value for an @emph{atom} argument does not name a defined atom.

An @var{atom-error} is a special case of the more general
@var{request-error} (@pxref{request-error}).
@end deftp


@deftp {Condition} closed-display

The @var{closed-display} condition is signaled when trying to read
or write a closed display (that is, @var{close-display} has been
called on the @var{display} object, or a server-disconnect
occurred). The @var{closed-display} object is reported with the
error.

A @var{closed-display} condition is a special case of the more
general @var{x-error} (@pxref{x-error}).
@end deftp


@deftp {Condition} colormap-error

A value for a @emph{colormap} argument does not name a defined
colormap.

A @var{colormap-error} is a special case of the more general
@var{resource-error} (@pxref{resource-error}).
@end deftp


@deftp {Condition} connection-failure

Signaled when an X11 server refuses a connection. The following
items are reported along with the error:
@itemize @bullet

@item  @emph{major-version} -- The major version of the X server code.

@item  @emph{minor-version} -- The minor version of the X server code.

@item  @emph{host} -- The host name for the X server.

@item  @emph{display} -- The display on which the error occurred.

@item  @emph{reason} -- A string indicating why the connection failed.
@end itemize

A @var{connection-failure} is a special case of the more general
@var{x-error} (@pxref{x-error}).
@end deftp


@deftp {Condition} cursor-error

A value for a @emph{cursor} argument does not name a defined cursor.

A @var{cursor-error} is a special case of the more general
@var{resource-error} (@pxref{resource-error}).
@end deftp


@deftp {Condition} device-busy

Signaled by (@code{setf} (@var{pointer-mapping} @emph{display})
@var{mapping}) when the @var{set-pointer-mapping} request returns
a busy status. A similar condition occurs in
@var{set-modifier-mapping}, but in this case, it returns a boolean
indicating success, rather than signaling an error.  The
@var{device-busy} condition returns the display object as part of
the error.

A @var{device-busy} condition is a special case of the more general
@var{x-error} (@pxref{x-error}).
@end deftp


@deftp {Condition} drawable-error

A value for a @emph{drawable} argument does not name a defined window or pixmap.

A @var{drawable-error} is a special case of the more general @var{resource-error} (@pxref{resource-error}).
@end deftp


@deftp {Condition} font-error

A value for a @emph{font} or @emph{gcontext} argument does not name a defined font.

A @var{font-error} is a special case of the more general
@var{resource-error} (@pxref{resource-error}).
@end deftp


@deftp {Condition} gcontext-error

A value for a @emph{gcontext} argument does not name a defined GContext.

A @var{gcontext-error} is a special case of the more general
@var{resource-error} (@pxref{resource-error}).
@end deftp


@deftp {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 @var{id-choice-error} is a special case of the more general
@var{resource-error} (@pxref{resource-error}).
@end deftp


@deftp {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 @var{implementation-error} is a special case of the more general
@var{resource-error} (@pxref{resource-error}).
@end deftp


@deftp {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 @var{length-error} is a special case of the more general
@var{resource-error} (@pxref{resource-error}).
@end deftp


@deftp {Condition} lookup-error

CLX has the option of caching different resource types (see
@var{*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 @var{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 @var{lookup-error} is signaled. This error indicates a
problem with the extension code being used. The following items are
reported along with the error:
@itemize @bullet

@item  @emph{id} -- The resource ID.

@item  @emph{display} -- The display being used.

@item  @emph{type} -- The resource type.

@item  @emph{object} -- The @var{resource} object.
@end itemize

A @var{lookup-error} is a special case of the more general
@var{x-error} (@pxref{x-error}).
@end deftp


@deftp {Condition} match-error

In a graphics request, the root and depth of the GContext does not
match that of the drawable. An @var{: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 @var{:input-only} window locks this attribute. The
values do not exist for an @var{:input-only} window.

A @var{match-error} is a special case of the more general
@var{request-error} (@pxref{request-error}).
@end deftp


@deftp {Condition} missing-parameter

One or more of the required keyword parameters is missing or
@var{nil}. The missing parameters are reported along with the
error.

A @var{missing-parameter} condition is a special case of the more
general @var{x-error} (@pxref{x-error}).
@end deftp


@deftp {Condition} name-error

A font or color of the specified name does not exist.

A @var{name-error} is a special case of the more general
@var{request-error} (@pxref{request-error}).
@end deftp


@deftp {Condition} pixmap-error

A value for a @emph{pixmap} argument does not name a defined pixmap.

A @var{pixmap-error} is a special case of the more general
@var{resource-error}. (@pxref{resource-error}.)
@end deftp


@deftp {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:
@itemize @bullet

@item  @emph{reply-length} -- The actual reply length.

@item  @emph{expected-length} -- The expected reply length.

@item  @emph{display} -- The display on which the error occurred.
@end itemize

A @var{reply-length-error} is a special case of the more general
@var{x-error} (@pxref{x-error}).
@end deftp


@deftp {Condition} reply-timeout

The @var{*reply-timeout*} parameter specifies the maximum number of
seconds to wait for a request reply, or @var{nil} to wait forever
(the default). When a reply has not been received after
*@var{reply-timeout}* seconds, the @var{reply-timeout} condition
is signaled. The @emph{timeout} @emph{period} and @emph{display} are
reported along with the error.

A @var{reply-timeout} condition is a special case of the more
general @var{x-error} (@pxref{x-error}).
@end deftp


@deftp {Condition} request-error
@anchor{request-error}

The following items are reported along with the error:

The major or minor opcode does not specify a valid request.
@itemize @bullet

@item  @emph{display} -- The display on which the error occurred.

@item  @emph{error-key} -- The error (sub)type.

@item  @emph{major} -- The major opcode.

@item  @emph{minor} -- The minor opcode.

@item  @emph{sequence} -- The actual sequence number.

@item  @emph{current-sequence} -- The current sequence number.
@end itemize

A @var{request-error} condition is a special case of the more
general @var{x-error} (@pxref{x-error}).
@end deftp

@deftp {Condition} resource-error
@anchor{resource-error}

All X11 errors for incorrect resource IDs are built on top of
@var{resource-error}. These are @var{colormap-error},
@var{cursor-error}, @var{drawable-error}, @var{font-error},
@var{gcontext-error}, @var{id-choice-error}, @var{pixmap-error}
and @var{window-error}. @var{resource-error} is never signaled
directly.

A @var{resource-error} is a special case of the more general
@var{request-error} (@pxref{request-error}).
@end deftp


@deftp {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
@var{sequence-error} is signaled. A @var{sequence-error} usually
indicates a locking problem with a multi-processing Lisp. The
following items are reported along with the error:
@itemize @bullet

@item  @emph{display} -- The display on which the error occurred.

@item  @emph{req-sequence} -- The sequence number in the reply.

@item  @emph{msg-sequence} -- The current sequence number.
@end itemize

A @var{sequence-error} condition is a special case of the more
general @var{x-error}. (@pxref{x-error})
@end deftp


@deftp {Condition} server-disconnect

The connection to the server was lost. The display on which the
error occurred is reported along with the error.

A @var{server-disconnect} condition is a special case of the more
general @var{x-error}. (@pxref{x-error})
@end deftp


@deftp {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:

@table @code
@item  display
The display on which the error occurred.

@item  req-sequence
The sequence number in the reply.

@item  msg-sequence
The current sequence number.

@item  length
The message length of the reply.
@end table


An @var{unexpected-reply} condition is a special case of the more general
@var{x-error}. (@pxref{x-error}.)
@end deftp


@deftp {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 @var{unknown-error} is a special case of the more general
@var{request-error}. (@pxref{request-error})
@end deftp


@deftp {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 @var{value-error} is a special case of the more general
@var{request-error}. (@pxref{request-error})
@end deftp


@deftp {Condition} window-error (resource-error)


A value for a @emph{window} argument does not name a defined window.

A @var{window-error} is a special case of the more general
@var{resource-error}. (@pxref{resource-error}.)
@end deftp


@deftp {Condition} x-error
@anchor{x-error}

This is the most general error condition upon which all other conditions are defined.
@end deftp



@ignore
@var{PROTOCOL VS. CLX FUNCTIONAL}

@var{CROSS-REFERENCE LISTING}

@var{X11 Request Name CLX Function Name}

AllocColor      @var{alloc-color}
AllocColorCells @var{alloc-color-cells}
AllocColorPlanes@var{alloc-color-planes}
AllocNamedColor @var{alloc-color}
AllowEvents     @var{allow-events}
Bell  @var{bell}
ChangeAccessControl       (@code{setf} (@var{access-control} @emph{display})
ChangeActivePointerGrab   @var{change-active-pointer-grab}
ChangeCloseDownMode       (@code{setf} (@var{close-down-mode} @emph{display}))
ChangeGC        @var{force-gcontext-changes}
(See @var{with-gcontext})
(@code{setf} (@var{gcontext-function} @emph{gc}))
(@code{setf} (@var{gcontext-plane-mask} @emph{gc}))
(@code{setf} (@var{gcontext-foreground} @emph{gc}))
(@code{setf} (@var{gcontext-background} @emph{gc}))
(@code{setf} (@var{gcontext-line-width} @emph{gc}))
(@code{setf} (@var{gcontext-line-style} @emph{gc}))
(@code{setf} (@var{gcontext-cap-style} @emph{gc}))
(@code{setf} (@var{gcontext-join-style} @emph{gc}))
(@code{setf} (@var{gcontext-fill-style} @emph{gc}))
(@code{setf} (@var{gcontext-fill-rule} @emph{gc}))
(@code{setf} (@var{gcontext-tile} @emph{gc}))
(@code{setf} (@var{gcontext-stipple} @emph{gc}))
(@code{setf} (@var{gcontext-ts-x} @emph{gc}))
(@code{setf} (@var{gcontext-ts-y} @emph{gc}))
(@code{setf} (@var{gcontext-font} @emph{gc} &optional
@var{metrics-p}))
(@code{setf} (@var{gcontext-subwindow-mode} @emph{gc}))
(@code{setf} (@var{gcontext-exposures} @emph{gc})))
(@code{setf} (@var{gcontext-clip-x} @emph{gc}))
(@code{setf} (@var{gcontext-clip-y} @emph{gc}))
(@code{setf} (@var{gcontext-clip-mask} @emph{gc}
&optional @var{ordering}))
(@code{setf} (@var{gcontext-dash-offset} @emph{gc}))
(@code{setf} (@var{gcontext-dashes} @emph{gc}))
(@code{setf} (@var{gcontext-arc-mode} @emph{gc}))
(@code{setf} (@var{gcontext-clip-ordering} @emph{gc}))

@var{X11 Request Name CLX Function Name}

ChangeHosts     @var{add-access-host}
ChangeHosts     @var{remove-access-host}
ChangeKeyboardControl     @var{change-keyboard-control}
ChangePointerControl      @var{change-pointer-control}
ChangeProperty  @var{change-property}
ChangeSaveSet   @var{remove-from-save-set}
ChangeSaveSet   @var{add-to-save-set}
ChangeWindowAttributes    (See @var{with-state})
(@code{setf} (@var{window-background} @emph{window}))
(@code{setf} (@var{window-border} @emph{window}))
(@code{setf} (@var{window-bit-gravity} @emph{window}))
(@code{setf} (@var{window-gravity} @emph{window}))
(@code{setf} (@var{window-backing-store} @emph{window}))
(@code{setf} (@var{window-backing-planes} @emph{window}))
(@code{setf} (@var{window-backing-pixel} @emph{window}))
(@code{setf} (@var{window-override-redirect} @emph{window})
@code{(setf (window-save-under} @emph{window}@var{))}
(@code{setf} (@var{window-colormap} @emph{window}))
(@code{setf} (@var{window-cursor} @emph{window}))
(@code{setf} (@var{window-event-mask} @emph{window}))
(@code{setf} (@var{window-do-not-propagate-mask}
@emph{window}))
CirculateWindow @var{circulate-window-down}
CirculateWindow @var{circulate-window-up}
ClearToBackground         @var{clear-area}
CloseFont       @var{close-font}
ConfigureWindow (See @var{with-state})
(@code{setf} (@var{drawable-x} @emph{drawable}))
(@code{setf} (@var{drawable-y} @emph{drawabl}e))
(@code{setf} (@var{drawable-width} @emph{drawable}))
(@code{setf} (@var{drawable-height} @emph{drawable}))
(@code{setf} (@var{drawable-depth} @emph{drawable}))
(@code{setf} (@var{drawable-border-width} @emph{drawable}))
(@code{setf} (@var{window-priority} @emph{window} &optional
@var{sibling}))
ConvertSelection@var{convert-selection}
CopyArea        @var{copy-area}
CopyColormapAndFree       @var{copy-colormap-and-free}
CopyGC@var{copy-gcontext}
CopyGC@var{copy-gcontext-components}
CopyPlane       @var{copy-plane}
CreateColormap  @var{create-colormap}
CreateCursor    @var{create-cursor}
CreateGC        @var{create-gcontext}
CreateGlyphCursor         @var{create-glyph-cursor}
CreatePixmap    @var{create-pixmap}
CreateWindow    @var{create-window}
DeleteProperty  @var{delete-property}
DestroySubwindows         @var{destroy-subwindows}
DestroyWindow   @var{destroy-window}
FillPoly        @var{draw-lines}
ForceScreenSaver@var{reset-screen-saver}
ForceScreenSaver@var{activate-screen-saver}
FreeColormap    @var{free-colormap}
FreeColors      @var{free-colors}
FreeCursor      @var{free-cursor}

@var{X11 Request Name CLX Function Name}

FreeGC@var{free-gcontext}
FreePixmap      @var{free-pixmap}
GetAtomName     @var{atom-name}
GetFontPath     @var{font-path}
GetGeometry     (See @var{with-state})
@var{drawable-root}
@var{drawable-x}
@var{drawable-y}
@var{drawable-width}
@var{drawable-height}
@var{drawable-depth}
@var{drawable-border-width}
GetImage        @var{get-raw-image}
GetInputFocus   @var{input-focus}
GetKeyboardControl        @var{keyboard-control}
GetKeyboardMapping        @var{keyboard-mapping}
GetModifierMapping        @var{modifier-mapping}
GetMotionEvents @var{motion-events}
GetPointerControl         @var{pointer-control}
GetPointerMapping         @var{pointer-mapping}
GetProperty     @var{get-property}
GetScreenSaver  @var{screen-saver}
GetSelectionOwner         @var{selection-owner}
GetWindowAttributes       (See @var{with-state})
@var{window-visual}
@var{window-class}
@var{window-bit-gravity}
@var{window-gravity}
@var{window-backing-store}
@var{window-backing-planes}
@var{window-backing-pixel}
@var{window-save-under}
@var{window-override-redirect}
@var{window-event-mask}
@var{window-do-not-propagate-mask}
@var{window-colormap}
@var{window-colormap-installed-p}
@var{window-all-event-masks}
@var{window-map-state}
GrabButton      @var{grab-button}
GrabKey         @var{grab-key}
GrabKeyboard    @var{grab-keyboard}
GrabPointer     @var{grab-pointer}
GrabServer      @var{grab-server}
ImageText16     @var{draw-image-glyphs}
ImageText16     @var{draw-image-glyph}
ImageText8      @var{draw-image-glyphs}
InstallColormap @var{install-colormap}
InternAtom      @var{find-atom}
InternAtom      @var{intern-atom}
KillClient      @var{kill-temporary-clients}
KillClient      @var{kill-client}
ListExtensions  @var{list-extensions}
ListFonts       @var{list-font-names}
ListFontsWithInfo         @var{list-fonts}
ListHosts       @var{access-control}

@var{X11 Request Name CLX Function Name}

ListHosts       @var{access-hosts}
ListInstalledColormaps    @var{installed-colormaps}
ListProperties  @var{list-properties}
LookupColor     @var{lookup-color}
MapSubwindows   @var{map-subwindows}
MapWindow       @var{map-window}
OpenFont        @var{open-font}
PolyArc         @var{draw-arc}
PolyArc         @var{draw-arcs}
PolyFillArc     @var{draw-arc}
PolyFillArc     @var{draw-arcs}
PolyFillRectangle         @var{draw-rectangle}
PolyFillRectangle         @var{draw-rectangles}
PolyLine        @var{draw-line}
PolyLine        @var{draw-lines}
PolyPoint       @var{draw-point}
PolyPoint       @var{draw-points}
PolyRectangle   @var{draw-rectangle}
PolyRectangle   @var{draw-rectangles}
PolySegment     @var{draw-segments}
PolyText16      @var{draw-glyph}
PolyText16      @var{draw-glyphs}
PolyText8       @var{draw-glyphs}
PutImage        @var{put-raw-image}
QueryBestSize   @var{query-best-cursor}
QueryBestSize   @var{query-best-stipple}
QueryBestSize   @var{query-best-tile}
QueryColors     @var{query-colors}
QueryExtension  @var{query-extension}
QueryFont       @var{font-name}
@var{font-name}
@var{font-direction}
@var{font-min-char}
@var{font-max-char}
@var{font-min-byte1}
@var{font-max-byte1}
@var{font-min-byte2}
@var{font-max-byte2}
@var{font-all-chars-exist-p}
@var{font-default-char}
@var{font-ascent}
@var{font-descent}
@var{font-properties}
@var{font-property}
@var{char-left-bearing}
@var{char-right-bearing}
@var{char-width}
@var{char-ascent}
@var{char-descent}
@var{char-attributes}
@var{min-char-left-bearing}
@var{min-char-right-bearing}
@var{min-char-width}
@var{min-char-ascent}
@var{min-char-descent}
@var{min-char-attributes}

@var{X11 Request Name CLX Function Name}

@var{max-char-left-bearing}
@var{max-char-right-bearing}
@var{max-char-width}
@var{max-char-ascent}
@var{max-char-descent}
@var{max-char-attributes}
QueryKeymap     @var{query-keymap}
QueryPointer    @var{global-pointer-position}
QueryPointer    @var{pointer-position}
QueryPointer    @var{query-pointer}
QueryTextExtents@var{text-extents}
QueryTextExtents@var{text-width}
QueryTree       @var{query-tree}
RecolorCursor   @var{recolor-cursor}
ReparentWindow  @var{reparent-window}
RotateProperties@var{rotate-properties}
SendEvent       @var{send-event}
SetClipRectangles         @var{force-gcontext-changes}
(See @var{with-gcontext})
(@code{setf} (@var{gcontext-clip-x} @emph{gc}))
(@code{setf} (@var{gcontext-clip-y} @emph{gc}))
(@code{setf} (@var{gcontext-clip-mask} @emph{gc} &optional
@var{ordering}))
(@code{setf} (@var{gcontext-clip-ordering} @emph{gc}))
SetDashes       @var{force-gcontext-changes}
(See @var{with-gcontext})
(@code{setf} (@var{gcontext-dash-offset} @emph{gc}))
(@code{setf} (@var{gcontext-dashes} @emph{gc}))
SetFontPath     (@code{setf} (@var{font-path} @emph{font})
SetInputFocus   @var{set-input-focus}
SetKeyboardMapping        @var{change-keyboard-mapping}
SetModifierMapping        @var{set-modifier-mapping}
SetPointerMapping         @var{set-pointer-mapping}
SetScreenSaver  @var{set-screen-saver}
SetSelectionOwner         @var{set-selection-owner}
StoreColors     @var{store-color}
StoreColors     @var{store-colors}
StoreNamedColor @var{store-color}
StoreNamedColor @var{store-colors}
TranslateCoords @var{translate-coordinates}
UngrabButton    @var{ungrab-button}
UngrabKey       @var{ungrab-key}
UngrabKeyboard  @var{ungrab-keyboard}
UngrabPointer   @var{ungrab-pointer}
UngrabServer    @var{ungrab-server}
UninstallColormap         @var{uninstall-colormap}
UnmapSubwindows @var{unmap-subwindows}
UnmapWindow     @var{unmap-window}
WarpPointer     @var{warp-pointer}
WarpPointer     @var{warp-pointer-if-inside}
WarpPointer     @var{warp-pointer-relative}
WarpPointer     @var{warp-pointer-relative-if-inside}
ListHosts       @var{access-control}
ListHosts       @var{access-hosts}
ForceScreenSaver@var{activate-screen-saver}
ChangeHosts     @var{add-access-host}

@var{X11 Request Name CLX Function Name}

ChangeSaveSet   @var{add-to-save-set}
AllocColor      @var{alloc-color}
AllocNamedColor @var{alloc-color}
AllocColorCells @var{alloc-color-cells}
AllocColorPlanes@var{alloc-color-planes}
AllowEvents     @var{allow-events}
GetAtomName     @var{atom-name}
Bell  @var{bell}
ChangeActivePointerGrab   @var{change-active-pointer-grab}
ChangeKeyboardControl     @var{change-keyboard-control}
SetKeyboardMapping        @var{change-keyboard-mapping}
ChangePointerControl      @var{change-pointer-control}
ChangeProperty  @var{change-property}
QueryFont       @var{char-ascent}
QueryFont       @var{char-attributes}
QueryFont       @var{char-descent}
QueryFont       @var{char-left-bearing}
QueryFont       @var{char-right-bearing}
QueryFont       @var{char-width}
CirculateWindow @var{circulate-window-down}
CirculateWindow @var{circulate-window-up}
ClearToBackground         @var{clear-area}
CloseFont       @var{close-font}
ConvertSelection@var{convert-selection}
CopyArea        @var{copy-area}
CopyColormapAndFree       @var{copy-colormap-and-free}
CopyGC@var{copy-gcontext}
CopyGC@var{copy-gcontext-components}
CopyPlane       @var{copy-plane}
CreateColormap  @var{create-colormap}
CreateCursor    @var{create-cursor}
CreateGC        @var{create-gcontext}
CreateGlyphCursor         @var{create-glyph-cursor}
CreatePixmap    @var{create-pixmap}
CreateWindow    @var{create-window}
DeleteProperty  @var{delete-property}
DestroySubwindows         @var{destroy-subwindows}
DestroyWindow   @var{destroy-window}
PolyArc         @var{draw-arc}
PolyArc         @var{draw-arcs}
PolyText16      @var{draw-glyph}
PolyText16      @var{draw-glyphs}
PolyText8       @var{draw-glyphs}
ImageText16     @var{draw-image-glyph}
ImageText16     @var{draw-image-glyphs}
ImageText8      @var{draw-image-glyphs}
PolyLine        @var{draw-line}
PolyLine        @var{draw-lines}
PolyPoint       @var{draw-point}
PolyPoint       @var{draw-points}
PolyFillRectangle         @var{draw-rectangle}
PolyRectangle   @var{draw-rectangle}
PolyFillRectangle         @var{draw-rectangles}
PolyRectangle   @var{draw-rectangles}
PolySegment     @var{draw-segments}
GetGeometry     @var{drawable-border-width}

@var{X11 Request Name CLX Function Name}

GetGeometry     @var{drawable-depth}
GetGeometry     @var{drawable-height}
GetGeometry     @var{drawable-root}
GetGeometry     @var{drawable-width}
GetGeometry     @var{drawable-x}
GetGeometry     @var{drawable-y}
FillPoly        @var{fill-polygon}
InternAtom      @var{find-atom}
QueryFont       @var{font-all-chars-exist-p}
QueryFont       @var{font-ascent}
QueryFont       @var{font-default-char}
QueryFont       @var{font-descent}
QueryFont       @var{font-direction}
QueryFont       @var{font-max-byte1}
QueryFont       @var{font-max-byte2}
QueryFont       @var{font-max-char}
QueryFont       @var{font-min-byte1}
QueryFont       @var{font-min-byte2}
QueryFont       @var{font-min-char}
QueryFont       @var{font-name}
QueryFont       @var{font-name}
GetFontPath     @var{font-path}
QueryFont       @var{font-properties}
QueryFont       @var{font-property}
ChangeGC        @var{force-gcontext-changes}
SetClipRectangles         @var{force-gcontext-changes}
SetDashes       @var{force-gcontext-changes}
FreeColormap    @var{free-colormap}
FreeColors      @var{free-colors}
FreeCursor      @var{free-cursor}
FreeGC@var{free-gcontext}
FreePixmap      @var{free-pixmap}
GetProperty     @var{get-property}
GetImage        @var{get-raw-image}
QueryPointer    @var{global-pointer-position}
GrabButton      @var{grab-button}
GrabKey         @var{grab-key}
GrabKeyboard    @var{grab-keyboard}
GrabPointer     @var{grab-pointer}
GrabServer      @var{grab-server}
GrabServer      @var{with-server-grabbed}
GetInputFocus   @var{input-focus}
InstallColormap @var{install-colormap}
ListInstalledColormaps    @var{installed-colormaps}
InternAtom      @var{intern-atom}
GetKeyboardControl        @var{keyboard-control}
GetKeyboardMapping        @var{keyboard-mapping}
KillClient      @var{kill-client}
KillClient      @var{kill-temporary-clients}
ListExtensions  @var{list-extensions}
ListFonts       @var{list-font-names}
ListFontsWithInfo         @var{list-fonts}
ListProperties  @var{list-properties}
LookupColor     @var{lookup-color}
MapSubwindows   @var{map-subwindows}
MapWindow       @var{map-window}

@var{X11 Request Name CLX Function Name}

QueryFont       @var{max-char-ascent}
QueryFont       @var{max-char-attributes}
QueryFont       @var{max-char-descent}
QueryFont       @var{max-char-left-bearing}
QueryFont       @var{max-char-right-bearing}
QueryFont       @var{max-char-width}
QueryFont       @var{min-char-ascent}
QueryFont       @var{min-char-attributes}
QueryFont       @var{min-char-descent}
QueryFont       @var{min-char-left-bearing}
QueryFont       @var{min-char-right-bearing}
QueryFont       @var{min-char-width}
GetModifierMapping        @var{modifier-mapping}
GetMotionEvents @var{motion-events}
OpenFont        @var{open-font}
GetPointerControl         @var{pointer-control}
GetPointerMapping         @var{pointer-mapping}
QueryPointer    @var{pointer-position}
PutImage        @var{put-raw-image}
QueryBestSize   @var{query-best-cursor}
QueryBestSize   @var{query-best-stipple}
QueryBestSize   @var{query-best-tile}
QueryColors     @var{query-colors}
QueryExtension  @var{query-extension}
QueryKeymap     @var{query-keymap}
QueryPointer    @var{query-pointer}
QueryTree       @var{query-tree}
RecolorCursor   @var{recolor-cursor}
ChangeHosts     @var{remove-access-host}
ChangeSaveSet   @var{remove-from-save-set}
ReparentWindow  @var{reparent-window}
ForceScreenSaver@var{reset-screen-saver}
RotateProperties@var{rotate-properties}
GetScreenSaver  @var{screen-saver}
GetSelectionOwner         @var{selection-owner}
SendEvent       @var{send-event}
ChangeAccessControl       @var{set-access-control}
ChangeCloseDownMode       @var{set-close-down-mode}
SetInputFocus   @var{set-input-focus}
SetModifierMapping        @var{set-modifier-mapping}
SetPointerMapping         @var{set-pointer-mapping}
SetScreenSaver  @var{set-screen-saver}
SetSelectionOwner         @var{set-selection-owner}
StoreColors     @var{store-color}
StoreColors     @var{store-colors}
StoreNamedColor @var{store-color}
StoreNamedColor @var{store-colors}
QueryTextExtents@var{text-extents}
QueryTextExtents@var{text-width}
TranslateCoords @var{translate-coordinates}
UngrabButton    @var{ungrab-button}
UngrabKey       @var{ungrab-key}
UngrabKeyboard  @var{ungrab-keyboard}
UngrabPointer   @var{ungrab-pointer}
UngrabServer    @var{ungrab-server}
UngrabServer    @var{with-server-grabbed}

@var{X11 Request Name CLX Function Name}

UninstallColormap         @var{uninstall-colormap}
UnmapSubwindows @var{unmap-subwindows}
UnmapWindow     @var{unmap-window}
WarpPointer     @var{warp-pointer}
WarpPointer     @var{warp-pointer-if-inside}
WarpPointer     @var{warp-pointer-relative}
WarpPointer     @var{warp-pointer-relative-if-inside}
GetWindowAttributes       @var{window-all-event-masks}
GetWindowAttributes       @var{window-backing-pixel}
GetWindowAttributes       @var{window-backing-planes}
GetWindowAttributes       @var{window-backing-store}
GetWindowAttributes       @var{window-bit-gravity}
GetWindowAttributes       @var{window-class}
GetWindowAttributes       @var{window-colormap}
GetWindowAttributes       @var{window-colormap-installed-p}
GetWindowAttributes       @var{window-do-not-propagate-mask}
GetWindowAttributes       @var{window-event-mask}
GetWindowAttributes       @var{window-gravity}
GetWindowAttributes       @var{window-map-state}
GetWindowAttributes       @var{window-override-redirect}
GetWindowAttributes       @var{window-save-under}
GetWindowAttributes       @var{window-visual}
ConfigureWindow (@code{setf} (@var{drawable-border-width} @emph{drawable}))
ConfigureWindow (@code{setf} (@var{drawable-depth} @emph{drawable}))
ConfigureWindow (@code{setf} (@var{drawable-height} @emph{drawable}))
ConfigureWindow (@code{setf} (@var{drawable-width} @emph{drawabl}e))
ConfigureWindow (@code{setf} (@var{drawable-x} @emph{drawable}))
ConfigureWindow (@code{setf} (@var{drawable-y} @emph{drawable}))
SetFontPath     (@code{setf} (@var{font-path} @emph{font}) @var{paths})
ChangeGC        (@code{setf} (@var{gcontext-arc-mode} @emph{gc}))
ChangeGC        (@code{setf} (@var{gcontext-background} @emph{gc}))
ChangeGC        (@code{setf} (@var{gcontext-cap-style} @emph{gc}))
SetClipRectangles         (@code{setf} (@var{gcontext-clip-mask} @emph{gc} &optional
@var{ordering}))
SetClipRectangles         (@code{setf} (@var{gcontext-clip-ordering} @emph{gc}))
SetClipRectangles         (@code{setf} (@var{gcontext-clip-x} @emph{gc}))
SetClipRectangles         (@code{setf} (@var{gcontext-clip-y} @emph{gc}))
SetDashes       (@code{setf} (@var{gcontext-dash-offset} @emph{gc}))
SetDashes       (@code{setf} (@var{gcontext-dashes} @emph{gc}))
ChangeGC        (@code{setf} (@var{gcontext-exposures} @emph{gc}))
ChangeGC        (@code{setf} (@var{gcontext-fill-rule} @emph{gc}) @var{keyword})
ChangeGC        (@code{setf} (@var{gcontext-fill-style} @emph{gc}) @var{keyword})
ChangeGC        (@code{setf} (@var{gcontext-font} @emph{gc} &optional
@var{metrics-p})
ChangeGC        (@code{setf} (@var{gcontext-foreground} @emph{gc}) @var{card32})
ChangeGC        (@code{setf} (@var{gcontext-function} @emph{gc}))
ChangeGC        (@code{setf} (@var{gcontext-join-style} @emph{gc}) @var{keyword})
ChangeGC        (@code{setf} (@var{gcontext-line-style} @emph{gc}) @var{keyword})
ChangeGC        (@code{setf} (@var{gcontext-line-width} @emph{gc}) @var{card16})
ChangeGC        (@code{setf} (@var{gcontext-plane-mask} @emph{gc}) @var{card32})
ChangeGC        (@code{setf} (@var{gcontext-stipple} @emph{gc}) @var{pixmap})
ChangeGC        (@code{setf} (@var{gcontext-subwindow-mode} @emph{gc}))
ChangeGC        (@code{setf} (@var{gcontext-tile} @emph{gc}))
ChangeGC        (@code{setf} (@var{gcontext-ts-x} @emph{gc}))
ChangeGC        (@code{setf} (@var{gcontext-ts-y} @emph{gc}))
ChangeWindowAttributes    (@code{setf} (@var{window-background} @emph{window}))

@var{X11 Request Name CLX Function Name}

ChangeWindowAttributes    (@code{setf} (@var{window-backing-pixel} @emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-backing-planes} @emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-backing-store} @emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-bit-gravity} @emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-border} @emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-colormap} @emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-cursor} @emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-do-not-propagate-mask}
@emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-event-mask} @emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-gravity} @emph{window}))
ChangeWindowAttributes    (@code{setf} (@var{window-override-redirect} @emph{window}))
ConfigureWindow (@code{setf} (@var{window-priority} @emph{window} &optional
@var{sibling}))
ChangeWindowAttributes    (@code{setf} (@var{window-save-under} @emph{window}))
@end ignore

@node Undocumented, Glossary, Errors, Top
@chapter Undocumented

This section just lists all symbols exported from the
@var{XLIB} package but not documented in this manual.

@defun bitmap-image &optional plist &rest patterns
@end defun


@defun character->keysyms character &optional display
@end defun


@defun character-in-map-p display character keymap

@table @var
@item display
A @var{display}.
@end table

@end defun

@defun decode-core-error display event &optional arg
@end defun

@defun default-error-handler display error-key &rest key-vals &key asynchronous &allow-other-keys
@end defun

@defun default-keysym-index display keycode state
@end defun

@defun default-keysym-translate display state object
@end defun

@defun define-keysym object keysym &key lowercase translate modifiers mask display
@end defun

@defun define-keysym-set set first-keysym last-keysym
@end defun

@defun display-invoke-after-function display


Explicitly invokes the @emph{after-function} of the display.
(see @var{display-after-function}). This function is
internally called after every request.
@end defun

@defun display-nscreens display
@end defun

@defun display-release-number object
@end defun

@defun event-handler handlers event-key
@end defun

@defun get-external-event-code display event
@end defun

@defun get-standard-colormap window property
@end defun

@defun get-wm-class window
@end defun

@defun icon-sizes window
@end defun

@defun iconify-window window screen
@end defun

@defun keysym->keycodes display keysym
@end defun

@defun keysym-in-map-p display keysym keymap
@end defun

@defun keysym-set keysym
@end defun

@defun mapping-notify display request start count

Called on a @var{:mapping-notify} event to update
the keyboard-mapping cache in @emph{display}.
@end defun

@defun no-operation display
@end defun

@defun parse-color colormap spec
@end defun

@defun resource-database-timestamp database
@end defun

@defun resource-key stringable
@end defun

@defun rgb-colormaps window property
@end defun

@defun root-resources screen &key database key test test-not

Returns a resource database containing the contents of the
root window @var{RESOURCE_MANAGER} property for the given
@emph{screen}. If @emph{screen} is a display, then its
default screen is used. If an existing @emph{database} is
given, then resource values are merged with the
@emph{database} and the modified @emph{database} is
returned.

@emph{test} and @emph{test-not} are predicates for selecting
which resources are read. Arguments are a resource name list
and a resource value. The @emph{key} function, if given, is
called to convert a resource value string to the value given
to @emph{test} or @emph{test-not}.
@end defun

@defun rotate-cut-buffers display &optional (delta 1) (careful-p t)
@end defun

@defun set-access-control display enabled-p
@end defun

@defun set-close-down-mode display mode
@anchor{set-close-down-mode}
@end defun

@defun set-pointer-mapping display map
@end defun

@defun set-selection-owner display selection owner &optional time
@end defun

@defun set-standard-colormap window property colormap base-pixel max-color mult-color
@end defun

@defun set-standard-properties window &rest options
@end defun

@defun set-wm-class window resource-name resource-class
@end defun

@defun 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
@end defun

@defun set-wm-resources database window &key write test test-not
@end defun

@defun transient-for window
@end defun

@defun translate-default src src-start src-end font dst dst-start
@end defun

@defun undefine-keysym object keysym &key display modifiers &allow-other-keys
@end defun

@defun visual-info-blue-mask object
@end defun

@defun visual-info-green-mask object
@end defun

@defun visual-info-red-mask object
@end defun

@defun window-cursor window
@end defun

@defun window-visual-info window
@end defun

@defun withdraw-window window screen
@end defun

@defun wm-client-machine window
@end defun

@defun wm-colormap-windows window
@end defun

@defun wm-command window
@end defun

@defun wm-hints window
@end defun

@defun wm-hints-flags object
@end defun

@defun wm-icon-name window
@end defun

@defun wm-name window
@end defun

@defun wm-normal-hints window
@end defun

@defun wm-protocols window
@end defun

@defun wm-resources database window &key key test test-not
@end defun

@defun wm-zoom-hints window
@end defun

@ignore
XLIB:STATE-KEYSYM-P is undocumented.
XLIB:*VERSION* is undocumented.
XLIB:BITMAP-FORMAT-LSB-FIRST-P ???  [Function]
XLIB:BITMAP-FORMAT-P ???  [Function]
XLIB:BITMAP-FORMAT-PAD ???[Function]
XLIB:BITMAP-FORMAT-UNIT ???         [Function]
XLIB:CARD8->CHAR (card8)  [Function]
XLIB:CHAR->CARD8 (char)   [Function]
XLIB:COLORMAP-VISUAL-INFO ???       [Function]
XLIB:CUT-BUFFER (display &key (buffer 0) (type :string) (result-type 'string)
(transform #'card8->char) (start 0) end)     [Function]
XLIB:DEFINE-ERROR ???     [Function]
XLIB:DEFINE-EXTENSION ??? [Function]
XLIB:DEFINE-GCONTEXT-ACCESSOR ???   [Function]
XLIB:DISPLAY-DEFAULT-SCREEN ???     [Function]
XLIB:DISPLAY-HOST ???     [Function]
XLIB:DISPLAY-REPORT-ASYNCHRONOUS-ERRORS ???   [Function]
XLIB:DISPLAY-XDEFAULTS ???[Function]
XLIB:EXTENSION-OPCODE ??? [Function]
XLIB:GCONTEXT-CLIP-ORDERING is undocumented.
XLIB:GENERALIZED-BOOLEAN is undocumented.
XLIB:ILLEGAL-REQUEST-ERROR is undocumented.
XLIB:IMAGE is undocumented.
XLIB:IMAGE-PIXMAP (drawable image &key gcontext width height depth)         [Function]
XLIB:IMAGE-X is undocumented.
XLIB:IMAGE-X-P ???        [Function]
XLIB:IMAGE-XY is undocumented.
XLIB:IMAGE-XY-P ???       [Function]
XLIB:IMAGE-Z is undocumented.
XLIB:IMAGE-Z-P ???        [Function]
XLIB:INVALID-FONT is undocumented.
XLIB:KEYCODE->CHARACTER (display keycode state &key keysym-index
(keysym-index-function #'default-keysym-index))        [Function]
XLIB:MAKE-EVENT-HANDLERS (&key (type 'array) default)   [Function]
XLIB:MAKE-WM-HINTS (&key ((:input #:g0) nil) ((:initial-state #:g1) nil) ((:icon-pixmap #:g2) nil)
((:icon-window #:g3) nil) ((:icon-x #:g4) nil) ((:icon-y #:g5) nil)
((:icon-mask #:g6) nil) ((:window-group #:g7) nil) ((:flags #:g8) 0))      [Function]
XLIB:MAKE-WM-SIZE-HINTS (&key ((:user-specified-position-p #:g0) nil)
((:user-specified-size-p #:g1) nil) ((:x #:g2) nil) ((:y #:g3) nil)
((:width #:g4) nil) ((:height #:g5) nil) ((:min-width #:g6) nil)
((:min-height #:g7) nil) ((:max-width #:g8) nil) ((:max-height #:g9) nil)
((:width-inc #:g10) nil) ((:height-inc #:g11) nil) ((:min-aspect #:g12) nil)
((:max-aspect #:g13) nil) ((:base-width #:g14) nil) ((:base-height #:g15) nil)
((:win-gravity #:g16) nil) ((:program-specified-position-p #:g17) nil)
((:program-specified-size-p #:g18) nil))     [Function]
XLIB:PIXMAP-FORMAT-BITS-PER-PIXEL ???         [Function]
XLIB:PIXMAP-FORMAT-DEPTH ???        [Function]
XLIB:PIXMAP-FORMAT-P ???  [Function]
XLIB:PIXMAP-FORMAT-SCANLINE-PAD ??? [Function]
XLIB:RESOURCE-DATABASE is undocumented.
XLIB:SCREEN-ROOT-VISUAL-INFO ???    [Function]
XLIB:TRANSLATION-FUNCTION is undocumented.
XLIB:VISUAL-INFO-BITS-PER-RGB ???   [Function]
XLIB:VISUAL-INFO-CLASS ???[Function]
XLIB:VISUAL-INFO-COLORMAP-ENTRIES ???         [Function]
XLIB:VISUAL-INFO-DISPLAY ???        [Function]
XLIB:VISUAL-INFO-ID ???   [Function]
XLIB:VISUAL-INFO-P ???    [Function]
XLIB:VISUAL-INFO-PLIST ???[Function]
XLIB:WINDOW-BACKGROUND is undocumented.
XLIB:WINDOW-BORDER is undocumented.
XLIB:WINDOW-PRIORITY is undocumented.
XLIB:WM-HINTS-ICON-MASK ???         [Function]
XLIB:WM-HINTS-ICON-PIXMAP ???       [Function]
XLIB:WM-HINTS-ICON-WINDOW ???       [Function]
XLIB:WM-HINTS-ICON-X ???  [Function]
XLIB:WM-HINTS-ICON-Y ???  [Function]
XLIB:WM-HINTS-INITIAL-STATE ???     [Function]
XLIB:WM-HINTS-INPUT ???   [Function]
XLIB:WM-HINTS-P ???       [Function]
XLIB:WM-HINTS-WINDOW-GROUP ???      [Function]
XLIB:WM-SIZE-HINTS is undocumented.
XLIB:WM-SIZE-HINTS-BASE-HEIGHT ???  [Function]
XLIB:WM-SIZE-HINTS-BASE-WIDTH ???   [Function]
XLIB:WM-SIZE-HINTS-HEIGHT ???       [Function]
XLIB:WM-SIZE-HINTS-HEIGHT-INC ???   [Function]
XLIB:WM-SIZE-HINTS-MAX-ASPECT ???   [Function]
XLIB:WM-SIZE-HINTS-MAX-HEIGHT ???   [Function]
XLIB:WM-SIZE-HINTS-MAX-WIDTH ???    [Function]
XLIB:WM-SIZE-HINTS-MIN-ASPECT ???   [Function]
XLIB:WM-SIZE-HINTS-MIN-HEIGHT ???   [Function]
XLIB:WM-SIZE-HINTS-MIN-WIDTH ???    [Function]
XLIB:WM-SIZE-HINTS-P ???  [Function]
XLIB:WM-SIZE-HINTS-USER-SPECIFIED-POSITION-P ???        [Function]
XLIB:WM-SIZE-HINTS-USER-SPECIFIED-SIZE-P ???  [Function]
XLIB:WM-SIZE-HINTS-WIDTH ???        [Function]
XLIB:WM-SIZE-HINTS-WIDTH-INC ???    [Function]
XLIB:WM-SIZE-HINTS-WIN-GRAVITY ???  [Function]
XLIB:WM-SIZE-HINTS-X ???  [Function]
XLIB:WM-SIZE-HINTS-Y ???  [Function]
@end ignore

@node Glossary, Function Index, Undocumented, Top
@appendix Glossary

@table @asis
@item 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 @emph{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.

@item 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 @var{event-translations} slot and then calling
actions associated with the matching event specification.

@item active grab
A grab is @emph{active} when the pointer or keyboard is actually owned
by the single grabbing client.

@item ancestors
If W is an inferior of A, then A is an @emph{ancestor} of W.

@item atom
A unique ID corresponding to a string name. Atoms are used to identify
properties, types, and selections.

@item backing store
When a server maintains the contents of a window, the off-screen saved
pixels are known as a @emph{backing store}.

@item before action
An action of a @var{contact-display} that is called when an event is
dispatched to a contact, but before any other contact input processing
is performed.

@item 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 @emph{bit} @emph{gravity}.

@item bitmap
A pixmap of depth one.

@item button grabbing
Buttons on the pointer can be passively @emph{grabbed} by a
client. When the button is pressed, the pointer is then actively
grabbed by the client.

@item 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.

@item 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.

@item children
First-level subwindows of a window.

@item class event
Event translations that belong to all instances of a contact class. A
class event @var{translations} translation is created by the
@var{defevent} macro.

@item class resources
Resources defined for each instance of a contact class. Also see
constraint resources.

@item click
A @var{:button-press} event followed immediately by a
@var{:button-release} event for the same button, with no intervening
change in pointer position or modifier key state.

@item 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 @emph{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.

@item 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 @emph{clipping
region}.

@item 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.

@item composite
A subclass of @var{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.

@item complete resource class
A list of symbols containing the class of the contact, the class of
the contact's @var{parent} (and so on), and the class of the
@var{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.

@item complete resource name
A list of symbols containing the @var{name} of the contact, the
@var{name} of the contact's @var{parent} (and so on), and the name
of the @var{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.

@item 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.

@item 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.

@item contact
The basic CLUE object for programming a user interface.

@item contact-display
The CLUE object type that represents a connection to an X server and
that supports an event loop for application input.

@item 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.

@item contact realization
The process of allocating contact resources. This process completes
contact creation.

@item 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.

@item content
The single child of a shell. The basic geometry management policy
implemented by the @var{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.

@item 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.

@item 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.

@item 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.

@item descendant
If W is an inferior of A, then W is a @emph{descendant} of A.

@item device
Keyboards, mice, tablets, track-balls, button boxes, and so forth, are
all collectively known as input @emph{devices}. The core protocol only
deals with two devices: the keyboard and the pointer.

@item 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.

@item dispatching an event
The process of finding the appropriate contact and its actions.

@item double-click
A sequence of two clicks of the same button in rapid succession.

@item drawable
Both windows and pixmaps can be used as sources and destinations in
graphics operations. These are collectively known as
@emph{drawables}. However, an @var{:input-only} window cannot be used
as a source or destination in a graphics operation.

@item event
Clients receive information asynchronously via @emph{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.

@item event compression
Ignoring (or compressing) certain redundant input events. Compression
of redundant events is controlled by the class slots
@var{compress-exposures} and @var{compress-motion}, which are shared
by all instances of a contact class.

@item 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
@var{process-next-event} function.

@item 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 @emph{event
mask}.

@item event propagation
Device-related events @emph{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.

@item 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 @var{event-translations} slot and then calling
actions associated with the matching event specification.

@item 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.

@item event source
The smallest window containing the pointer is the @emph{source} of a
device related event.

@item event translation
The process of determining which contact action functions will be
executed. An event translation is a list found in a contact's
@var{event-translations} slot associating an event specification with
one or more action names. Also see class event translations.

@item exposure event
Servers do not guarantee to preserve the contents of windows when
windows are obscured or reconfigured. @emph{Exposure} events are sent
to clients to inform them when contents of regions of windows have
been lost.

@item extension
Named @emph{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.

@item focus window
Another term for the input focus.

@item 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.

@item geometry management
The process whereby a composite controls the geometrical properties of
its child contacts; the composite is referred to as the geometry
manager.

@item glyph
An image, typically of a character, in a font.

@item grab
Keyboard keys, the keyboard, pointer buttons, the pointer, and the
server can be @emph{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.

@item gcontext
Shorthand for graphics context.

@item graphics context
Various information for graphics output is stored in a @emph{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.

@item 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.

@item hot spot
A cursor has an associated @emph{hot spot} that defines a point in the
cursor that corresponds to the coordinates reported for the pointer.

@item identifier
Each resource has an @emph{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.

@item inferiors
All of the subwindows nested below a window: the children, the
children's children, and so on.

@item initialization
See contact initialization.

@item input event
See event.

@item 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.

@item input-only window
A window that cannot be used for graphics requests. @emph{input-only}
windows are invisible, and can be used to control such things as
cursors, input event generation, and grabbing.  @emph{input-only}
windows cannot have @emph{input/output} windows as inferiors.

@item input/output window
The normal kind of opaque window, used for both input and
output. Input/output windows can have both @emph{input/output} and
input-only windows as inferiors.

@item insensitivity
See sensitivity.

@item interactive-stream
A contact subclass designed to integrate CLUE with the conventional
stream-based I/O of Common Lisp.

@item key grabbing
Keys on the keyboard can be passively @emph{grabbed} by a client. When
the key is pressed, the keyboard is then actively grabbed by the
client.

@item keyboard grabbing
A client can actively @emph{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.

@item keysym
An encoding of a symbol on a keycap on a keyboard.

@item managed
A contact under geometry management control.

@item mapped
A window is said to be @emph{mapped} if a map call has been performed
on it. Unmapped windows and their inferiors are never viewable or
visible.

@item modifier keys
SHIFT, CONTROL, META, SUPER, HYPER, ALT, Compose, Apple, CAPS LOCK,
Shift Lock, and similar keys are called @emph{modifier keys}.

@item monochrome
A special case of static gray, in which there are only two colormap
entries.

@item obscure
A window is @emph{obscured} if some other window obscures it. For
example, window A obscures window B if:
@itemize @bullet

@item  Both windows are viewable @var{:input-output} windows

@item  Window A is higher in the global stacking order than window B

@item  The rectangle defined by the outside edges of window A intersects the rectangle
defined by the outside edges of window B
@end itemize

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).

@item occlude
A window is @emph{occluded} if some other window occludes it. For
example, window A occludes window B if:
@itemize @bullet

@item  Both windows are mapped

@item  Window A is higher in the global stacking order than window B

@item  The rectangle defined by the outside edges of window A intersects the rectangle
defined by the outside edges of window B
@end itemize

Notice that window borders are included in the calculation. See
obscure (there is a fine distinction between occlude and obscure).

@item override-shell
A subclass of @var{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.

@item 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.

@item parent window
If C is a child of P, then P is the @emph{parent} of C.

@item passive grab
Grabbing a key or button is a @emph{passive grab}. The grab activates
when the key or button is actually pressed.

@item pixel value
An @emph{n}-bit value, where @emph{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.

@item 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 (2@emph{n})-1, where @emph{n} is the depth (z axis) of
the pixmap. A pixmap can also be thought of as a stack of @emph{n}
bitmaps.

@item plane
When a pixmap or window is thought of as a stack of bitmaps, each
bitmap is called a @emph{plane} or @emph{bit plane}.

@item plane mask
Graphics operations can be restricted to only affect a subset of bit
planes of a destination.  A @emph{plane mask} is a bit mask describing
which planes are to be modified, and it is stored in a graphics
context.

@item pointer
The pointing device attached to the cursor and tracked on the screens.

@item pointer grabbing
A client can actively @emph{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.

@item 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.

@item 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 @var{state}
of a shell to @var{:mapped} is sometimes referred to as
@emph{mapping} or @emph{popping up} the shell. Setting the
@var{state} of a shell to @var{:withdrawn} or @var{:iconic} is
sometimes referred to as @emph{unmapping} or @emph{popping down} the
shell.

@item property
Windows can have associated @emph{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.

@item property list
The list of properties that have been defined for a window.

@item 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.

@item realization
See contact realization.

@item 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 @emph{redirected}
to a specified client, rather than the operation actually being
performed.

@item reply
Information requested by a client program is sent back to the client
with a @emph{reply}. Both events and replies are multiplexed on the
same connection. Most requests do not generate replies. However, some
requests generate multiple replies.

@item 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.

@item request
A command to the server is called a @emph{request}. It is a single
block of data sent over a connection.

@item resource
A value of the user interface that can be changed by the user in a
resource database via CLX functions @var{add-resource},
@var{get-resource}, and so forth. See server resource.

@item resource class, complete
See complete resource class.

@item 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.

@item resource name, complete
See complete resource name.

@item RGB values
@emph{Red}, @emph{green}, and @emph{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.

@item root
A special composite contact used to represent an entire display
screen.

@item root window
Each screen has a @emph{root window} covering it. It cannot be
reconfigured or unmapped, but otherwise acts as a full-fledged
window. A root window has no parent.

@item save set
The @emph{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.

@item 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.

@item scanline order
An image represented in @emph{scanline order} contains scanlines
ordered by increasing y coordinate.

@item screen
A server can provide several independent @emph{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.

@item selection

A @emph{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 @emph{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 @emph{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.

@item 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.

@item server
The @emph{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.

@item server grabbing
The server can be @emph{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.

@item 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.

@item shell
A composite that handles the duties required by standard conventions
for top-level X windows.

@item sibling
Children of the same parent window are known as @emph{sibling}
windows.

@item static color
A degenerate case of pseudo color in which the RGB values are
predefined and read-only.

@item 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.

@item stacking order
Sibling windows can @emph{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
@emph{stacking order}.

@item state
A slot of @var{contact} that controls the visual effect of the
contact.

@item 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.

@item tile
A pixmap can be replicated in two dimensions to @emph{tile} a
region. The pixmap itself is also known as a tile.

@item timer
A CLUE object that provides support for animation and other types of
time-sensitive user interfaces. A timer causes @var{:timer} events to
be dispatched to a specific contact for processing.

@item 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.

@item 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.

@item top-level-session
A subclass of @var{shell} that is used to communicate with a session
manager.

@item top-level-shell
A subclass of @var{shell} that provides full window manager
interaction.

@item transient-shell
A subclass of @var{shell} that a window manager typically will unmap
when its owner becomes unmapped or iconified and will not allow to be
individually iconified.

@item 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.

@item 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.

@item unmanaged
A contact that is not under geometry management control.

@item user interface
A set of abstract interface objects used to control the dialog between
an application and its human user.

@item viewable
A window is @emph{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.

@item visible
A region of a window is @emph{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.

@item 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 @emph{window gravity}.

@item window manager
Manipulation of windows on the screen, and much of the user interface
(policy) is typically provided by a @emph{window manager} client.

@item window manager shell
A subclass of @var{shell} called @var{wm-shell} that interacts with
the window manager.

@item XY Format
The data for a pixmap is said to be in @emph{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.

@item Z Format
The data for a pixmap is said to be in @emph{Z Format} if it is
organized as a set of pixel values in scanline order.
@end table

@node Function Index, Type Index, Glossary, Top
@appendix Function Index

@printindex fn

@node Type Index,  , Function Index, Top
@appendix Type Index

@printindex tp

@bye
