← Back to branch summary

~ubuntu-branches/ubuntu/intrepid/ecl/intrepid

« back to all changes in this revision

Viewing changes to src/clx/manual/clx.texinfo

  • Committer: Bazaar Package Importer
  • Author(s): Peter Van Eynde
  • Date: 2006-05-17 02:46:26 UTC
  • Revision ID: james.westby@ubuntu.com-20060517024626-lljr08ftv9g9vefl
Tags: upstream-0.9h-20060510
Import upstream version 0.9h-20060510

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/clx/manual/clx.texinfo
 
1
\input texinfo   @c -*-texinfo-*-
 
2
@c $Id: clx.texinfo,v 1.3 2005/05/19 11:31:18 jjgarcia Exp $
 
3
@c %**start of header
 
4
@setfilename clx.info
 
5
@settitle Common LISP X Interface
 
6
@setchapternewpage odd
 
7
@c %**end of header
 
8
 
 
9
@dircategory Lisp Programming
 
10
@direntry
 
11
* CLX: (clx).           Common LISP X Interface
 
12
@end direntry
 
13
 
 
14
 
 
15
@titlepage
 
16
@title The Common Lisp X Interface (CLX)
 
17
 
 
18
@page
 
19
@vskip 0pt plus 1filll
 
20
@c @copying
 
21
The Common LISP X Interface (CLX)
 
22
 
 
23
Copyright @copyright{} 1988, 1989 Texas Instruments Incorporated
 
24
 
 
25
@quotation
 
26
Permission is granted to any individual or institution to use, copy,
 
27
modify and distribute this document, provided that this complete
 
28
copyright and permission notice is maintained, intact, in all copies
 
29
and supporting documentation. Texas Instruments Incorporated makes no
 
30
representations about the suitability of this document or the software
 
31
described herein for any purpose. It is provided "as is" without
 
32
express or implied warranty.
 
33
@end quotation
 
34
 
 
35
@c @end copying
 
36
@end titlepage
 
37
 
 
38
@contents
 
39
 
 
40
@ifnottex
 
41
@node Top, Acknowledgments, (dir), (dir)
 
42
@top The Common LISP X Interface (CLX)
 
43
 
 
44
@c @copying
 
45
The Common LISP X Interface (CLX)
 
46
 
 
47
Copyright @copyright{} 1988, 1989 Texas Instruments Incorporated
 
48
 
 
49
@quotation
 
50
Permission is granted to any individual or institution to use, copy,
 
51
modify and distribute this document, provided that this complete
 
52
copyright and permission notice is maintained, intact, in all copies
 
53
and supporting documentation. Texas Instruments Incorporated makes no
 
54
representations about the suitability of this document or the software
 
55
described herein for any purpose. It is provided "as is" without
 
56
express or implied warranty.
 
57
@end quotation
 
58
 
 
59
@c @end copying
 
60
@end ifnottex
 
61
 
 
62
@menu
 
63
* Acknowledgments::
 
64
* Introduction to CLX::
 
65
* Displays::
 
66
* Screens::
 
67
* Windows and Pixmaps::
 
68
* Graphics Contexts::
 
69
* Graphic Operations::
 
70
* Images::
 
71
* Font and Characters::
 
72
* Colors::
 
73
* Cursors::
 
74
* Atoms::
 
75
* Events and Input::
 
76
* Resources::
 
77
* Control Functions::
 
78
* Extensions::
 
79
* Errors::
 
80
* Undocumented::
 
81
* Glossary::
 
82
* Function Index::
 
83
* Type Index::
 
84
 
 
85
@detailmenu
 
86
 --- The Detailed Node Listing ---
 
87
 
 
88
Introduction to CLX
 
89
 
 
90
* The X Window System::
 
91
* A Quick Tour of CLX::
 
92
* Naming and Argument Conventions::
 
93
* Programming Considerations::
 
94
* Data Types::
 
95
 
 
96
The X Window System
 
97
 
 
98
* Windows::
 
99
* Input Events::
 
100
 
 
101
A Quick Tour of CLX
 
102
 
 
103
* A Simple Menu::
 
104
* Displaying the Menu::
 
105
* Menu Input::
 
106
* The Main Program::
 
107
* Debugging With CLX::
 
108
 
 
109
Displays
 
110
 
 
111
* Opening the Display::
 
112
* Display Attributes::
 
113
* Managing the Output Buffer::
 
114
* Closing the Display::
 
115
 
 
116
Screens
 
117
 
 
118
* Screens and Visuals::
 
119
* Screen Attributes::
 
120
 
 
121
Windows and Pixmaps
 
122
 
 
123
* Drawables::
 
124
* Creating Windows::
 
125
* Window Attributes::
 
126
* Stacking Order::
 
127
* Window Hierarchy::
 
128
* Mapping Windows::
 
129
* Destroying Windows::
 
130
* Pixmaps::
 
131
 
 
132
Graphics Contexts
 
133
 
 
134
* Creating Graphics Contexts::
 
135
* Graphics Context Attributes::
 
136
* Copying Graphics Contexts::
 
137
* Destroying Graphics Contexts::
 
138
* Graphics Context Cache::
 
139
 
 
140
Graphic Operations
 
141
 
 
142
* Area and Plane Operations::
 
143
* Drawing Points::
 
144
* Drawing Lines::
 
145
* Drawing Rectangles::
 
146
* Drawing Arcs::
 
147
* Drawing Text::
 
148
 
 
149
Images
 
150
 
 
151
* Image Types::
 
152
* Image Functions::
 
153
* Image Files::
 
154
* Direct Image Transfer::
 
155
 
 
156
Image Types
 
157
 
 
158
* Basic Images::
 
159
* XY-Format Images::
 
160
* Z-Format Images::
 
161
 
 
162
Font and Characters
 
163
 
 
164
* Opening Fonts::
 
165
* Listing Fonts::
 
166
* Font Attributes::
 
167
* Chracter Attributes::
 
168
* Querying Text Size::
 
169
 
 
170
Colors
 
171
 
 
172
* Colormaps and Colors::
 
173
* Color Functions::
 
174
* Colormap Functions::
 
175
 
 
176
Colormap Functions
 
177
 
 
178
* Creating Colormaps::
 
179
* Installing Colormaps::
 
180
* Allocating Colors::
 
181
* Finding Colors::
 
182
* Changing Colors::
 
183
* Colormap Attributes::
 
184
 
 
185
Cursors
 
186
 
 
187
* Creating Cursors::
 
188
* Cursor Functions::
 
189
* Cursor Attributes::
 
190
 
 
191
Atoms, Properties and Selections
 
192
 
 
193
* Atoms (Atoms)::
 
194
* Properties::
 
195
* Selections::
 
196
 
 
197
Events and Input
 
198
 
 
199
* Selecting Events::
 
200
* Processing Events::
 
201
* Managing the Event Queue::
 
202
* Sending Events::
 
203
* Pointer Position::
 
204
* Managing Input Focus::
 
205
* Grabbing the Pointer::
 
206
* Grabbing a Button::
 
207
* Grabbing the Keyboard::
 
208
* Grabbing a Key::
 
209
* Event Types::
 
210
* Releasing Queued Events::
 
211
 
 
212
Event Types
 
213
 
 
214
* Keyboard and Pointer Events::
 
215
* Input Focus Events::
 
216
* Keyboard and Pointer State Events::
 
217
* Exposure Events::
 
218
* Window State Events::
 
219
* Structure Control Events::
 
220
* Client Communications Events::
 
221
* Declaring Event Types::
 
222
 
 
223
Resources
 
224
 
 
225
* Resource Binings::
 
226
* Basic Resource Database Functions::
 
227
* Accessing Resource Values::
 
228
* Resource Database Files::
 
229
 
 
230
Accessing Resource Values
 
231
 
 
232
* Complete Names and Classes::
 
233
* Matching Resource Names::
 
234
* Resource Access Functions::
 
235
 
 
236
Control Functions
 
237
 
 
238
* Grabbing the Server::
 
239
* Pointer Control::
 
240
* Keyboard Control::
 
241
* Keyboard Encodings::
 
242
* Client Termination::
 
243
* Managing Host Access::
 
244
* Screen Saver::
 
245
 
 
246
Keyboard Encodings
 
247
 
 
248
* Keycodes and Keysyms::
 
249
* Keyboard Mapping::
 
250
* Using Keycodes and Keysyms::
 
251
 
 
252
Extensions
 
253
 
 
254
* Extensions (Extensions)::
 
255
* SHAPE - The X11 Nonrectangular Window Shape Extension::
 
256
* RENDER - A new rendering system for X11::
 
257
 
 
258
RENDER - A new rendering system for X11
 
259
 
 
260
* Picture formats::
 
261
* The picture object::
 
262
* Glyphs and Glyphsets::
 
263
* Using glyphs::
 
264
* Errors (Extensions)::
 
265
 
 
266
Errors
 
267
 
 
268
* Introduction (Errors)::
 
269
 
 
270
@end detailmenu
 
271
@end menu
 
272
 
 
273
@node Acknowledgments, Introduction to CLX, Top, Top
 
274
@chapter Acknowledgments
 
275
 
 
276
Primary Interface Author:
 
277
 
 
278
Robert W. Scheifler
 
279
 
 
280
@display
 
281
MIT Laboratory for Computer Science
 
282
545 Technology Square, Room 418
 
283
Cambridge, MA 02139
 
284
@email{rws@@zermatt.lcs.mit.edu}
 
285
@end display
 
286
 
 
287
Primary Implementation Author:
 
288
 
 
289
LaMott Oren
 
290
 
 
291
@display
 
292
Texas Instruments
 
293
PO Box 655474, MS 238
 
294
Dallas, TX 75265
 
295
@email{oren@@csc.ti.com}
 
296
@end display
 
297
 
 
298
 
 
299
 
 
300
Design Contributors:
 
301
 
 
302
@itemize @bullet
 
303
@item Dan Cerys, BBN
 
304
@item Scott Fahlman, CMU
 
305
@item Kerry Kimbrough, Texas Instruments
 
306
@item Chris Lindblad, MIT
 
307
@item Rob MacLachlan, CMU
 
308
@item Mike McMahon, Symbolics
 
309
@item David Moon, Symbolics
 
310
@item LaMott Oren, Texas Instruments
 
311
@item Daniel Weinreb, Symbolics
 
312
@item John Wroclawski, MIT
 
313
@item Richard Zippel, Symbolics
 
314
@end itemize
 
315
 
 
316
Documentation Contributors:
 
317
 
 
318
@itemize @bullet
 
319
@item Keith Cessna, Texas Instruments
 
320
@item Kerry Kimbrough, Texas Instruments
 
321
@item Mike Myjak
 
322
@item LaMott Oren, Texas Instruments
 
323
@item Dan Stenger, Texas Instruments
 
324
@end itemize
 
325
 
 
326
The X Window System is a trademark of MIT.
 
327
 
 
328
UNIX is a trademark of AT&T Bell Laboratories.
 
329
 
 
330
ULTRIX, ULTRIX-32, ULTRIX-32m, ULTRIX-32w, and VAX/VMS are trademarks of Digital Equipment
 
331
Corporation.
 
332
 
 
333
@node Introduction to CLX, Displays, Acknowledgments, Top
 
334
@chapter Introduction to CLX
 
335
 
 
336
This manual assumes a basic understanding of window systems and the Common Lisp programming
 
337
language. To provide an introduction to the Common Lisp X Interface (CLX) programming, this
 
338
section discusses the following:
 
339
 
 
340
@itemize @bullet
 
341
@item Overview of the X Window System
 
342
@item Naming and argument conventions
 
343
@item Programming considerations
 
344
@end itemize
 
345
 
 
346
@menu
 
347
* The X Window System::
 
348
* A Quick Tour of CLX::
 
349
* Naming and Argument Conventions::
 
350
* Programming Considerations::
 
351
* Data Types::
 
352
@end menu
 
353
 
 
354
@node The X Window System, A Quick Tour of CLX, Introduction to CLX, Introduction to CLX
 
355
@section The X Window System
 
356
 
 
357
The X Window System was developed at the Massachusetts Institute of
 
358
Technology (MIT) and first released in 1985. Since then, the X Window
 
359
System has become an industry-standard product available on virtually
 
360
every type of bit-mapped workstation. The current version of X,
 
361
Version 11, has been implemented for several different computer
 
362
architectures, for a wide variety of display hardware, and also for
 
363
many different operating systems. X Version 11 represents the
 
364
fulfillment of the original design goals proposed by MIT, as follows:
 
365
 
 
366
@table @asis
 
367
@item Portable
 
368
Support virtually any bitmap display and any interactive input device
 
369
(including keyboards, mice, tablets, joysticks, and touch screens).
 
370
Make it easy to implement the window system on different operating
 
371
systems.
 
372
 
 
373
@item Device-Independent Applications
 
374
Avoid rewriting, recompiling, or even relinking in order to use
 
375
different display/input hardware. Make it easy for an application to
 
376
work on both monochrome and color hardware.
 
377
 
 
378
@item Network Transparent
 
379
Let an application run on one computer while using another computer's
 
380
display, even if the other computer has a different operating system
 
381
or hardware architecture.
 
382
 
 
383
@item Multitasking
 
384
Support multiple applications being displayed simultaneously.
 
385
 
 
386
@item No User Interface Policy
 
387
 
 
388
Since no one agrees on what constitutes the best user interface, make
 
389
it possible for a broad range of user interface styles (or policies)
 
390
to be implemented, external to the window system and to the
 
391
application programs.
 
392
 
 
393
@item Cheap Windows
 
394
Windows should be abundant, and ubiquitous. Provide overlapping
 
395
windows and a simple mechanism for window hierarchy.
 
396
 
 
397
@item High-Performance Graphics
 
398
Provide powerful interfaces for synthesizing 2-D images (geometric
 
399
primitives, high-quality text with multiple typefaces, and scanned
 
400
images).
 
401
 
 
402
@item Extensible
 
403
Include a mechanism for adding new capabilities. Allow separate sites
 
404
to develop independent extensions without becoming incompatible with
 
405
remote applications.
 
406
@end table
 
407
 
 
408
Some of these goals lead directly to the basic X architecture -- the
 
409
client-server model. The basic window system is implemented by the X
 
410
@emph{server} program. An application program (the @emph{client})
 
411
sends window system @emph{requests} to the X server through a reliable
 
412
two-way byte-stream.
 
413
 
 
414
In general, the server and the client can be executing on separate
 
415
host computers, in which case the byte-stream is implemented via some
 
416
network protocol (TCP, DECnet(tm), Chaosnet, and so
 
417
forth). The X server, which is connected to several client programs
 
418
running concurrently, executes client requests in round-robin
 
419
fashion. The server is responsible for drawing client graphics on the
 
420
display screen and for making sure that graphics output to a window
 
421
stays inside its boundary.
 
422
 
 
423
The other primary job of the X server is to channel input from the
 
424
keyboard, pointer, and other input devices back to the appropriate
 
425
client programs. Input arrives at the client asynchronously in the
 
426
form of input @emph{events} representing up/down transitions of keys
 
427
or pointer buttons, changes in the pointer position, and so on. In
 
428
some cases, a request generates a return value (or @emph{reply}) from
 
429
the server, which is another kind of client input. Replies and input
 
430
events are received via the same byte-stream connecting the client
 
431
with the server.
 
432
 
 
433
@menu
 
434
* Windows::
 
435
* Input Events::
 
436
@end menu
 
437
 
 
438
@node Windows, Input Events, The X Window System, The X Window System
 
439
@subsection Windows
 
440
 
 
441
The X Window System supports one or more screens containing
 
442
overlapping windows and subwindows. A @emph{screen} is a physical
 
443
monitor and hardware, which can be either color or black and
 
444
white. There can be multiple screens per display workstation. A single
 
445
server can provide display services for any number of screens. A set
 
446
of screens for a single user with one keyboard and one mouse is called
 
447
a @emph{display}.
 
448
 
 
449
All windows in an X server are arranged in a strict hierarchy. At the
 
450
top of the hierarchy are the @emph{root windows}, which cover each of
 
451
the display screens. Each root window is either partially or
 
452
completely covered by child windows. All windows, except for root
 
453
windows, have parents. Any window can in turn have its own
 
454
children. In this way, an application program can create a window tree
 
455
of arbitrary depth on each screen.
 
456
 
 
457
A child window can be larger than its parent. That is, part or all of
 
458
the child window can extend beyond the boundaries of the parent.
 
459
However, all output to a window is clipped by the boundaries of its
 
460
parent window. If several children of a window have overlapping
 
461
locations, one of the children is considered to be on top of/or raised
 
462
over the others, @emph{obscuring} them. Window output to areas that
 
463
are covered by other windows is suppressed.
 
464
 
 
465
A window has a border that is zero or more pixels in width and can be
 
466
any pattern (pixmap) or solid color. A window usually has a background
 
467
pattern that is drawn by the X server. Each window has its own
 
468
coordinate system. Child windows obscure their parents unless the
 
469
child windows have no background. Graphics operations in the parent
 
470
window are usually clipped by the children.
 
471
 
 
472
X also provides objects called @emph{pixmaps} for off-screen storage
 
473
of graphics. Single-plane pixmaps (that is, of depth 1) are sometimes
 
474
referred to as @emph{bitmaps}. Both pixmaps and windows can be used
 
475
interchangeably in most graphics functions. Pixmaps are also used in
 
476
various graphics operations to define patterns, or
 
477
@emph{tiles}. Windows and pixmaps together are referred to as
 
478
@emph{drawables}.
 
479
 
 
480
@node Input Events,  , Windows, The X Window System
 
481
@subsection Input Events
 
482
 
 
483
The X input mechanism is conceptually simple yet quite powerful. Most
 
484
events are attached to a particular window (that is, contain an
 
485
identifier for the window receiving the event). A client program can
 
486
receive multiple window input streams, all multiplexed over the single
 
487
byte-stream connection to the server.
 
488
 
 
489
Clients can tailor their input by expressing interest in only certain
 
490
event types. The server uses special event types to send important
 
491
messages to the client. For example, the client can elect to receive
 
492
an @var{:enter-notify}
 
493
(@pxref{:enter-notify}) event
 
494
when the pointer cursor moves into a certain window. Another vital
 
495
message from the server is an @var{:exposure}
 
496
(@pxref{:exposure}) event. This is a
 
497
signal to the client indicating that at least some portion of the
 
498
window has suddenly become visible (perhaps the user moved another
 
499
window which had been overlapping it). The client is then responsible
 
500
for doing what is necessary to redisplay the window's image.  Client
 
501
programs must be prepared to regenerate the contents of windows in
 
502
this way on demand.
 
503
 
 
504
Input is also subject to policy decisions about which client window
 
505
receives keyboard and pointer events. Since the pointer is free to roam
 
506
between windows, just clicking on a window is often enough to send a
 
507
pointer event to that window. Keyboard events, however, must go to a
 
508
keyboard focus window which has to be designated in some other way.
 
509
Usually, the arbiter of such input management policy is a program called
 
510
the @emph{window manager}. The window manager gives the human
 
511
user a way to make a window the keyboard focus, to manage the layout of
 
512
windows on the screen, to represent windows with icons, and so forth. In
 
513
fact, the window manager client determines most of the so-called look
 
514
and feel of the X Window System.
 
515
 
 
516
@node A Quick Tour of CLX, Naming and Argument Conventions, The X Window System, Introduction to CLX
 
517
@section A Quick Tour of CLX
 
518
 
 
519
The X Window System is defined by the X Window System Protocol
 
520
Specification, a detailed description of the encoding and the meaning of
 
521
requests and events sent between a client and a server. This standard
 
522
protocol does not depend on any particular programming language. As a
 
523
result, each programming language must define its own functional
 
524
interface for using the X protocol. The standard X interface used by
 
525
Common Lisp programmers is called CLX. CLX is a set of data types,
 
526
functions, and macros which allow a Common Lisp client program to
 
527
interact with an X server to send requests and to receive input events
 
528
and replies.
 
529
 
 
530
For the most part, CLX functions are closely tied to the underlying
 
531
requests in the X protocol. Many CLX functions simply add requests to an
 
532
output buffer. These requests later execute asynchronously on the X
 
533
display server. However, some functions of CLX lie outside the scope of
 
534
the protocol--for example, reading events and managing a clientside
 
535
event queue. CLX is also responsible for important batching and caching
 
536
tasks that minimize network communication.
 
537
 
 
538
The following paragraphs show an example of a CLX client program. All
 
539
CLX functions and macros are shown in upper case. Note that some of the
 
540
terms used are unique to X, while other terms that are common to other
 
541
window systems have different meanings in X. It may be helpful to refer
 
542
to the glossary when you are uncertain of a term's meaning in the
 
543
context of the X Window System.
 
544
 
 
545
@menu
 
546
* A Simple Menu::
 
547
* Displaying the Menu::
 
548
* Menu Input::
 
549
* The Main Program::
 
550
* Debugging With CLX::
 
551
@end menu
 
552
 
 
553
@node A Simple Menu, Displaying the Menu, A Quick Tour of CLX, A Quick Tour of CLX
 
554
@subsection A Simple Menu
 
555
 
 
556
The example client program creates and displays a simple pop-up menu
 
557
consisting of a column of strings--a title string followed by selectable
 
558
menu item strings. The implementation uses one window to represent the
 
559
entire menu, plus a set of subwindows, one for each menu item. Here is
 
560
the definition of a structure which represents such a menu.
 
561
 
 
562
@lisp
 
563
(defstruct (menu)
 
564
  "A simple menu of text strings."
 
565
  (title "Choose an item:")
 
566
  item-alist                            ;((item-window item-string))
 
567
  window
 
568
  gcontext
 
569
  width
 
570
  title-width
 
571
  item-width
 
572
  item-height
 
573
  (geometry-changed-p t))            ;nil if unchanged since displayed
 
574
@end lisp
 
575
 
 
576
 
 
577
The @code{window} slot will contain the
 
578
@var{window} (@pxref{window})
 
579
object that represents the menu. The @code{item-}
 
580
@code{alist} represents the relationship between the menu items
 
581
and their associated subwindows. Each entry in @code{item-alist}
 
582
is a list whose first element is a (sub)window object and whose second
 
583
element is the corresponding item string. A
 
584
@var{window} (@pxref{window})
 
585
object is an instance of a CLX-defined data type which represents X
 
586
windows. A
 
587
@var{window} (@pxref{window})
 
588
object actually carries two pieces of information: an X window ID
 
589
integer and a
 
590
@var{display} (@pxref{display})
 
591
object. A
 
592
@var{display} (@pxref{display})
 
593
is another CLX-defined data type that represents a connection to a
 
594
specific X display server. The @code{gcontext} slot contains an
 
595
instance of a CLX data type known as a @emph{graphics context}. A
 
596
graphics context is a set of display attribute values, such as
 
597
foreground color, fill style, line style, text font, and so forth. Each
 
598
X graphics request (and hence each CLX graphics function call) must
 
599
supply a graphics context to use in displaying the request. The menu's
 
600
@code{gcontext} will thus hold all of the attribute values used
 
601
during menu display.
 
602
 
 
603
The first thing to do is make an instance of a @code{menu} object:
 
604
 
 
605
@lisp
 
606
(defun create-menu (parent-window text-color background-color text-font)
 
607
  (make-menu
 
608
   ;; Create menu graphics context
 
609
   :gcontext (CREATE-GCONTEXT :drawable   parent-window
 
610
                              :foreground text-color
 
611
                              :background background-color
 
612
                              :font       text-font)
 
613
 
 
614
   ;; Create menu window
 
615
   :window    (CREATE-WINDOW
 
616
               :parent            parent-window
 
617
               :class             :input-output
 
618
               :x                 0     ;temporary value
 
619
               :y                 0     ;temporary value
 
620
               :width             16    ;temporary value
 
621
               :height            16    ;temporary value
 
622
               :border-width 2
 
623
               :border            text-color
 
624
               :background        background-color
 
625
               :save-under        :on
 
626
               :override-redirect :on ;override window mgr when positioning
 
627
               :event-mask        (MAKE-EVENT-MASK :leave-window :exposure))))
 
628
@end lisp
 
629
 
 
630
@var{create-window} (@pxref{create-window})
 
631
is one of the most important CLX functions, since it creates and returns
 
632
a @var{window} (@pxref{window})
 
633
object. Several of its options are shown here. The default window class
 
634
is @var{:input-output}, but X provides for @var{:input-only} windows,
 
635
too. Every window must have a parent window, except for a system-defined
 
636
@emph{root window}, which represents an entire display screen. The
 
637
@var{:event-mask} keyword value, a CLX
 
638
@var{event-mask} (@pxref{event-mask})
 
639
data type, says that an input event will be received for the menu window
 
640
when the window is exposed and also when the pointer cursor leaves the
 
641
window. The window border is a pattern-filled or (as in this case) a
 
642
solid-colored boundary which is maintained automatically by the X
 
643
server; a client cannot draw in a window's border, since all graphics
 
644
requests are relative to the origin (upper-left corner) of the window's
 
645
interior and are clipped by the server to this inside region. Turning on
 
646
the @var{:save-under} option is a hint to the X server that, when this
 
647
window is made visible, it may be more efficient to save the pixels it
 
648
obscures, rather than require several client programs to refresh their
 
649
windows when the pop-up menu disappears. This is a way to work around
 
650
X's client-managed refresh policy when only a small amount of screen
 
651
space is needed temporarily.
 
652
 
 
653
Why is @var{:override-redirect} turned on for the menu window? This is
 
654
actually a little unusual, because it prevents any window manager client
 
655
from @emph{redirecting} the position of the menu when it is popped up.
 
656
Remember that the window manager represents the user's policy for
 
657
controlling the positions of his windows, so this kind of redirection is
 
658
ordinarily correct. However, in this case, as a favor to the user, the
 
659
menu avoids redirection in order to pop up the menu at a very specific
 
660
location; that is, under the pointer cursor.
 
661
 
 
662
What about the item subwindows? The @code{menu-set-item-list}
 
663
function in the following example creates them whenever the menu's item
 
664
list is changed. The upper-left x and y coordinates and the width and
 
665
height are not important yet, because they are computed just before the
 
666
menu is displayed. This function also calls
 
667
@var{create-window} (@pxref{create-window}),
 
668
demonstrating the equal treatment of parent and children windows in the
 
669
X window hierarchy.
 
670
 
 
671
@lisp
 
672
(defun menu-set-item-list (menu &rest item-strings)
 
673
  ;; Assume the new items will change the menu's width and height
 
674
  (setf (menu-geometry-changed-p menu) t)
 
675
 
 
676
  ;; Destroy any existing item windows
 
677
  (dolist (item (menu-item-alist menu))
 
678
    (DESTROY-WINDOW (first item)))
 
679
 
 
680
  ;; Add (item-window item-string) elements to item-alist
 
681
  (setf (menu-item-alist menu)
 
682
        (let (alist)
 
683
          (dolist (item item-strings (nreverse alist))
 
684
            (push (list (CREATE-WINDOW
 
685
                         :parent       (menu-window menu)
 
686
                         :x            0 ;temporary value
 
687
                         :y            0 ;temporary value
 
688
                         :width        16 ;temporary value
 
689
                         :height       16 ;temporary value
 
690
                         :background   (GCONTEXT-BACKGROUND (menu-gcontext menu))
 
691
                         :event-mask   (MAKE-EVENT-MASK :enter-window
 
692
                                                        :leave-window
 
693
                                                        :button-press
 
694
                                                        :button-release))
 
695
                        item)
 
696
                  alist)))))
 
697
@end lisp
 
698
 
 
699
@node Displaying the Menu, Menu Input, A Simple Menu, A Quick Tour of CLX
 
700
@subsection Displaying the Menu
 
701
 
 
702
The @code{menu-recompute-geometry} function (shown in the
 
703
following example) handles the job of calculating the size of the menu,
 
704
based on its current item list and its current text font. CLX provides a
 
705
way to inquire the geometrical properties of a font object (for example,
 
706
its ascent and descent from the baseline) and also a
 
707
@var{text-extents} (@pxref{text-extents})
 
708
function.
 
709
@var{text-extents} (@pxref{text-extents})
 
710
returns the geometry of a given string as displayed in a given font.
 
711
Notice the use of the
 
712
@var{with-state} (@pxref{with-state})
 
713
macro when setting a window's geometry attributes. CLX strives to
 
714
preserve the familiar @code{setf} style of accessing individual window
 
715
attributes, even though an attribute access actually involves sending a
 
716
request to a (possibly remote) server and/or waiting for a reply.
 
717
@var{with-state} (@pxref{with-state})
 
718
tells CLX to batch together all read and write accesses to a given
 
719
window, using a local cache to minimize the number of server requests.
 
720
This CLX feature can result in a dramatic improvement in client
 
721
performance without burdening the programmer interface.
 
722
 
 
723
@code{menu-recompute-geometry} causes all the item subwindows to
 
724
become @emph{mapped}. Mapping a window means attempting to make it
 
725
visible on the screen. However, a subwindow will not actually be
 
726
@emph{visible} until it and all of its ancestors are mapped. Even then,
 
727
another window might be covering up the subwindow.
 
728
 
 
729
@lisp
 
730
(defun menu-recompute-geometry (menu)
 
731
  (when (menu-geometry-changed-p menu)
 
732
    (let* ((menu-font   (GCONTEXT-FONT (menu-gcontext menu)))
 
733
           (title-width (TEXT-EXTENTS menu-font (menu-title menu)))
 
734
           (item-height (+ (FONT-ASCENT menu-font)
 
735
                           (FONT-DESCENT menu-font)
 
736
                           *menu-item-margin*))
 
737
           (item-width     0)
 
738
           (items          (menu-item-alist menu))
 
739
           menu-width)
 
740
 
 
741
      ;; Find max item string width
 
742
      (setf item-width
 
743
            (+ *menu-item-margin*
 
744
               (dolist (next-item items item-width)
 
745
                 (setf item-width (max item-width
 
746
                                       (TEXT-EXTENTS menu-font (second next-item)))))))
 
747
 
 
748
      ;; Compute final menu width, taking margins into account
 
749
      (setf menu-width (max title-width (+ item-width *menu-item-margin*)))
 
750
      (let ((window     (menu-window menu)))
 
751
 
 
752
        ;; Update width and height of menu window
 
753
        (WITH-STATE (window)
 
754
                    (setf (DRAWABLE-WIDTH      window) menu-width
 
755
                          (DRAWABLE-HEIGHT window) (* (1+ (length items)) item-height)))
 
756
 
 
757
        ;; Update width, height, position of item         windows
 
758
        (let ((item-left         (round (- menu-width item-width) 2))
 
759
              (next-item-top (- item-height (round *menu-item-margin* 2))))
 
760
          (dolist (next-item items)
 
761
            (let ((window (first next-item)))
 
762
              (WITH-STATE (window)
 
763
                          (setf (DRAWABLE-HEIGHT window) item-height
 
764
                                (DRAWABLE-WIDTH      window) item-width
 
765
                                (DRAWABLE-X          window) item-left
 
766
                                (DRAWABLE-Y          window) next-item-top)))
 
767
            (incf next-item-top item-height))))
 
768
 
 
769
      ;; Map all item windows
 
770
      (MAP-SUBWINDOWS (menu-window menu))
 
771
 
 
772
      ;; Save item geometry
 
773
      (setf (menu-item-width menu)         item-width
 
774
            (menu-item-height menu)        item-height
 
775
            (menu-width menu)              menu-width
 
776
            (menu-title-width menu)        title-width
 
777
            (menu-geometry-changed-p menu) nil))))
 
778
@end lisp
 
779
 
 
780
Of course, the sample client must know how to draw/redraw the menu and
 
781
its items, so the function @code{menu-refresh} is defined next to
 
782
handle that task (shown in the following example). Note that the
 
783
location of window output is given relative to the window origin.
 
784
Windows and subwindows have different coordinate systems. The location
 
785
of the origin (upper-left corner) of a subwindow's coordinate system is
 
786
given with respect to its parent window's coordinate system. Negative
 
787
coordinates are valid, although only output to the +x/+y quadrant of a
 
788
window's coordinate system will ever be visible.
 
789
 
 
790
@lisp
 
791
(defun menu-refresh (menu)
 
792
  (let* ((gcontext   (menu-gcontext menu))
 
793
         (baseline-y (FONT-ASCENT (GCONTEXT-FONT gcontext))))
 
794
    ;; Show title centered in "reverse-video"
 
795
    (let ((fg (GCONTEXT-BACKGROUND gcontext))
 
796
          (bg (GCONTEXT-FOREGROUND gcontext)))
 
797
      (WITH-GCONTEXT (gcontext :foreground fg :background bg)
 
798
                     (DRAW-IMAGE-GLYPHS
 
799
                      (menu-window menu)
 
800
                      gcontext
 
801
                      (round (- (menu-width menu)
 
802
                                (menu-title-width menu)) 2) ;start x
 
803
                      baseline-y        ;start y
 
804
                      (menu-title menu))))
 
805
 
 
806
    ;; Show each menu item (position is relative to item window)
 
807
    (let ((box-margin (round *menu-item-margin* 2)))
 
808
      (dolist (item (menu-item-alist menu))
 
809
        (DRAW-IMAGE-GLYPHS
 
810
         (first item) gcontext
 
811
         box-margin                     ;start x
 
812
         (+ baseline-y box-margin)      ;start y
 
813
         (second item))))))
 
814
@end lisp
 
815
 
 
816
@var{with-gcontext} (@pxref{with-gcontext})
 
817
is a CLX macro that allows you temporarily to modify a graphics context
 
818
within the dynamic scope of the macro body.
 
819
@var{draw-image-glyphs} (@pxref{draw-image-glyphs})
 
820
is a CLX text drawing function which produces a terminal-like rendering:
 
821
foreground character on a background block. (More sophisticated text
 
822
rendering functions are also available.) The strange use of
 
823
@emph{glyphs} instead of @emph{string} here actually highlights an
 
824
important fact: X and Common Lisp have totally different concepts of a
 
825
character. A Common Lisp character is an object whose implementation can
 
826
comprehend a vast universe of text complexities (typefaces, type styles,
 
827
international character sets, symbols, and so forth). However, to X, a
 
828
string is just a sequence of integer indexes into the array of bitmaps
 
829
represented by a CLX font object. In general,
 
830
@var{draw-image-glyphs} (@pxref{draw-image-glyphs}),
 
831
@var{text-extents} (@pxref{text-extents}),
 
832
and other CLX text functions accept a @var{:translate} keyword
 
833
argument. Its value is a function which translates the characters of a
 
834
string argument into the appropriate font-and-index pairs needed by CLX.
 
835
This example relies upon the default translation function, which simply
 
836
uses @var{char-code} to compute an index into the current font.
 
837
 
 
838
@node Menu Input, The Main Program, Displaying the Menu, A Quick Tour of CLX
 
839
@subsection Menu Input
 
840
 
 
841
Now that a menu can be displayed, the sample client program must define
 
842
how the menu will process user input. The @code{menu-choose}
 
843
function (shown in the following example) has the classic structure of
 
844
an X client program. First, do some initialization (for example, present
 
845
the menu at a given location). Then, enter an input event loop. Read an
 
846
input event, process it, and repeat the loop until a termination event
 
847
is received. The
 
848
@var{event-case} (@pxref{event-case})
 
849
macro continues reading an event from the menu window's display object
 
850
until one of its clauses returns non-@var{nil}. These clauses specify
 
851
the action to be taken for each event type and also bind values from the
 
852
event report to local variables, such as the @var{event-window}
 
853
receiving the event. Notice that the @var{:force-output-p} option is
 
854
enabled, causing
 
855
@var{event-case} (@pxref{event-case})
 
856
to begin by sending any client requests which CLX has not yet output to
 
857
the server. To improve performance, CLX quietly queues up requests and
 
858
periodically sends them off in a batch. However, in an interactive
 
859
feedback loop such as this, it is important to keep the display crisply
 
860
up-to-date.
 
861
 
 
862
@lisp
 
863
(defun menu-choose (menu x y)
 
864
  ;; Display the menu so that first item is at x,y.
 
865
  (menu-present menu x y)
 
866
 
 
867
  (let ((items (menu-item-alist menu))
 
868
        (mw    (menu-window menu))
 
869
        selected-item)
 
870
 
 
871
    ;; Event processing loop
 
872
    (do () (selected-item)
 
873
      (EVENT-CASE ((DRAWABLE-DISPLAY mw) :force-output-p t)
 
874
                  (:exposure
 
875
                   (count)
 
876
                   ;; Discard all but final :exposure then display the menu
 
877
                   (when (zerop count) (menu-refresh menu))
 
878
                   t)
 
879
 
 
880
                  (:button-release
 
881
                   (event-window)
 
882
                   ;;Select an item
 
883
                   (setf selected-item (second (assoc event-window items)))
 
884
                   t)
 
885
 
 
886
                  (:enter-notify
 
887
                   (window)
 
888
                   ;;Highlight an item
 
889
                   (menu-highlight-item menu (find window items :key #'first))
 
890
                   t)
 
891
 
 
892
                  (:leave-notify
 
893
                   (window kind)
 
894
                   (if (eql mw window)
 
895
                       ;; Quit if pointer moved out of main menu window
 
896
                       (setf selected-item (when (eq kind :ancestor) :none))
 
897
                     ;; Otherwise, unhighlight the item window left
 
898
                     (menu-unhighlight-item menu (find window items :key #'first)))
 
899
                   t)
 
900
 
 
901
                  (otherwise
 
902
                   ()
 
903
                   ;;Ignore and discard any other event
 
904
                   t)))
 
905
 
 
906
    ;; Erase the menu
 
907
    (UNMAP-WINDOW mw)
 
908
 
 
909
    ;; Return selected item string, if any
 
910
    (unless (eq selected-item :none) selected-item)))
 
911
@end lisp
 
912
 
 
913
The event loop in @code{menu-choose} demonstrates an idiom used in
 
914
all X programs: the contents of a window are displayed (in this case, by
 
915
calling @code{menu-refresh}) only when an
 
916
@var{:exposure} (@pxref{:exposure})
 
917
event is received, signaling that the server has actually made the
 
918
window @emph{viewable}. The handling of
 
919
@var{:exposure} (@pxref{:exposure})
 
920
in @code{menu-choose} also implements a little trick for improving
 
921
efficiency. In general, when a window is exposed after being previously
 
922
obscured (perhaps only partially), the server is free to send several
 
923
@var{:exposure} (@pxref{:exposure})
 
924
events, one for each rectangular tile of the exposed region. For small
 
925
windows like this menu, it is not worth the trouble to redraw the image
 
926
one tile at a time. So the code above just ignores all but the last tile
 
927
exposure and redraws everything in one call to
 
928
@code{menu-refresh}.
 
929
 
 
930
@node The Main Program, Debugging With CLX, Menu Input, A Quick Tour of CLX
 
931
@subsection The Main Program
 
932
 
 
933
After all the preceding build-up and the other functions referenced
 
934
(but not shown here) have been implemented, the code for the main
 
935
client program is very small.
 
936
 
 
937
@lisp
 
938
(defun just-say-lisp (host &optional (font-name "fg-16"))
 
939
  (let* ((display   (OPEN-DISPLAY host))
 
940
         (screen    (first (DISPLAY-ROOTS display)))
 
941
         (fg-color  (SCREEN-BLACK-PIXEL screen))
 
942
         (bg-color  (SCREEN-WHITE-PIXEL screen))
 
943
         (nice-font (OPEN-FONT display font-name))
 
944
 
 
945
         ;; Create a menu as a child of the root window.
 
946
         (a-menu       (create-menu (SCREEN-ROOT screen)
 
947
                                    fg-color bg-color nice-font)))
 
948
 
 
949
    (setf (menu-title a-menu) "Please pick your favorite language:")
 
950
    (menu-set-item-list a-menu "Fortran" "APL" "Forth" "Lisp")
 
951
 
 
952
    ;; Bedevil the user until he picks a nice programming language
 
953
    (unwind-protect
 
954
        (loop
 
955
         ;; Determine the current root window position of the pointer
 
956
         (multiple-value-bind (x y) (QUERY-POINTER (SCREEN-ROOT screen))
 
957
 
 
958
           (let ((choice (menu-choose a-menu x y)))
 
959
             (when (string-equal "Lisp" choice)
 
960
               (return)))))
 
961
 
 
962
      (CLOSE-DISPLAY display))))
 
963
@end lisp
 
964
 
 
965
Note that the main program event loop lies in the body of an
 
966
@var{unwind-protect} form. This is a good programming technique
 
967
because, without this protection, an unexpected error could cause the
 
968
program to terminate without freeing the @emph{server resources} it has
 
969
created. Server resources are CLX objects which refer to objects
 
970
actually stored on the X server. Examples of these are
 
971
@var{window} (@pxref{window}),
 
972
@var{font} (@pxref{font}),
 
973
@var{pixmap} (@pxref{pixmap}),
 
974
@var{cursor} (@pxref{cursor}),
 
975
@var{colormap} (@pxref{colormap}),
 
976
and
 
977
@var{gcontext} (@pxref{gcontext})
 
978
objects. These server resources are created and destroyed by user
 
979
requests. Server resources created by a client are also destroyed when
 
980
its display connection is closed. If client resources are repeatedly
 
981
created without being destroyed, then the server will eventually run out
 
982
of memory and fail.
 
983
 
 
984
Most server resources are potentially sharable between applications. In
 
985
fact, windows are manipulated explicitly by window manager programs.
 
986
Fonts and cursors are typically shared automatically since the X server
 
987
loads and unloads font storage as needed.
 
988
@var{gcontext} (@pxref{gcontext})
 
989
objects are not ordinarily shared between client applications.
 
990
 
 
991
@node Debugging With CLX,  , The Main Program, A Quick Tour of CLX
 
992
@subsection Debugging With CLX
 
993
 
 
994
Typically, most CLX programs do not need to control the buffering of
 
995
output requests directly. However, CLX programmers need to be aware of
 
996
the asynchronous nature of client-server communication. It may be
 
997
convenient to control the CLX output buffer more directly, especially
 
998
during debugging.
 
999
 
 
1000
A client that wants a request to execute immediately instead of
 
1001
asynchronously can follow it with a call to
 
1002
@var{display-force-output} (@pxref{display-force-output}).
 
1003
This function @emph{blocks} (does not return) until all previously
 
1004
buffered output requests have been sent. Otherwise, the output buffer is
 
1005
always flushed by a call to any function which returns a value from the
 
1006
server or which waits for input (for example,
 
1007
@var{get-property} (@pxref{get-property}).
 
1008
Certain output requests can cause input events to be sent. For example,
 
1009
@var{map-window} (@pxref{map-window})
 
1010
can cause
 
1011
@var{:exposure} (@pxref{:exposure})
 
1012
events to be sent. Synchronizing output with the resulting input can be
 
1013
done with the
 
1014
@var{display-finish-output} (@pxref{display-finish-output})
 
1015
function. This function blocks until all previously buffered output has
 
1016
been sent and all resulting input events have been received.
 
1017
 
 
1018
Functions that return information from the server block until an
 
1019
explicit reply is received or an error occurs. If a nonblocking call
 
1020
results in an error, the error is generally not reported until later.
 
1021
All errors (synchronous and asynchronous) are processed by calling an
 
1022
error handler defined for the display. If the handler is a sequence it
 
1023
is expected to contain handler functions specific to each error. The
 
1024
error code is used to index the sequence, fetching the appropriate
 
1025
handler. Any results returned by the handler are ignored since it is
 
1026
assumed that the handler either takes care of the error completely, or
 
1027
else signals.
 
1028
 
 
1029
@node Naming and Argument Conventions, Programming Considerations, A Quick Tour of CLX, Introduction to CLX
 
1030
@section Naming and Argument Conventions
 
1031
 
 
1032
Throughout CLX, a number of conventions for naming and syntax of the CLX
 
1033
functions have been followed. These conventions are intended to make the
 
1034
syntax of the functions more predictable.
 
1035
 
 
1036
The major naming conventions are as follows:
 
1037
 
 
1038
@itemize @bullet
 
1039
@item
 
1040
To better differentiate the CLX symbols from other symbols, they have
 
1041
all been placed in the package XLIB. External symbols have been
 
1042
explicitly exported.
 
1043
 
 
1044
@item
 
1045
The @emph{display} argument, where used, is always first in the
 
1046
argument list.
 
1047
 
 
1048
@item
 
1049
All server resource objects, where used, occur at the beginning of the
 
1050
argument list, immediately after the display variable.
 
1051
 
 
1052
@item
 
1053
When a graphics context (@emph{gcontext}) is present together with
 
1054
another type of server resource (most commonly, a @emph{drawable}),
 
1055
the graphics context occurs in the argument list after the other
 
1056
server resource. Drawables out rank all other server resources.
 
1057
 
 
1058
@item
 
1059
Source arguments always precede the destination arguments in the
 
1060
argument list.
 
1061
 
 
1062
@item
 
1063
The @emph{x} argument always precedes the @emph{y} argument in the
 
1064
argument list.
 
1065
 
 
1066
@item
 
1067
The @emph{width} argument always precedes the @emph{height} argument
 
1068
in the argument list.
 
1069
 
 
1070
@item
 
1071
Where the @emph{x}, @emph{y}, @emph{width} and @emph{height} arguments
 
1072
are used together, the @emph{x} and @emph{y} arguments always precede
 
1073
the @emph{width} and @emph{height} arguments.
 
1074
 
 
1075
@item
 
1076
Where a @emph{mask} is accompanied with a @emph{structure}, the mask
 
1077
always precedes the structure in the argument list.
 
1078
@end itemize
 
1079
 
 
1080
@node Programming Considerations, Data Types, Naming and Argument Conventions, Introduction to CLX
 
1081
@section Programming Considerations
 
1082
 
 
1083
The major programming considerations are as follows:
 
1084
 
 
1085
@itemize @bullet
 
1086
@item
 
1087
Keyboards are the greatest variable between different manufacturer's
 
1088
workstations. If you want your program to be portable, you should be
 
1089
particularly conservative here.
 
1090
 
 
1091
@item
 
1092
Many display systems have limited amounts of off-screen memory. If you
 
1093
can, you should minimize use of pixmaps and backing store.
 
1094
 
 
1095
@item
 
1096
The user should have control of his screen real-estate. Therefore, you
 
1097
should write your applications to react to window management, rather
 
1098
than presume control of the entire screen. What you do inside of your
 
1099
top level window, however, is up to your application.
 
1100
 
 
1101
@item
 
1102
Coordinates and sizes in X are actually 16-bit quantities. They
 
1103
usually are declared as an
 
1104
@var{int16} (@pxref{int16}) in
 
1105
the functions. Values larger than 16 bits can be truncated silently.
 
1106
Sizes (width and height) are unsigned quantities.
 
1107
 
 
1108
@item
 
1109
The types
 
1110
@var{color} (@pxref{color}),
 
1111
@var{colormap} (@pxref{colormap}),
 
1112
@var{cursor} (@pxref{cursor}),
 
1113
@var{display} (@pxref{display}),
 
1114
@var{font} (@pxref{font}),
 
1115
@var{gcontext} (@pxref{gcontext}),
 
1116
@var{pixmap} (@pxref{pixmap}),
 
1117
@var{screen} (@pxref{screen}),
 
1118
and
 
1119
@var{window} (@pxref{window})
 
1120
are defined solely by a functional interface. Even though they are
 
1121
treated like structures in this document, it is not specified whether
 
1122
they are implemented as structures or classes. Although some
 
1123
interfaces are described as functions, they are not required to be
 
1124
defined using @var{defun.} (It is a requirement that they be
 
1125
functions as opposed to macros or special forms.)
 
1126
@end itemize
 
1127
 
 
1128
@node Data Types,  , Programming Considerations, Introduction to CLX
 
1129
@section Data Types
 
1130
 
 
1131
 
 
1132
The following are some data type definitions that are commonly used in
 
1133
CLX function definitions.
 
1134
 
 
1135
@deftp {Type} alist (key-type-and-name datum-type-and-name) 'list
 
1136
@var{alist} defines an association list. An association list is a
 
1137
sequence, containing zero or more repetitions of the given elements
 
1138
with each of the elements expressed as (@emph{type} @emph{name}).
 
1139
@end deftp
 
1140
 
 
1141
 
 
1142
@deftp {Type} angle `(number ,(* -2pi) ,(* 2pi))
 
1143
@var{angle} defines an angle in units of radians and is bounded by
 
1144
(-2%pi;) and (2%pi;). Note that we are explicitly using a
 
1145
different angle representation than what is actually transmitted in
 
1146
the protocol.
 
1147
@end deftp
 
1148
 
 
1149
 
 
1150
@deftp {Type} arc-seq '(repeat-seq (int16 x) (int16 y) (card16 width) (card16 height) (angle angle1) (angle angle2))
 
1151
@var{arc-seq} defines a six-tuple sequence of the form
 
1152
(@emph{x}, @emph{y}, @emph{width}, @emph{height}, @emph{angle1}, @emph{angle2}).
 
1153
The points @emph{x} and @emph{y} are signed, 16-bit quantities with a
 
1154
range from -32,768 to 32,767. The @emph{width} and @emph{height}
 
1155
values are unsigned, 16-bit quantities and range from 0 to 65,535.
 
1156
@emph{angle1} and @emph{angle2} are in units of radians, and bounded
 
1157
by (-2%pi;) and (2%pi;).
 
1158
@end deftp
 
1159
 
 
1160
 
 
1161
@deftp {Type} array-index `(integer 0 ,array-dimension-limit)
 
1162
@var{array-index} defines a type which is a subtype of the integers
 
1163
and can be used to describe all variables that can be array
 
1164
indices. The range is inclusive because start and end array index
 
1165
specifiers can be one (1) past the end.
 
1166
@end deftp
 
1167
 
 
1168
 
 
1169
@deftp {Type} bit-gravity '(member gravity*)
 
1170
A keyword that specifies which region of a window should be retained
 
1171
when the window is resized.
 
1172
 
 
1173
@emph{gravity} -- One of the following:
 
1174
@itemize @c menu
 
1175
 
 
1176
@item @var{:center}
 
1177
@item @var{:north}
 
1178
@item @var{:south}
 
1179
@item @var{:static}
 
1180
 
 
1181
@item @var{:east}
 
1182
@item @var{:north-east}
 
1183
@item @var{:south-east :west}
 
1184
 
 
1185
@item @var{:forget}
 
1186
@item @var{:north-west}
 
1187
@item @var{:south-west}
 
1188
@end itemize
 
1189
 
 
1190
If a window is reconfigured without changing its inside width or
 
1191
height, then the contents of the window moves with the window and are
 
1192
not lost. Otherwise, the contents of a resized window are either moved
 
1193
or lost, depending on its bit-gravity attribute. See
 
1194
@var{window-bit-gravity}, in @ref{Window Attributes}, for additional
 
1195
information.
 
1196
 
 
1197
@end deftp
 
1198
 
 
1199
 
 
1200
 
 
1201
@deftp {Type} bitmap '(array bit (* *))
 
1202
Specifies a two-dimensional array of bits.
 
1203
@end deftp
 
1204
 
 
1205
 
 
1206
@deftp {Structure} bitmap-format
 
1207
 
 
1208
A structure that describes the storage format of a bitmap.
 
1209
 
 
1210
The @var{bitmap-format} structure contains slots for @var{unit},
 
1211
@var{pad}, and @var{lsb-first-p}. The @var{unit} member indicates
 
1212
the unit of increments used to maintain the bitmap data. The units
 
1213
available for use are 8, 16, or 32 bits. The @var{pad} member
 
1214
indicates how many bits are needed to pad the left edge of the
 
1215
scan-line. The @var{lsb-first-p} member is a predicate which
 
1216
indicates the ordering of bits with the bitmap unit.
 
1217
 
 
1218
@end deftp
 
1219
 
 
1220
 
 
1221
@deftp {Slot of bitmap-format} unit
 
1222
 
 
1223
Type: (@var{member} 8 16 32).
 
1224
 
 
1225
The size of a contiguous grouping of bits, which can be 8, 16, or
 
1226
32. The default is 8.
 
1227
 
 
1228
@end deftp
 
1229
 
 
1230
 
 
1231
 
 
1232
@deftp {Slot of bitmap-format} pad
 
1233
 
 
1234
Type: (@var{member} 8 16 32).
 
1235
 
 
1236
The number of bits to left-pad the scan-line, which can be 8, 16, or
 
1237
32. The default is 8.
 
1238
@end deftp
 
1239
 
 
1240
 
 
1241
@deftp {Slot of bitmap-format} lsb-first-p
 
1242
 
 
1243
Type: @var{boolean}.
 
1244
 
 
1245
A predicate indicating whether the least significant bit comes first
 
1246
(@var{true}) or not (@var{nil}).
 
1247
@end deftp
 
1248
 
 
1249
 
 
1250
@deftp {Type} boolean '(or nil (not nil))
 
1251
@var{boolean} defines a type which is all inclusive. It is used for
 
1252
variables that can take on a true (non-@var{nil}) or false
 
1253
(@var{nil}) value.
 
1254
@end deftp
 
1255
 
 
1256
@deftp {Type} boole-constant `(member value*)
 
1257
 
 
1258
@var{boole-constant} defines a type that is a set of the values
 
1259
associated with the 16 boolean operation-code constants for the Common
 
1260
Lisp language. It is used for the set of allowed source and
 
1261
destination combination functions in a graphics context.
 
1262
 
 
1263
@emph{value} -- One of the following:
 
1264
@itemize @c menu
 
1265
 
 
1266
@item @var{boole-1}
 
1267
@item @var{boole-c1}
 
1268
@item @var{boole-nand}
 
1269
@item @var{boole-xor}
 
1270
 
 
1271
@item @var{boole-2}
 
1272
@item @var{boole-c2}
 
1273
@item @var{boole-nor}
 
1274
 
 
1275
@item @var{boole-and}
 
1276
@item @var{boole-clr}
 
1277
@item @var{boole-orc1}
 
1278
 
 
1279
@item @var{boole-andc1}
 
1280
@item @var{boole-eqv}
 
1281
@item @var{boole-orc2}
 
1282
 
 
1283
@item @var{boole-andc2}
 
1284
@item @var{boole-ior}
 
1285
@item @var{boole-set}
 
1286
@end itemize
 
1287
@end deftp
 
1288
 
 
1289
 
 
1290
@deftp {Type} card8 '(unsigned-byte 8)
 
1291
An unsigned integer value that is a maximum of eight bits long. This
 
1292
gives a number of this type a range from 0 to 255.
 
1293
@end deftp
 
1294
 
 
1295
 
 
1296
@deftp {Type} card16 '(unsigned-byte 16)
 
1297
An unsigned integer value that is a maximum of 16 bits long. This
 
1298
gives a number of this type a range from 0 to 65,535.
 
1299
@end deftp
 
1300
 
 
1301
 
 
1302
@deftp {Type} card29 '(unsigned-byte 29)
 
1303
An unsigned integer value that is a maximum of 29 bits long. This
 
1304
gives a number of this type a range from 0 to 536,870,911.
 
1305
@end deftp
 
1306
 
 
1307
 
 
1308
@deftp {Type} card32 '(unsigned-byte 32)
 
1309
An unsigned integer value that is a maximum of 32 bits long. This
 
1310
gives a number of this type a range from 0 to 4,294,967,295.
 
1311
@end deftp
 
1312
 
 
1313
 
 
1314
@deftp {Type} color '(satisfies color-p)
 
1315
@anchor{color}
 
1316
A @var{color}. @xref{Color Functions}, for additional
 
1317
information.
 
1318
@end deftp
 
1319
 
 
1320
 
 
1321
@deftp {Type} colormap '(satisfies colormap-p)
 
1322
@anchor{colormap}
 
1323
A @var{colormap}. @xref{Colormap Functions}, for
 
1324
additional information.
 
1325
@end deftp
 
1326
 
 
1327
 
 
1328
@deftp {Type} cursor '(satisfies cursor-p)
 
1329
@anchor{cursor}
 
1330
A @var{cursor}. @xref{Cursors}, for additional information.
 
1331
@end deftp
 
1332
 
 
1333
 
 
1334
@deftp {Type} device-event-mask '(or mask32 (list device-event-mask-class))
 
1335
@anchor{event-mask}
 
1336
 
 
1337
Provides a way to specify a set of bits for an event bitmask. Two ways
 
1338
of specifying the bits are allowed: by setting the event bits in a 32
 
1339
bit mask, or by listing the keyword names of the device related event
 
1340
bits in a list.
 
1341
@end deftp
 
1342
 
 
1343
 
 
1344
@deftp {Type} device-event-mask-class '(member event*)
 
1345
A keyword name, for a device related event, that corresponds to a
 
1346
particular bit in an event bitmask. The set of names is a subset of
 
1347
the names in the type @var{event-mask-class}.
 
1348
 
 
1349
@emph{event} -- One of the following:
 
1350
@itemize @c menu
 
1351
 
 
1352
@item @var{:button-1-motion}
 
1353
@item @var{:button-motion}
 
1354
 
 
1355
@item @var{:button-2-motion}
 
1356
@item @var{:button-press}
 
1357
 
 
1358
@item @var{:button-3-motion}
 
1359
@item @var{:key-press}
 
1360
 
 
1361
@item @var{:button-4-motion}
 
1362
@item @var{:key-release}
 
1363
 
 
1364
@item @var{:button-5-motion}
 
1365
@item @var{:pointer-motion}
 
1366
@end itemize
 
1367
@end deftp
 
1368
 
 
1369
 
 
1370
@deftp {Type} display '(satisfies display-p)
 
1371
@anchor{display}
 
1372
A connection to an X server. @xref{Displays}, for additional
 
1373
information.
 
1374
@end deftp
 
1375
 
 
1376
 
 
1377
@deftp {Type} drawable '(or window pixmap)
 
1378
Both @var{windows} and @var{pixmaps} can be used as sources and
 
1379
destinations in graphics operations. @var{windows} and @var{pixmaps}
 
1380
together are known as @emph{drawables}. However, an @var{:input-only}
 
1381
window cannot be used as a source or destination in a graphics
 
1382
operation.
 
1383
@end deftp
 
1384
 
 
1385
 
 
1386
@deftp {Type} draw-direction '(member :left-to-right :right-to-left)
 
1387
Defines a list of rotation directions for drawing arcs and
 
1388
fonts. @var{draw-direction} can have the values of
 
1389
@var{:left-to-right} or @var{:right-to-left}.
 
1390
@end deftp
 
1391
 
 
1392
 
 
1393
@deftp {Type} error-key '(member error*)
 
1394
Defines a list of all predefined errors. All errors (synchronous and
 
1395
asynchronous) are processed by calling an error handler in the
 
1396
display. The handler is called with the display as the first argument
 
1397
and the error-key as its second argument.
 
1398
 
 
1399
@emph{error} -- One of the following:
 
1400
@itemize @c menu
 
1401
 
 
1402
@item @var{:access}
 
1403
@item @var{:drawable}
 
1404
@item @var{:implementation}
 
1405
@item @var{:value}
 
1406
 
 
1407
@item @var{:alloc}
 
1408
@item @var{:font}
 
1409
@item @var{:length}
 
1410
@item @var{:window}
 
1411
 
 
1412
@item @var{:atom}
 
1413
@item @var{:gcontext}
 
1414
@item @var{:match}
 
1415
 
 
1416
@item @var{:colormap}
 
1417
@item @var{:id-choice}
 
1418
@item @var{:name}
 
1419
 
 
1420
@item @var{:cursor}
 
1421
@item @var{:illegal-request}
 
1422
@item @var{:pixmap}
 
1423
@end itemize
 
1424
@end deftp
 
1425
 
 
1426
@deftp {Type} event-key '(member event-type*)
 
1427
Defines a list that specifies all predefined event-types. Clients are
 
1428
informed of information asynchronously by means of events. These
 
1429
events can be either asynchronously generated from devices or
 
1430
generated as side effects of client requests.
 
1431
 
 
1432
@emph{event-type} -- One of the following:
 
1433
@itemize @c menu
 
1434
 
 
1435
@item @var{:button-press}
 
1436
@item @var{:exposure}
 
1437
@item @var{:motion-notify}
 
1438
 
 
1439
@item @var{:button-release}
 
1440
@item @var{:focus-in}
 
1441
@item @var{:no-exposure}
 
1442
 
 
1443
@item @var{:circulate-notify}
 
1444
@item @var{:focus-out}
 
1445
@item @var{:property-notify}
 
1446
 
 
1447
@item @var{:circulate-request}
 
1448
@item @var{:graphics-exposure}
 
1449
@item @var{:reparent-notify}
 
1450
 
 
1451
@item @var{:client-message}
 
1452
@item @var{:gravity-notify}
 
1453
@item @var{:resize-request}
 
1454
 
 
1455
@item @var{:colormap-notify}
 
1456
@item @var{:keymap-notify}
 
1457
@item @var{:selection-clear}
 
1458
 
 
1459
@item @var{:configure-notify}
 
1460
@item @var{:key-press}
 
1461
@item @var{:selection-notify}
 
1462
 
 
1463
@item @var{:configure-request}
 
1464
@item @var{:key-release}
 
1465
@item @var{:selection-request}
 
1466
 
 
1467
@item @var{:create-notify}
 
1468
@item @var{:leave-notify}
 
1469
@item @var{:unmap-notify}
 
1470
 
 
1471
@item @var{:destroy-notify}
 
1472
@item @var{:map-notify}
 
1473
@item @var{:visibility-notify}
 
1474
 
 
1475
@item @var{:enter-notify}
 
1476
@item @var{:map-request}
 
1477
@end itemize
 
1478
@end deftp
 
1479
 
 
1480
@deftp {Type} event-mask '(or mask32 (list event-mask-class))
 
1481
Provides a way to specify a set of bits for an event bitmask. Two ways
 
1482
of specifying the bits are allowed: by setting the event bits in a 32
 
1483
bit mask, or by listing the keyword names of the event bits in a list.
 
1484
@end deftp
 
1485
 
 
1486
 
 
1487
@deftp {Type} event-mask-class '(member event*)
 
1488
The elements of the type @var{event-mask-class} are keyword names
 
1489
that correspond to a particular bit in an event bitmask.
 
1490
 
 
1491
@emph{event} -- One of the following:
 
1492
@itemize @c menu
 
1493
 
 
1494
@item @var{:button-1-motion}
 
1495
@item @var{:enter-window}
 
1496
@item @var{:pointer-motion-hint}
 
1497
 
 
1498
@item @var{:button-2-motion}
 
1499
@item @var{:exposure}
 
1500
@item @var{:property-change}
 
1501
 
 
1502
@item @var{:button-3-motion}
 
1503
@item @var{:focus-change}
 
1504
@item @var{:resize-redirect}
 
1505
 
 
1506
@item @var{:button-4-motion}
 
1507
@item @var{:key-press}
 
1508
@item @var{:structure-notify}
 
1509
 
 
1510
@item @var{:button-5-motion}
 
1511
@item @var{:key-release}
 
1512
@item @var{:substructure-notify}
 
1513
 
 
1514
@item @var{:button-motion}
 
1515
@item @var{:keymap-state}
 
1516
@item @var{:substructure-redirect}
 
1517
 
 
1518
@item @var{:button-press}
 
1519
@item @var{:leave-window}
 
1520
@item @var{:visibility-change}
 
1521
 
 
1522
@item @var{:button-release}
 
1523
@item @var{:owner-grab-button}
 
1524
 
 
1525
@item @var{:colormap-change}
 
1526
@item @var{:pointer-motion}
 
1527
@end itemize
 
1528
@end deftp
 
1529
 
 
1530
 
 
1531
@defun make-event-keys event-mask
 
1532
Returns a list of @var{event-mask-class} keyword names for the event
 
1533
bits that are set in the specified event mask.
 
1534
 
 
1535
@table @var
 
1536
@item event-mask
 
1537
An event mask (type @var{mask32}).
 
1538
@end table
 
1539
 
 
1540
@end defun
 
1541
 
 
1542
 
 
1543
@defun make-event-mask &rest keys
 
1544
 
 
1545
@table @var
 
1546
@item keys
 
1547
@var{event-mask-class} keywords.
 
1548
@end table
 
1549
 
 
1550
Constructs an event mask from a set of @var{event-mask-class} keyword
 
1551
names.
 
1552
 
 
1553
@table @var
 
1554
@item event-mask
 
1555
Type @var{mask32}.
 
1556
@end table
 
1557
 
 
1558
@end defun
 
1559
 
 
1560
 
 
1561
@deftp {Type} font '(satisfies font-p)
 
1562
@anchor{font}
 
1563
 
 
1564
A text font. @xref{Font and Characters}, for additional
 
1565
information.
 
1566
 
 
1567
@end deftp
 
1568
 
 
1569
 
 
1570
@deftp {Type} fontable '(or stringable font)
 
1571
 
 
1572
A @var{fontable} is either a @var{font} object or the name of one of
 
1573
the fonts in the font database.
 
1574
 
 
1575
@end deftp
 
1576
 
 
1577
 
 
1578
@deftp {Type} font-props 'list
 
1579
 
 
1580
A @var{list} that contains alternating keywords and integers.
 
1581
 
 
1582
@end deftp
 
1583
 
 
1584
 
 
1585
@deftp {Type} gcontext '(satisfies gcontext-p)
 
1586
@anchor{gcontext}
 
1587
 
 
1588
A graphics context. @xref{Graphics Contexts}, for additional
 
1589
information.
 
1590
 
 
1591
@end deftp
 
1592
 
 
1593
 
 
1594
@deftp {Type} gcontext-key '(member type*)
 
1595
 
 
1596
A list of predefined types for use in @var{gcontext}
 
1597
processing. Various information for graphics output is stored in a
 
1598
graphics context (GC or GContext), such as foreground pixel,
 
1599
background pixel, line width, clipping region, and so forth.
 
1600
 
 
1601
@var{type} -- One of the following:
 
1602
@itemize @c menu
 
1603
 
 
1604
@item @var{:arc-mode}
 
1605
@item @var{:exposures}
 
1606
@item @var{:line-width}
 
1607
 
 
1608
@item @var{:background}
 
1609
@item @var{:fill-rule}
 
1610
@item @var{:plane-mask}
 
1611
 
 
1612
@item @var{:cap-style :fill-style}
 
1613
@item @var{:stipple}
 
1614
 
 
1615
@item @var{:clip-mask}
 
1616
@item @var{:font}
 
1617
@item @var{:subwindow-mode}
 
1618
 
 
1619
@item @var{:clip-x}
 
1620
@item @var{:foreground}
 
1621
@item @var{:tile}
 
1622
 
 
1623
@item @var{:clip-y}
 
1624
@item @var{:function}
 
1625
@item @var{:ts-x}
 
1626
 
 
1627
@item @var{:dash-offset}
 
1628
@item @var{:join-style}
 
1629
@item @var{:ts-y}
 
1630
 
 
1631
@item @var{:dashes}
 
1632
@item @var{:line-style}
 
1633
@end itemize
 
1634
@end deftp
 
1635
 
 
1636
@deftp {Type} grab-status '(member grab-type*)
 
1637
 
 
1638
There are two kinds of grabs: active and passive. An @emph{active
 
1639
grab} occurs when a single client grabs the keyboard and/or pointer
 
1640
explicitly. Clients can also grab a particular keyboard key or pointer
 
1641
button in a window. The grab activates when the key or button is
 
1642
actually pressed, and is called a @emph{passive grab}. Passive grabs
 
1643
can be very convenient for implementing reliable pop-up menus.
 
1644
 
 
1645
@var{grab-type} -- One of the following:
 
1646
 
 
1647
@itemize @c menu
 
1648
 
 
1649
@item @var{:already-grabbed}
 
1650
 
 
1651
@item @var{:frozen}
 
1652
 
 
1653
@item @var{:invalid-time}
 
1654
 
 
1655
@item @var{:not-viewable}
 
1656
 
 
1657
@item @var{:success}
 
1658
@end itemize
 
1659
@end deftp
 
1660
 
 
1661
 
 
1662
@deftp {Type} image-depth '(integer 0 32)
 
1663
Used in determining the depth of a pixmap, window, or image. The value
 
1664
specifies the number of bits deep that a given pixel has within a
 
1665
given pixmap, window, or image.
 
1666
@end deftp
 
1667
 
 
1668
 
 
1669
@deftp {Type} index-size '(member :default 8 16)
 
1670
Used to control the element size of the destination buffer given to
 
1671
the translate function when drawing glyphs. If @var{:default} is
 
1672
specified, the size is based on the current font, if known; otherwise,
 
1673
16 is used.
 
1674
@end deftp
 
1675
 
 
1676
 
 
1677
@deftp {Type} int8 '(signed-byte 8)
 
1678
A signed integer value that is a maximum of eight bits long. A number
 
1679
of this type can have a range from -128 to 127.
 
1680
@end deftp
 
1681
 
 
1682
 
 
1683
@deftp {Type} int16 '(signed-byte 16)
 
1684
@anchor{int16}
 
1685
A signed integer value that is a maximum of 16 bits long. A number of
 
1686
this type can have a range from -32,768 to 32,767.
 
1687
@end deftp
 
1688
 
 
1689
 
 
1690
@deftp {Type} int32 '(signed-byte 32)
 
1691
A signed integer value that is a maximum of 32 bits long. A number of
 
1692
this type can have a range from -2,147,483,648 to 2,147,483,647.
 
1693
@end deftp
 
1694
 
 
1695
 
 
1696
@deftp {Type} keysym 'card32
 
1697
Used as an encoding of a symbol on a keycap on a keyboard. It is an
 
1698
unsigned integer value represented in a maximum of 32 bits long. A
 
1699
@var{keysym} type can have a range from 0 to 4,294,967,295.
 
1700
@end deftp
 
1701
 
 
1702
 
 
1703
@deftp {Type} mask16 ' card16
 
1704
A positional bitmask that contains 16 boolean flags.
 
1705
@end deftp
 
1706
 
 
1707
 
 
1708
@deftp {Type} mask32 ' card32
 
1709
A positional bitmask that contains 32 boolean flags.
 
1710
@end deftp
 
1711
 
 
1712
 
 
1713
@deftp {Type} modifier-key '(member modifier*)
 
1714
A keyword identifying one of the modifier keys on the keyboard device.
 
1715
 
 
1716
@var{modifier} -- One of the following:
 
1717
@itemize @c menu
 
1718
 
 
1719
@item @var{:shift}
 
1720
@item @var{:mod-2}
 
1721
 
 
1722
@item @var{:lock}
 
1723
@item @var{:mod-3}
 
1724
 
 
1725
@item @var{:control}
 
1726
@item @var{:mod-4}
 
1727
 
 
1728
@item @var{:mod-1}
 
1729
@item @var{:mod-5}
 
1730
@end itemize
 
1731
@end deftp
 
1732
 
 
1733
 
 
1734
@deftp {Type} modifier-mask '(or (member :any) mask16 (list modifier-key))
 
1735
A bitmask or list of keywords that specifies a set of modifier
 
1736
keys. The keyword @var{:any} is equivalent to any subset of modifier
 
1737
key.
 
1738
@end deftp
 
1739
 
 
1740
 
 
1741
@deftp {Type} pixarray '(or (array pixel (* *)) (array card16 (* *)) (array card8 (* *)) (array (unsigned-byte 4) (* *)) (array bit (* *)))
 
1742
 
 
1743
Specifies a two-dimensional array of pixels.
 
1744
 
 
1745
@end deftp
 
1746
 
 
1747
 
 
1748
 
 
1749
@deftp {Type} pixel '(unsigned-byte 32)
 
1750
 
 
1751
An unsigned integer value that is a maximum of 32 bits long. This
 
1752
gives a pixel type a value range from 0 to 4,294,967,295. Useful
 
1753
values are dependent on the class of colormap being used.
 
1754
 
 
1755
@end deftp
 
1756
 
 
1757
 
 
1758
@deftp {Type} pixmap '(satisfies pixmap-p)
 
1759
@anchor{pixmap}
 
1760
 
 
1761
A @var{pixmap}, @pxref{Pixmaps}), for additional information.
 
1762
 
 
1763
@end deftp
 
1764
 
 
1765
 
 
1766
@deftp {Structure} pixmap-format
 
1767
 
 
1768
A structure that describes the storage format of a pixmap.
 
1769
 
 
1770
The @var{pixmap-format} structure contains slots for @var{depth},
 
1771
@var{bits-per-pixel}, and @var{scanline-pad}. The @var{depth} member
 
1772
indicates the number of bit planes in the pixmap. The
 
1773
@var{bits-per-pixel} member indicates the number of bits used to
 
1774
represent a single pixel. For X, a pixel can be 1, 4, 8, 16, 24, or 32
 
1775
bits wide. As for @var{bitmap-format}, the @var{scanline-pad} member
 
1776
indicates how many pixels are needed to pad the left edge of the
 
1777
scan-line.
 
1778
@end deftp
 
1779
 
 
1780
@deftp {Slot of pixmap-format} depth
 
1781
 
 
1782
Type: @var{image-depth}.
 
1783
 
 
1784
The number of bit planes in the pixmap.
 
1785
@end deftp
 
1786
 
 
1787
 
 
1788
@deftp {Slot of pixmap-format} bits-per-pixel
 
1789
 
 
1790
 
 
1791
Type: (@var{member} 1 4 8 16 24 32).
 
1792
 
 
1793
The number of consecutive bits used to encode a single pixel. The
 
1794
default is 8.
 
1795
@end deftp
 
1796
 
 
1797
 
 
1798
@deftp {Slot of pixmap-format} scanline-pad
 
1799
 
 
1800
Type: (@var{member} 8 16 32).
 
1801
 
 
1802
The number of bits to left-pad the scan-line, which can be 8, 16, or
 
1803
32. The default is 8.
 
1804
@end deftp
 
1805
 
 
1806
@deftp {Type} point-seq '(repeat-seq (int16 x) (int16 y))
 
1807
 
 
1808
The @var{point-seq} type is used to define sequences of
 
1809
(@var{x},@var{y}) pairs of points. The paired values are 16-bit,
 
1810
signed integer quantities. This gives the points in this type a range
 
1811
from -32,768 to 32,767.
 
1812
@end deftp
 
1813
 
 
1814
@deftp {Type} pointer-event-mask '(or mask32 (list pointer-event-mask-class))
 
1815
 
 
1816
Provides a way to specify a set of bits for an event bitmask. Two ways
 
1817
of specifying the bits are allowed: by setting the event bits in a 32
 
1818
bit mask, or by listing the keyword names of the pointer related event
 
1819
bits in a list.
 
1820
 
 
1821
@end deftp
 
1822
 
 
1823
 
 
1824
@deftp {Type} pointer-event-mask-class '(member event*)
 
1825
 
 
1826
A keyword name, for a pointer related event, that corresponds to a
 
1827
particular bit in an event bitmask. The set of names is a subset of
 
1828
the names in the type @var{event-mask-class}.
 
1829
 
 
1830
@var{event} -- One of the following:
 
1831
 
 
1832
@itemize @c menu
 
1833
 
 
1834
@item @var{:button-1-motion}
 
1835
@item @var{:button-motion}
 
1836
@item @var{:leave-window}
 
1837
 
 
1838
@item @var{:button-2-motion}
 
1839
@item @var{:button-press}
 
1840
@item @var{:pointer-motion}
 
1841
 
 
1842
@item @var{:button-3-motion}
 
1843
@item @var{:button-release}
 
1844
@item @var{:pointer-motion-hint}
 
1845
 
 
1846
@item @var{:button-4-motion}
 
1847
@item @var{:enter-window}
 
1848
 
 
1849
@item @var{:button-5-motion}
 
1850
@item @var{:keymap-state}
 
1851
@end itemize
 
1852
@end deftp
 
1853
 
 
1854
@deftp {Type} rect-seq '(repeat-seq (int16 x) (int16 y) (card16 width) (card16 height))
 
1855
 
 
1856
@var{rect-seq} defines a four-tuple sequence of the form (@var{x},
 
1857
@var{y}, @var{width}, @var{height}). The points @var{x} and
 
1858
@var{y} are signed, 16-bit quantities with a range from -32,768 to
 
1859
32,767. The @var{width} and @var{height} values are unsigned, 16-bit
 
1860
quantities and range from 0 to 65,535.
 
1861
 
 
1862
@end deftp
 
1863
 
 
1864
 
 
1865
@deftp {Type} repeat-seq (&rest elts) 'sequence
 
1866
 
 
1867
A subtype used to define repeating sequences.
 
1868
 
 
1869
@end deftp
 
1870
 
 
1871
 
 
1872
@deftp {Type} resource-id 'card29
 
1873
 
 
1874
A numeric identifier that is assigned by the server to a server
 
1875
resource object.
 
1876
 
 
1877
@end deftp
 
1878
 
 
1879
 
 
1880
@deftp {Type} rgb-val '(float 0.0 1.0)
 
1881
 
 
1882
An @var{rgb-val} is a floating-point value between 0 and 1 that
 
1883
specifies a saturation for a red, green, or blue additive primary. The
 
1884
0 value indicates no saturation and 1 indicates full saturation.
 
1885
 
 
1886
@end deftp
 
1887
 
 
1888
@deftp {Type} screen '(satisfies screen-p)
 
1889
@anchor{screen}
 
1890
 
 
1891
A display screen. @xref{Screens}, for further information.
 
1892
 
 
1893
@end deftp
 
1894
 
 
1895
 
 
1896
@deftp {Type} seg-seq '(repeat-seq (int16 x1) (int16 y1) (int16 x2) (int16 y2))
 
1897
 
 
1898
Defines sequences of (@var{x1}, @var{y1}, @var{x2}, @var{y2}) sets
 
1899
of points. The point values are 16-bit, signed integer
 
1900
quantities. This gives the points in this type a range from -32,768 to
 
1901
32,767.
 
1902
 
 
1903
@end deftp
 
1904
 
 
1905
 
 
1906
@deftp {Type} state-mask-key '(or modifier-key (member button*))
 
1907
 
 
1908
A keyword identifying one of the display modifier keys or pointer
 
1909
buttons whose state is reported in device events.
 
1910
 
 
1911
@var{button} -- One of the following:
 
1912
 
 
1913
@itemize @c menu
 
1914
@item @var{:button-1}
 
1915
@item @var{:button-4}
 
1916
@item @var{:button-2}
 
1917
@item @var{:button-5}
 
1918
@item @var{:button-3}
 
1919
@end itemize
 
1920
 
 
1921
@end deftp
 
1922
 
 
1923
@defun make-state-keys state-mask
 
1924
 
 
1925
@table @var
 
1926
@item state-mask
 
1927
A 16-bit mask of type @var{mask16}.
 
1928
 
 
1929
@end table
 
1930
 
 
1931
Returns a list of @var{state-mask-key} symbols corresponding to the
 
1932
@var{state-mask}. A symbol belongs to the returned list if, and only
 
1933
if, the corresponding @var{state-mask} bit is 1.
 
1934
 
 
1935
@table @var
 
1936
@item state-keywords
 
1937
Type @var{list}.
 
1938
@end table
 
1939
 
 
1940
@end defun
 
1941
 
 
1942
 
 
1943
@defun make-state-mask &rest keys
 
1944
 
 
1945
@table @var
 
1946
@item keys
 
1947
A list of @var{state-mask-key} symbols.
 
1948
@end table
 
1949
 
 
1950
Returns a 16-bit @var{mask} representing the given
 
1951
@var{state-mask-key} symbols. The returned @var{mask} contains a 1
 
1952
bit for each keyword.
 
1953
 
 
1954
@table @var
 
1955
@item mask
 
1956
Type @var{mask16}.
 
1957
@end table
 
1958
@end defun
 
1959
 
 
1960
@deftp {Type} stringable '(or string symbol)
 
1961
 
 
1962
Used for naming something. This type can be either a string or a
 
1963
@var{symbol} whose @var{symbol-name} is used as the string containing
 
1964
the name. The case of the characters in the string is ignored when
 
1965
comparing stringables.
 
1966
 
 
1967
@end deftp
 
1968
 
 
1969
 
 
1970
@deftp {Type} timestamp '(or null card32)
 
1971
 
 
1972
An encoding of a time. @var{nil} stands for the current time.
 
1973
 
 
1974
@end deftp
 
1975
 
 
1976
 
 
1977
@deftp {Structure} visual-info
 
1978
 
 
1979
A structure that represents a visual type. The elements of this
 
1980
structure are @var{id}, @var{class}, @var{red-mask}, @var{green-mask},
 
1981
@var{blue-mask}, @var{bits-per-rgb}, and @var{colormap-entries}.
 
1982
 
 
1983
@end deftp
 
1984
 
 
1985
 
 
1986
@deftp {Slot of visual-info} id
 
1987
 
 
1988
Type: @var{card29}.
 
1989
 
 
1990
A unique identification number.
 
1991
 
 
1992
@end deftp
 
1993
 
 
1994
 
 
1995
@deftp {Slot of visual-info} class
 
1996
 
 
1997
Type: (member :direct-color :gray-scale :pseudo-color :static-color :static-gray :true-color).
 
1998
 
 
1999
The class of the visual type.
 
2000
 
 
2001
@end deftp
 
2002
 
 
2003
 
 
2004
@deftp {Slots of visual-info} red-mask
 
2005
@deftpx {Slots of visual-info} green-mask
 
2006
@deftpx {Slots of visual-info} blue-mask
 
2007
 
 
2008
Type: @var{pixel}.
 
2009
 
 
2010
The @var{red-mask}, @var{green-mask}, and @var{blue-mask} elements are
 
2011
only meaningful for the @var{:direct-color} and @var{:true-color}
 
2012
classes. Each mask has one contiguous set of bits with no
 
2013
intersections.
 
2014
 
 
2015
@end deftp
 
2016
 
 
2017
@deftp {Slot of visual-info} bits-per-rgb
 
2018
 
 
2019
Type: @var{card8}.
 
2020
 
 
2021
Specifies the log base 2 of the approximate number of distinct color
 
2022
values ( individually) of red, green, and blue. Actual RGB values are
 
2023
unsigned 16-bit numbers.
 
2024
 
 
2025
@end deftp
 
2026
 
 
2027
 
 
2028
@deftp {Slot of visual-info} colormap-entries
 
2029
 
 
2030
Type: @var{card16}.
 
2031
 
 
2032
Defines the number of available colormap entries in a newly created
 
2033
colormap. For @var{:direct-color} and @var{:true-color}, this is the
 
2034
size of an individual pixel subfield.
 
2035
 
 
2036
@end deftp
 
2037
 
 
2038
 
 
2039
@deftp {Type} win-gravity '(member gravity*)
 
2040
 
 
2041
A keyword that specifies how to reposition a window when its parent is
 
2042
resized.
 
2043
 
 
2044
@var{gravity} -- One of the following:
 
2045
@itemize @c menu
 
2046
 
 
2047
@item @var{:center}
 
2048
@item @var{:north-west}
 
2049
@item @var{:static}
 
2050
 
 
2051
@item @var{:east}
 
2052
@item @var{:south}
 
2053
@item @var{:unmap}
 
2054
 
 
2055
@item @var{:north}
 
2056
@item @var{:south-east}
 
2057
@item @var{:west}
 
2058
 
 
2059
@item @var{:north-east}
 
2060
@item @var{:south-west}
 
2061
@end itemize
 
2062
 
 
2063
If a parent window is reconfigured without changing its inside width
 
2064
or height, then all child windows move with the parent and are not
 
2065
changed. Otherwise, each child of the resized parent is moved,
 
2066
depending on the child's gravity attribute. See @var{window-gravity}
 
2067
(@pxref{Window Attributes})), for additional information.
 
2068
 
 
2069
@end deftp
 
2070
 
 
2071
 
 
2072
@deftp {Type} window '(satisfies window-p)
 
2073
@anchor{window}
 
2074
 
 
2075
A window. @xref{Windows and Pixmaps}, for additional
 
2076
information.
 
2077
 
 
2078
@end deftp
 
2079
 
 
2080
 
 
2081
@deftp {Type} xatom '(or string symbol)
 
2082
 
 
2083
A name that has been assigned a corresponding unique ID by the
 
2084
server. @var{xatoms} are used to identify properties, selections, and
 
2085
types defined in the X server. An @var{xatom} can be either a
 
2086
@var{string} or @var{symbol} whose @var{symbol-name} is used as the
 
2087
@var{xatom} name. The case of the characters in the string are
 
2088
significant when comparing @var{xatoms}.
 
2089
 
 
2090
@end deftp
 
2091
 
 
2092
@node Displays, Screens, Introduction to CLX, Top
 
2093
@chapter Displays
 
2094
 
 
2095
A particular X server, together with its screens and input devices, is
 
2096
called a @emph{display}. The CLX @var{display} object contains all the
 
2097
information about the particular display and its screens, as well as the
 
2098
state that is needed to communicate with the display over a particular
 
2099
connection.
 
2100
 
 
2101
Before your program can use a display, you must establish a connection to
 
2102
the X server driving your display. Once you have established a connection,
 
2103
you then can use the CLX macros and functions discussed in this section to
 
2104
return information about the display.  This section discusses how to:
 
2105
 
 
2106
@itemize @bullet
 
2107
@item  Open (connect) a display
 
2108
@item  Obtain information about a display
 
2109
@item  Access and change display attributes
 
2110
@item  Close (disconnect) a display
 
2111
@end itemize
 
2112
 
 
2113
@menu
 
2114
* Opening the Display::
 
2115
* Display Attributes::
 
2116
* Managing the Output Buffer::
 
2117
* Closing the Display::
 
2118
@end menu
 
2119
 
 
2120
@node Opening the Display, Display Attributes, Displays, Displays
 
2121
@section Opening the Display
 
2122
 
 
2123
 
 
2124
The @var{open-display} function is used to open a connection to an X
 
2125
server.
 
2126
 
 
2127
@defun open-display host &key :display :protocol
 
2128
 
 
2129
@table @var
 
2130
@item host
 
2131
Specifies the name of the @emph{host} machine on which the server
 
2132
executes. A string must be acceptable as a @emph{host}, but otherwise
 
2133
the possible types are not constrained and will likely be very system
 
2134
dependent.
 
2135
 
 
2136
@item :display
 
2137
An integer that specifies which display device on the @emph{host}
 
2138
should be used for this connection. This is needed since multiple
 
2139
displays can be controlled by a single X server. The default is
 
2140
display 0 (zero).
 
2141
 
 
2142
@item :protocol
 
2143
A keyword argument that specifies which network protocol should be
 
2144
used for connecting to the server (for example, @var{:tcp},
 
2145
@var{:dna}, or @var{:chaos}). The set of possible values and the
 
2146
default value are implementation specific.
 
2147
 
 
2148
@end table
 
2149
 
 
2150
Returns a @var{display} that serves as the connection to the X
 
2151
server and contains all the information about that X server.
 
2152
 
 
2153
Authorization, if any, is assumed to come from the
 
2154
environment. After a successful call to @var{open-display}, all
 
2155
screens on the display can be used by the client application.
 
2156
 
 
2157
@table @var
 
2158
@item display
 
2159
Type @var{display}.
 
2160
@end table
 
2161
 
 
2162
@end defun
 
2163
 
 
2164
 
 
2165
@node Display Attributes, Managing the Output Buffer, Opening the Display, Displays
 
2166
@section Display Attributes
 
2167
 
 
2168
The complete set of display attributes is discussed in the following
 
2169
paragraphs.
 
2170
 
 
2171
@defun display-authorization-data display
 
2172
 
 
2173
@table @var
 
2174
@item display
 
2175
A @var{display} object.
 
2176
@end table
 
2177
 
 
2178
Returns the authorization data string for @var{display} that was
 
2179
transmitted to the server by @var{open-display} during connection
 
2180
setup. The data is specific to the particular authorization protocol
 
2181
that was used. The @var{display-authorization-name} function returns
 
2182
the protocol used.
 
2183
 
 
2184
@table @var
 
2185
@item authorization-data
 
2186
Type @var{string}.
 
2187
@end table
 
2188
 
 
2189
@end defun
 
2190
 
 
2191
@defun display-authorization-name display
 
2192
 
 
2193
@table @var
 
2194
@item display
 
2195
A @var{display} object.
 
2196
@end table
 
2197
 
 
2198
Returns the authorization protocol namestring for @var{display} that
 
2199
was transmitted by @var{open-display} to the server during connection
 
2200
setup. The @var{authorization-name} indicates what authorization
 
2201
protocol the client expects the server to use. Specification of valid
 
2202
authorization mechanisms is not part of the X protocol. A server that
 
2203
implements a different protocol than the client expects, or a server
 
2204
that only implements the host-based mechanism, can simply ignore this
 
2205
information. If both name and data strings are empty, this is to be
 
2206
interpreted as "no explicit authorization."
 
2207
 
 
2208
@table @var
 
2209
@item authorization-name
 
2210
Type @var{string}.
 
2211
@end table
 
2212
 
 
2213
@end defun
 
2214
 
 
2215
@defun display-bitmap-format display
 
2216
@anchor{display-bitmap-format}
 
2217
 
 
2218
@table @var
 
2219
@item display
 
2220
A @var{display} object.
 
2221
@end table
 
2222
 
 
2223
Returns the @emph{bitmap-format} information for the specified @emph{display}.
 
2224
 
 
2225
@table @var
 
2226
@item bitmap-format
 
2227
Type @var{bitmap-format}.
 
2228
@end table
 
2229
 
 
2230
@end defun
 
2231
 
 
2232
@defun display-byte-order display
 
2233
 
 
2234
@table @var
 
2235
@item display
 
2236
A @var{display} object.
 
2237
@end table
 
2238
 
 
2239
Returns the @var{byte-order} to be employed in communication with the
 
2240
server for the given @var{display}. The possible values are as
 
2241
follows:
 
2242
 
 
2243
@table @var
 
2244
@item :lsbfirst
 
2245
Values are transmitted least significant byte first.
 
2246
@item :msbfirst
 
2247
Values are transmitted most significant byte first.
 
2248
@end table
 
2249
 
 
2250
Except where explicitly noted in the protocol, all 16-bit and 32-bit
 
2251
quantities sent by the client must be transmitted with this
 
2252
@var{byte-order}, and all 16-bit and 32-bit quantities returned by the
 
2253
server are transmitted with this @var{byte-order}.
 
2254
 
 
2255
@table @var
 
2256
@item byte-order
 
2257
Either @var{:lsbfirst} or @var{:msbfirst}.
 
2258
@end table
 
2259
 
 
2260
@end defun
 
2261
 
 
2262
@defun display-display display
 
2263
 
 
2264
@table @var
 
2265
@item display
 
2266
A @var{display} object.
 
2267
@end table
 
2268
 
 
2269
Returns the @var{display-number} for the host associated with
 
2270
@var{display}.
 
2271
 
 
2272
@table @var
 
2273
@item display-number
 
2274
Type @var{integer}.
 
2275
@end table
 
2276
 
 
2277
@end defun
 
2278
 
 
2279
@defun display-error-handler display
 
2280
 
 
2281
@table @var
 
2282
@item display
 
2283
A @var{display} object.
 
2284
@end table
 
2285
 
 
2286
Returns and (with @code{setf}) sets the @var{error-handler} function
 
2287
for the given @var{display}. CLX calls (one of) the display error
 
2288
handler functions to handle server errors returned to the
 
2289
connection. The default error handler, @var{default-error-handler},
 
2290
signals conditions as they occur. @xref{Errors}, for a list of
 
2291
the conditions that CLX can signal. For more information about errors
 
2292
and error handling, refer to the section entitled Common Lisp
 
2293
Condition System in the @emph{Lisp Reference} manual.
 
2294
 
 
2295
If the value of @var{error-handler} is a sequence, it is expected to
 
2296
contain a handler function for each specific error. The error code is
 
2297
used as an index into the sequence to fetch the appropriate handler
 
2298
function. If this element is a function, it is called for all
 
2299
errors. Any results returned by the handler are ignored since it is
 
2300
assumed the handler either takes care of the error completely or else
 
2301
signals. The arguments passed to the handler function are the
 
2302
@var{display} object, a symbol naming the type of error, and a set of
 
2303
keyword-value argument pairs that vary depending on the type of
 
2304
error. For all core errors, the keyword-value argument pairs are:
 
2305
 
 
2306
@multitable @columnfractions 0.5 0.5
 
2307
@item @var{:current-sequence} @tab @var{card16}
 
2308
@item @var{:major} @tab @var{card8}
 
2309
@item @var{:minor} @tab @var{card16}
 
2310
@item @var{:sequence} @tab @var{card16}
 
2311
@end multitable
 
2312
 
 
2313
For @var{colormap}, @var{cursor}, @var{drawable}, @var{font},
 
2314
@var{gcontext}, @var{id-choice}, @var{pixmap}, and @var{window}
 
2315
errors, the keyword-value pairs are the core error pairs plus:
 
2316
 
 
2317
@multitable @columnfractions 0.5 0.5
 
2318
@item @var{:resource-id} @tab @var{card32}
 
2319
@end multitable
 
2320
 
 
2321
For @var{:atom} errors, the keyword-value pairs are the core error
 
2322
pairs plus:
 
2323
 
 
2324
@multitable @columnfractions 0.5 0.5
 
2325
@item @var{:atom-id} @tab @var{card32}
 
2326
@end multitable
 
2327
 
 
2328
For @var{:value} errors, the keyword-value pairs are the core error
 
2329
pairs plus:
 
2330
 
 
2331
@multitable @columnfractions 0.5 0.5
 
2332
@item @var{:value} @tab @var{card32}
 
2333
@end multitable
 
2334
 
 
2335
@table @var
 
2336
@item error-handler
 
2337
Type @var{function} or @var{sequence}.
 
2338
@end table
 
2339
 
 
2340
@end defun
 
2341
 
 
2342
@defun display-image-lsb-first-p display
 
2343
 
 
2344
@table @var
 
2345
@item display
 
2346
A @var{display} object.
 
2347
@end table
 
2348
 
 
2349
Although the server is generally responsible for byte swapping
 
2350
communication data to match the client, images (pixmaps/bitmaps) are
 
2351
always transmitted and received in formats (including byte order)
 
2352
specified by the server. Within images for each scan-line unit in
 
2353
bitmaps or for each pixel value in pixmaps, the leftmost bit in the
 
2354
image as displayed on the screen is either the least or most
 
2355
significant bit in the unit. For the given @var{display},
 
2356
@var{display-image-lsb-first-p} returns non-@var{nil} if the leftmost
 
2357
bit is the least significant bit; otherwise, it returns @var{nil}.
 
2358
 
 
2359
@table @var
 
2360
@item image-lsb-first-p
 
2361
Type @var{boolean}.
 
2362
@end table
 
2363
 
 
2364
@end defun
 
2365
 
 
2366
 
 
2367
@defun display-keycode-range display
 
2368
 
 
2369
@table @var
 
2370
@item display
 
2371
A @var{display} object.
 
2372
@end table
 
2373
 
 
2374
Returns @var{min-keycode} and @var{max-keycode} as multiple
 
2375
values. See the @var{display-max-keycode} and
 
2376
@var{display-min-keycode} functions for additional information.
 
2377
 
 
2378
@table @var
 
2379
@item min-keycode
 
2380
@itemx max-keycode
 
2381
Type @var{card8}.
 
2382
@end table
 
2383
 
 
2384
@end defun
 
2385
 
 
2386
 
 
2387
@defun display-max-keycode display
 
2388
 
 
2389
@table @var
 
2390
@item display
 
2391
A @var{display} object.
 
2392
@end table
 
2393
 
 
2394
Returns the maximum keycode value for the specified
 
2395
@emph{display}. This value is never greater than 255. Not all keycodes
 
2396
in the allowed range are required to have corresponding keys.
 
2397
 
 
2398
@table @var
 
2399
@item max-keycode
 
2400
Type @var{card8}.
 
2401
@end table
 
2402
 
 
2403
@end defun
 
2404
 
 
2405
 
 
2406
@defun display-max-request-length display
 
2407
 
 
2408
@table @var
 
2409
@item display
 
2410
A @var{display} object.
 
2411
@end table
 
2412
 
 
2413
Returns the maximum length of a request, in four-byte units, that is
 
2414
accepted by the specified @emph{display}. Requests larger than this
 
2415
generate a length error, and the server will read and simply discard
 
2416
the entire request. This length is always at least 4096 (that is,
 
2417
requests of length up to and including 16384 bytes are accepted by all
 
2418
servers).
 
2419
 
 
2420
@table @var
 
2421
@item max-request-length
 
2422
Type @var{card16}.
 
2423
@end table
 
2424
 
 
2425
@end defun
 
2426
 
 
2427
 
 
2428
@defun display-min-keycode display
 
2429
 
 
2430
@table @var
 
2431
@item display
 
2432
A @var{display} object.
 
2433
@end table
 
2434
 
 
2435
Returns the minimum keycode value for the specified
 
2436
@var{display}. This value is never less than eight. Not all keycodes
 
2437
in the allowed range are required to have corresponding keys.
 
2438
 
 
2439
@table @var
 
2440
@item min-keycode
 
2441
Type @var{card8}.
 
2442
@end table
 
2443
 
 
2444
@end defun
 
2445
 
 
2446
 
 
2447
@defun display-motion-buffer-size display
 
2448
 
 
2449
@table @var
 
2450
@item display
 
2451
A @var{display} object.
 
2452
@end table
 
2453
 
 
2454
Returns the approximate size of the motion buffer for the specified
 
2455
@var{display}. The server can retain the recent history of pointer
 
2456
motion at a finer granularity than is reported by @var{:motion-notify}
 
2457
events. Such history is available through the @var{motion-events}
 
2458
function.
 
2459
 
 
2460
@table @var
 
2461
@item motion-buffer-size
 
2462
Type @var{card32}.
 
2463
@end table
 
2464
 
 
2465
@end defun
 
2466
 
 
2467
 
 
2468
@defun display-p display
 
2469
 
 
2470
@table @var
 
2471
@item display-p
 
2472
Type @var{boolean}.
 
2473
@end table
 
2474
 
 
2475
Returns non-@var{nil} if @emph{display} is a @var{display} object;
 
2476
@end defun
 
2477
 
 
2478
@defun display-pixmap-formats display
 
2479
 
 
2480
@table @var
 
2481
@item display
 
2482
A @var{display} object.
 
2483
@end table
 
2484
 
 
2485
Returns the list of @var{pixmap-format} values for the given
 
2486
@emph{display}. This list contains one entry for each depth value. The
 
2487
entry describes the format used to represent images of that depth. An
 
2488
entry for a depth is included if any screen supports that depth, and
 
2489
all screens supporting that depth must support (only) the format for
 
2490
that depth.
 
2491
 
 
2492
@table @var
 
2493
@item pixmap-formats
 
2494
Type @var{list}.
 
2495
@end table
 
2496
 
 
2497
@end defun
 
2498
 
 
2499
 
 
2500
@defun display-plist display
 
2501
 
 
2502
@table @var
 
2503
@item display
 
2504
A @var{display} object.
 
2505
@end table
 
2506
 
 
2507
Returns and (with @code{setf}) sets the property list for the specified
 
2508
@emph{display}. This function provides a hook where extensions can add
 
2509
data.
 
2510
@table @var
 
2511
@item plist
 
2512
Type @var{list}.
 
2513
@end table
 
2514
 
 
2515
@end defun
 
2516
 
 
2517
 
 
2518
@defun display-protocol-major-version display
 
2519
 
 
2520
@table @var
 
2521
@item display
 
2522
A @var{display} object.
 
2523
@end table
 
2524
 
 
2525
Returns the major version number of the X protocol associated with the
 
2526
specified @emph{display}. In general, the major version would
 
2527
increment for incompatible changes. The returned protocol version
 
2528
number indicates the protocol the server actually supports. This might
 
2529
not equal the version supported by the client. The server can (but
 
2530
need not) refuse connections from clients that offer a different
 
2531
version than the server supports. A server can (but need not) support
 
2532
more than one version simultaneously.
 
2533
@table @var
 
2534
@item protocol-major-version
 
2535
Type @var{card16}.
 
2536
@end table
 
2537
 
 
2538
@end defun
 
2539
 
 
2540
 
 
2541
@defun display-protocol-minor-version display
 
2542
 
 
2543
@table @var
 
2544
@item display
 
2545
A @var{display} object.
 
2546
@end table
 
2547
 
 
2548
Returns the minor protocol revision number associated with the
 
2549
specified @emph{display}. In general, the minor version would
 
2550
increment for small upward compatible changes in the X protocol.
 
2551
@table @var
 
2552
@item protocol-minor-version
 
2553
Type @var{card16}.
 
2554
@end table
 
2555
 
 
2556
@end defun
 
2557
 
 
2558
 
 
2559
@defun display-protocol-version display
 
2560
 
 
2561
@table @var
 
2562
@item display
 
2563
A @var{display} object.
 
2564
@end table
 
2565
 
 
2566
Returns @emph{protocol-major-version} and
 
2567
@emph{protocol-minor-version} as multiple values. See the
 
2568
@var{display-protocol-major-version} and
 
2569
@var{display-protocol-minor-version} functions for additional
 
2570
information.
 
2571
 
 
2572
@table @var
 
2573
@item protocol-major-version
 
2574
@itemx protocol-minor-version
 
2575
@end table
 
2576
 
 
2577
@end defun
 
2578
 
 
2579
 
 
2580
@defun display-resource-id-base display
 
2581
 
 
2582
@table @var
 
2583
@item display
 
2584
A @var{display} object.
 
2585
@end table
 
2586
 
 
2587
Returns the @emph{resource-id-base} value that was returned from the
 
2588
server during connection setup for the specified @emph{display}. This
 
2589
is used in combination with the @emph{resource-id-mask} to construct
 
2590
valid IDs for this connection.
 
2591
@table @var
 
2592
@item resource-id-base
 
2593
Type @var{resource-id}.
 
2594
@end table
 
2595
 
 
2596
@end defun
 
2597
 
 
2598
 
 
2599
@defun display-resource-id-mask display
 
2600
 
 
2601
@table @var
 
2602
@item display
 
2603
A @var{display} object.
 
2604
@end table
 
2605
 
 
2606
Returns the @emph{resource-id-mask} that was returned from the server
 
2607
during connection setup for the specified @emph{display}. The
 
2608
@emph{resource-id-mask} contains a single contiguous set of bits (at
 
2609
least 18) which the client uses to allocate resource IDs for types
 
2610
@var{window}, @var{pixmap}, @var{cursor}, @var{font}, @var{gcontext},
 
2611
and @var{colormap} by choosing a value with (only) some subset of
 
2612
these bits set, and @var{or}ing it with the
 
2613
@emph{resource-id-base}. Only values constructed in this way can be
 
2614
used to name newly created server resources over this
 
2615
connection. Server resource IDs never have the top three bits set. The
 
2616
client is not restricted to linear or contiguous allocation of server
 
2617
resource IDs. Once an ID has been freed, it can be reused, but this
 
2618
should not be necessary.
 
2619
 
 
2620
 
 
2621
An ID must be unique with respect to the IDs of all other server
 
2622
resources, not just other server resources of the same type. However,
 
2623
note that the value spaces of server resource identifiers, atoms,
 
2624
visualids, and keysyms are distinguished by context, and as such are
 
2625
not required to be disjoint (for example, a given numeric value might
 
2626
be both a valid window ID, a valid atom, and a valid keysym.)
 
2627
@table @var
 
2628
@item resource-id-mask
 
2629
Type @var{resource-id}.
 
2630
@end table
 
2631
 
 
2632
@end defun
 
2633
 
 
2634
 
 
2635
@defun display-roots display
 
2636
 
 
2637
@table @var
 
2638
@item display
 
2639
A @var{display} object.
 
2640
@end table
 
2641
 
 
2642
Returns a list of all the @var{screen} structures available for the
 
2643
given @emph{display}.
 
2644
@table @var
 
2645
@item roots
 
2646
A list of screens.
 
2647
@end table
 
2648
 
 
2649
@end defun
 
2650
 
 
2651
 
 
2652
@defun display-vendor display
 
2653
 
 
2654
@table @var
 
2655
@item display
 
2656
A @var{display} object.
 
2657
@end table
 
2658
Returns @emph{vendor-name} and @emph{release-number} as
 
2659
multiple values. See the @var{display-vendor-name} and
 
2660
@var{display-release-number} functions for additional information.
 
2661
@table @var
 
2662
@item vendor-name
 
2663
@itemx release-number
 
2664
@end table
 
2665
 
 
2666
@end defun
 
2667
 
 
2668
 
 
2669
@defun display-vendor-name display
 
2670
 
 
2671
@table @var
 
2672
@item display
 
2673
A @var{display} object.
 
2674
@end table
 
2675
 
 
2676
Returns a string that provides some vendor identification of the X
 
2677
server implementation associated with the specified @emph{display}.
 
2678
@table @var
 
2679
@item vendor-name
 
2680
Type @var{string}.
 
2681
@end table
 
2682
 
 
2683
@end defun
 
2684
 
 
2685
 
 
2686
@defun display-version-number display
 
2687
 
 
2688
@table @var
 
2689
@item display
 
2690
A @var{display} object.
 
2691
@end table
 
2692
 
 
2693
Returns the X protocol version number for this implementation of CLX.
 
2694
@table @var
 
2695
@item version-number
 
2696
Type @var{card16}.
 
2697
@end table
 
2698
 
 
2699
@end defun
 
2700
 
 
2701
@defun display-xid display
 
2702
 
 
2703
@table @var
 
2704
@item display
 
2705
A @var{display} object.
 
2706
@end table
 
2707
 
 
2708
Returns the function that is used to allocate server resource IDs for
 
2709
this @emph{display}.
 
2710
@table @var
 
2711
@item resource-allocator
 
2712
Type @var{function}.
 
2713
@end table
 
2714
 
 
2715
@end defun
 
2716
 
 
2717
 
 
2718
@defmac with-display display &body body
 
2719
 
 
2720
This macro is for use in a multi-process
 
2721
environment. @var{with-display} provides exclusive access to the local
 
2722
@var{display} object for multiple request generation. It need not
 
2723
provide immediate exclusive access for replies. That is, if another
 
2724
process is waiting for a reply (while not in a @var{with-display}),
 
2725
then synchronization need not (but can) occur immediately. Except
 
2726
where noted, all routines effectively contain an implicit
 
2727
@var{with-display} where needed, so that correct synchronization is
 
2728
always provided at the interface level on a per-call basis. Nested
 
2729
uses of this macro work correctly. This macro does not prevent
 
2730
concurrent event processing (@pxref{with-event-queue}).
 
2731
 
 
2732
@table @var
 
2733
@item display
 
2734
A @var{display}.
 
2735
@end table
 
2736
 
 
2737
@end defmac
 
2738
 
 
2739
@node Managing the Output Buffer, Closing the Display, Display Attributes, Displays
 
2740
@section Managing the Output Buffer
 
2741
 
 
2742
 
 
2743
Most CLX functions cause output requests to be generated to an X
 
2744
server. Output requests are not transmitted immediately but instead
 
2745
are stored in an @emph{output buffer} for the appropriate
 
2746
display. Requests in the output buffer are typically sent only when
 
2747
the buffer is filled. Alternatively, buffered requests can be sent
 
2748
prior to processing an event in the input event queue
 
2749
(@pxref{Processing Events}). In either case, CLX sends the output
 
2750
buffer automatically without explicit instructions from the client
 
2751
application.
 
2752
 
 
2753
However, in some cases, explicit control over the output buffer is
 
2754
needed, typically to ensure that the X server is in a consistent state
 
2755
before proceeding further. The @var{display-force-output} and
 
2756
@var{display-finish-output} functions allow a client program to
 
2757
synchronize with buffered output requests.
 
2758
 
 
2759
@defun display-after-function display
 
2760
 
 
2761
@table @var
 
2762
@item display
 
2763
A @var{display} object.
 
2764
@end table
 
2765
 
 
2766
Returns and (with @code{setf}) sets the @emph{after-function} for the
 
2767
given @emph{display}. If @emph{after-function} is non-@var{nil}, it is
 
2768
a function that is called after every protocol request is generated,
 
2769
even those inside an explicit @var{with-display}, but never called
 
2770
from inside the @emph{after-function}. The function is called inside
 
2771
the effective @var{with-display} for the associated request. The
 
2772
default value is @var{nil}. This can be set, for example, to
 
2773
#'@var{display-force-output} or #' @var{display-finish-outpu}t.
 
2774
@table @var
 
2775
@item after-function
 
2776
Type @var{function} or @var{null}.
 
2777
@end table
 
2778
 
 
2779
@end defun
 
2780
 
 
2781
 
 
2782
@defun display-force-output display
 
2783
@anchor{display-force-output}
 
2784
 
 
2785
@table @var
 
2786
@item display
 
2787
A @var{display} object.
 
2788
@end table
 
2789
 
 
2790
Forces any buffered output to be sent to the X server.
 
2791
 
 
2792
@end defun
 
2793
 
 
2794
 
 
2795
@defun display-finish-output display
 
2796
@anchor{display-finish-output}
 
2797
 
 
2798
@table @var
 
2799
@item display
 
2800
A @var{display} object.
 
2801
@end table
 
2802
 
 
2803
Forces any buffered output to be sent to the X server and then waits
 
2804
until all requests display error handler. Any events generated by
 
2805
output requests are read and stored in the event queue.
 
2806
 
 
2807
@end defun
 
2808
 
 
2809
@node Closing the Display,  , Managing the Output Buffer, Displays
 
2810
@section Closing the Display
 
2811
 
 
2812
To close or disconnect a display from the X server, use @var{close-display}.
 
2813
 
 
2814
@defun close-display display
 
2815
 
 
2816
@table @var
 
2817
@item display
 
2818
A @var{display} object.
 
2819
@end table
 
2820
 
 
2821
Closes the connection to the X server for the specified
 
2822
@var{display}. It destroys all server resources (@var{window},
 
2823
@var{font}, @var{pixmap}, @var{colormap}, @var{cursor}, and
 
2824
@var{gcontext}), that the client application has created on this
 
2825
display, unless the close down mode of the server resource has been
 
2826
changed (@pxref{set-close-down-mode}). Therefore, these server
 
2827
resources should never be referenced again. In addition, this function
 
2828
discards any output requests that have been buffered but have not yet
 
2829
been sent.
 
2830
 
 
2831
@end defun
 
2832
 
 
2833
@node Screens, Windows and Pixmaps, Displays, Top
 
2834
@chapter Screens
 
2835
 
 
2836
@menu
 
2837
* Screens and Visuals::
 
2838
* Screen Attributes::
 
2839
@end menu
 
2840
 
 
2841
@node Screens and Visuals, Screen Attributes, Screens, Screens
 
2842
@section Screens and Visuals
 
2843
 
 
2844
 
 
2845
An X display supports graphical output to one or more
 
2846
@emph{screens}. Each screen has its own root window and window
 
2847
hierarchy. Each window belongs to exactly one screen and cannot
 
2848
simultaneously appear on another screen.
 
2849
 
 
2850
 
 
2851
The kinds of graphics hardware used by X screens can vary greatly in
 
2852
their support for color and in their methods for accessing raster
 
2853
memory. X uses the concept of a @emph{visual type} (usually
 
2854
referred to simply as a @emph{visual}) which uniquely identifies the
 
2855
hardware capabilities of a display screen. Fundamentally, a visual is
 
2856
represented by a @var{card29} integer ID, which uniquely identifies
 
2857
the visual type relative to a single display. CLX also represents a
 
2858
visual with a @var{visual-info} structure that contains other
 
2859
attributes associated with a visual (@pxref{Data Types}). A
 
2860
screen can support more than one depth (that is, pixel size), and for
 
2861
each supported depth, a screen may support more than one visual.
 
2862
However, it is more typical for a screen to have only a single depth
 
2863
and a single visual type.
 
2864
 
 
2865
 
 
2866
A visual represents various aspects of the screen hardware, as
 
2867
follows:
 
2868
 
 
2869
@itemize @bullet
 
2870
 
 
2871
@item
 
2872
A screen can be color or gray-scale.
 
2873
 
 
2874
@item
 
2875
A screen can have a colormap that is either writable or read-only.
 
2876
 
 
2877
@item
 
2878
A screen can have a single colormap or separate colormaps for each of
 
2879
the red, green, and blue components. With separate colormaps, a pixel
 
2880
value is decomposed into three parts to determine indexes into each of
 
2881
the red, green, and blue colormaps.
 
2882
 
 
2883
@end itemize
 
2884
 
 
2885
CLX supports the following classes of visual types:
 
2886
@var{:direct-color}, @var{:gray-scale}, @var{:pseudo-color},
 
2887
@var{:static-color}, @var{:static-gray}, and @var{:true-color}. The
 
2888
following tables show how the characteristics of a screen determine
 
2889
the class of its visual type.
 
2890
 
 
2891
For screens with a single colormap:
 
2892
 
 
2893
@multitable {} {Color} {Gray-Scale}
 
2894
@item Read-only @tab @var{:static-color} @tab @var{:static-gray}
 
2895
@item Writable @tab @var{:pseudo-color} @tab @var{:gray-scale}
 
2896
@end multitable
 
2897
 
 
2898
For screens with red, green, and blue colormaps:
 
2899
 
 
2900
@multitable @columnfractions 0.3 0.3 0.3
 
2901
@item Read-only @tab @var{:true-color} @tab
 
2902
@item Writable @tab @var{:direct-color} @tab @var{:gray-scale}
 
2903
@end multitable
 
2904
 
 
2905
The visual class also indicates how screen colormaps are
 
2906
handled. @pxref{Colormaps and Colors}).
 
2907
 
 
2908
@node Screen Attributes,  , Screens and Visuals, Screens
 
2909
@section Screen Attributes
 
2910
 
 
2911
In CLX, each display screen is represented by a @var{screen}
 
2912
structure. The @var{display-roots} function returns the list of
 
2913
@var{screen} structures for the display. The following paragraphs
 
2914
discuss the attributes of CLX @var{screen} structures.
 
2915
 
 
2916
@defun screen-backing-stores screen
 
2917
 
 
2918
@table @var
 
2919
@item screen
 
2920
A @var{screen}.
 
2921
@end table
 
2922
 
 
2923
Returns a value indicating when the @emph{screen} supports backing
 
2924
stores, although it may be storage limited in the number of windows it
 
2925
can support at once. The value returned can be one of @var{:always},
 
2926
@var{:never}, or @var{:when-mapped}.
 
2927
 
 
2928
@table @var
 
2929
@item backing-stores-type
 
2930
One of @var{:always}, @var{:never}, or @var{:when-mapped}.
 
2931
@end table
 
2932
 
 
2933
@end defun
 
2934
 
 
2935
 
 
2936
@defun screen-black-pixel screen
 
2937
 
 
2938
@table @var
 
2939
@item screen
 
2940
A @var{screen}.
 
2941
@end table
 
2942
 
 
2943
Returns the black pixel value for the specified @emph{screen}.
 
2944
 
 
2945
@table @var
 
2946
@item black-pixel
 
2947
Type @var{pixel}.
 
2948
@end table
 
2949
 
 
2950
@end defun
 
2951
 
 
2952
 
 
2953
@defun screen-default-colormap screen
 
2954
 
 
2955
@table @var
 
2956
@item screen
 
2957
A @var{screen}.
 
2958
@end table
 
2959
 
 
2960
Returns the @emph{default-colormap} for the specified
 
2961
@emph{screen}. The @emph{default-colormap} is initially associated
 
2962
with the root window. Clients with minimal color requirements creating
 
2963
windows of the same depth as the root may want to allocate from this
 
2964
map by default. Most routine allocations of color should be made out
 
2965
of this colormap.
 
2966
 
 
2967
@table @var
 
2968
@item default-colormap
 
2969
Type @var{colormap}.
 
2970
@end table
 
2971
 
 
2972
@end defun
 
2973
 
 
2974
 
 
2975
@defun screen-depths screen
 
2976
 
 
2977
@table @var
 
2978
@item screen
 
2979
A @var{screen}.
 
2980
@end table
 
2981
 
 
2982
 
 
2983
Returns an association list that specifies what drawable
 
2984
depths are supported on the specified @emph{screen}. Elements of the
 
2985
returned association list have the form (depth @emph{visual}*), where
 
2986
each @emph{visual} is a @var{visual-info} structure. Pixmaps are
 
2987
supported for each depth listed, and windows of that depth are
 
2988
supported if at least one visual type is listed for the depth.  A
 
2989
pixmap depth of one is always supported and listed, but windows of
 
2990
depth one might not be supported. A depth of zero is never listed, but
 
2991
zero-depth @var{:input-only} windows are always supported.
 
2992
 
 
2993
@table @var
 
2994
@item depths
 
2995
Type @var{alist}.
 
2996
@end table
 
2997
 
 
2998
@end defun
 
2999
 
 
3000
 
 
3001
@defun screen-event-mask-at-open screen
 
3002
 
 
3003
@table @var
 
3004
@item screen
 
3005
A @var{screen}.
 
3006
@end table
 
3007
 
 
3008
 
 
3009
Returns the initial root event mask for the specified
 
3010
@emph{screen}.
 
3011
 
 
3012
@table @var
 
3013
@item event-mask-at-open
 
3014
Type @var{mask32}.
 
3015
@end table
 
3016
 
 
3017
@end defun
 
3018
 
 
3019
 
 
3020
@defun screen-height screen
 
3021
 
 
3022
@table @var
 
3023
@item screen
 
3024
A @var{screen}.
 
3025
@end table
 
3026
 
 
3027
 
 
3028
Returns the @emph{height} of the specified @emph{screen} in
 
3029
pixel units.
 
3030
 
 
3031
@table @var
 
3032
@item height
 
3033
Type @var{card16}.
 
3034
@end table
 
3035
 
 
3036
@end defun
 
3037
 
 
3038
 
 
3039
@defun screen-height-in-millimeters screen
 
3040
 
 
3041
@table @var
 
3042
@item screen
 
3043
A @var{screen}.
 
3044
@end table
 
3045
 
 
3046
 
 
3047
Returns the height of the specified @emph{screen} in
 
3048
millimeters. The returned height can be used with the width in
 
3049
millimeters to determine the physical size and the aspect ratio of the
 
3050
screen.
 
3051
 
 
3052
@table @var
 
3053
@item height-in-millimeters
 
3054
Type @var{card16}.
 
3055
@end table
 
3056
 
 
3057
@end defun
 
3058
 
 
3059
 
 
3060
@defun screen-max-installed-maps screen
 
3061
 
 
3062
@table @var
 
3063
@item screen
 
3064
A @var{screen}.
 
3065
@end table
 
3066
 
 
3067
 
 
3068
Returns the maximum number of colormaps that can be
 
3069
installed simultaneously with @var{install-colormap}.
 
3070
 
 
3071
@table @var
 
3072
@item max-installed-colormaps
 
3073
Type @var{card16}.
 
3074
@end table
 
3075
 
 
3076
@end defun
 
3077
 
 
3078
 
 
3079
@defun screen-min-installed-maps screen
 
3080
 
 
3081
@table @var
 
3082
@item screen
 
3083
A @var{screen}.
 
3084
@end table
 
3085
 
 
3086
Returns the minimum number of colormaps that can be guaranteed to be
 
3087
installed simultaneously.
 
3088
 
 
3089
@table @var
 
3090
@item min-installed-colormaps
 
3091
Type @var{card16}.
 
3092
@end table
 
3093
 
 
3094
@end defun
 
3095
 
 
3096
 
 
3097
@defun screen-p screen
 
3098
 
 
3099
@table @var
 
3100
@item screen-p
 
3101
Type @var{boolean}.
 
3102
@end table
 
3103
 
 
3104
 
 
3105
Returns non-@code{nil} if the @emph{screen} argument is a
 
3106
@end defun
 
3107
 
 
3108
 
 
3109
 
 
3110
@defun screen-plist screen
 
3111
 
 
3112
@table @var
 
3113
@item screen
 
3114
A @var{screen}.
 
3115
@end table
 
3116
 
 
3117
 
 
3118
Returns and (with @code{setf}) sets the property list for the
 
3119
specified @emph{screen}. This function provides a hook where
 
3120
extensions can add data.
 
3121
 
 
3122
@table @var
 
3123
@item plist
 
3124
Type @var{list}.
 
3125
@end table
 
3126
 
 
3127
@end defun
 
3128
 
 
3129
@defun screen-root screen
 
3130
 
 
3131
@table @var
 
3132
@item screen
 
3133
A @var{screen}.
 
3134
@end table
 
3135
 
 
3136
 
 
3137
Returns the @emph{root-window} for the specified
 
3138
@emph{screen}. This function is useful with functions that take a
 
3139
parent window as an argument. The class of the root window is always
 
3140
@var{:input-output}.
 
3141
 
 
3142
@table @var
 
3143
@item root-window
 
3144
Type @var{window} or @var{null}.
 
3145
@end table
 
3146
 
 
3147
@end defun
 
3148
 
 
3149
 
 
3150
@defun screen-root-depth screen
 
3151
 
 
3152
@table @var
 
3153
@item screen
 
3154
A @var{screen}.
 
3155
@end table
 
3156
 
 
3157
Returns the depth of the root window for the specified
 
3158
@emph{screen}. Other depths can also be supported on this
 
3159
@emph{screen}.
 
3160
 
 
3161
@table @var
 
3162
@item root-window-depth
 
3163
Type @var{image-depth}.
 
3164
@end table
 
3165
 
 
3166
@end defun
 
3167
 
 
3168
 
 
3169
@defun screen-root-visual screen
 
3170
 
 
3171
@table @var
 
3172
@item screen
 
3173
A @var{screen}.
 
3174
@end table
 
3175
 
 
3176
 
 
3177
Returns the default visual type for the root window for the
 
3178
specified @emph{screen}.
 
3179
 
 
3180
@table @var
 
3181
@item root-window-visual
 
3182
Type @var{card29}.
 
3183
@end table
 
3184
 
 
3185
@end defun
 
3186
 
 
3187
 
 
3188
@defun screen-save-unders-p screen
 
3189
 
 
3190
@table @var
 
3191
@item screen
 
3192
A screen.
 
3193
@end table
 
3194
 
 
3195
 
 
3196
If true, the server can support the save-under mode in
 
3197
@var{create-window} and in changing window attributes.
 
3198
 
 
3199
@table @var
 
3200
@item save-unders-p
 
3201
Type @var{boolean}.
 
3202
@end table
 
3203
 
 
3204
@end defun
 
3205
 
 
3206
 
 
3207
@defun screen-white-pixel screen
 
3208
 
 
3209
@table @var
 
3210
@item screen
 
3211
A screen.
 
3212
@end table
 
3213
 
 
3214
 
 
3215
Returns the white pixel value for the specified
 
3216
@emph{screen}.
 
3217
 
 
3218
@table @var
 
3219
@item white-pixel
 
3220
Type @var{pixel}.
 
3221
@end table
 
3222
 
 
3223
@end defun
 
3224
 
 
3225
 
 
3226
@defun screen-width screen
 
3227
 
 
3228
@table @var
 
3229
@item screen
 
3230
A screen.
 
3231
@end table
 
3232
 
 
3233
 
 
3234
Returns the width of the specified @emph{screen} in pixel
 
3235
units.
 
3236
 
 
3237
@table @var
 
3238
@item width
 
3239
Type @var{card16}.
 
3240
@end table
 
3241
 
 
3242
@end defun
 
3243
 
 
3244
 
 
3245
@defun screen-width-in-millimeters screen
 
3246
 
 
3247
@table @var
 
3248
@item screen
 
3249
A screen.
 
3250
@end table
 
3251
 
 
3252
 
 
3253
Returns the width of the specified @emph{screen} in millimeters. The
 
3254
returned width can be used with the height in millimeters to determine
 
3255
the physical size and the aspect ratio of the screen.
 
3256
 
 
3257
@table @var
 
3258
@item width-in-millimeters
 
3259
Type @var{card16}.
 
3260
@end table
 
3261
 
 
3262
@end defun
 
3263
 
 
3264
 
 
3265
@node Windows and Pixmaps, Graphics Contexts, Screens, Top
 
3266
@chapter Windows and Pixmaps
 
3267
 
 
3268
@menu
 
3269
* Drawables::
 
3270
* Creating Windows::
 
3271
* Window Attributes::
 
3272
* Stacking Order::
 
3273
* Window Hierarchy::
 
3274
* Mapping Windows::
 
3275
* Destroying Windows::
 
3276
* Pixmaps::
 
3277
@end menu
 
3278
 
 
3279
@node Drawables, Creating Windows, Windows and Pixmaps, Windows and Pixmaps
 
3280
@section Drawables
 
3281
 
 
3282
Both windows and pixmaps can be used as sources and destinations in
 
3283
graphics operations. These are collectively known as
 
3284
@emph{drawables}. The following functions apply to both windows and
 
3285
pixmaps.
 
3286
 
 
3287
@defun drawable-display drawable
 
3288
 
 
3289
@table @var
 
3290
@item drawable
 
3291
A @var{drawable} object.
 
3292
@end table
 
3293
 
 
3294
Returns the display for the specified @emph{drawable}.
 
3295
 
 
3296
@end defun
 
3297
 
 
3298
@defun drawable-equal drawable-1 drawable-2
 
3299
 
 
3300
@table @var
 
3301
@item drawable-1
 
3302
@itemx drawable-2
 
3303
@var{drawable} objects.
 
3304
@end table
 
3305
 
 
3306
Returns true if the two arguments refer to the same server resource,
 
3307
and @var{nil} if they do not.
 
3308
 
 
3309
@end defun
 
3310
 
 
3311
 
 
3312
@defun drawable-id drawable
 
3313
 
 
3314
@table @var
 
3315
@item drawable
 
3316
A @var{drawable} object.
 
3317
@end table
 
3318
 
 
3319
Returns the unique resource ID assigned to the specified
 
3320
@var{drawable}.
 
3321
 
 
3322
@table @var
 
3323
@item id
 
3324
Type @var{resource-id}.
 
3325
@end table
 
3326
 
 
3327
@end defun
 
3328
 
 
3329
@defun drawable-p drawable
 
3330
 
 
3331
@table @var
 
3332
@item boole
 
3333
Type @var{boolean}.
 
3334
@end table
 
3335
 
 
3336
Returns true if the argument is a @var{drawable} and @var{nil}
 
3337
otherwise.
 
3338
 
 
3339
@end defun
 
3340
 
 
3341
@defun drawable-plist drawable
 
3342
 
 
3343
@table @var
 
3344
@item plist
 
3345
A property list.
 
3346
@end table
 
3347
 
 
3348
Returns and (with @code{setf}) sets the property list for the specified
 
3349
@emph{drawable}. This function provides a hook where extensions can
 
3350
add data.
 
3351
 
 
3352
@end defun
 
3353
 
 
3354
@node Creating Windows, Window Attributes, Drawables, Windows and Pixmaps
 
3355
@section Creating Windows
 
3356
 
 
3357
 
 
3358
A window is a @var{drawable} that can also receive input events. CLX
 
3359
represents a window with a @var{window} object. The
 
3360
@var{create-window} function creates a new @var{window} object.
 
3361
 
 
3362
@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
 
3363
@anchor{create-window}
 
3364
 
 
3365
@table @var
 
3366
@item :parent
 
3367
The parent window. This argument is required.
 
3368
 
 
3369
@item :x
 
3370
@itemx :y
 
3371
@var{int16} coordinates for the outside upper-left corner of the new
 
3372
window with respect to the origin (inside upper-left corner) of the
 
3373
@var{:parent}. These arguments are required.
 
3374
 
 
3375
@item :width
 
3376
@itemx :height
 
3377
 
 
3378
@var{card16} values for the size of the new window. These arguments
 
3379
are required.
 
3380
 
 
3381
@item :depth
 
3382
 
 
3383
A @var{card16} specifying the depth of the new window.
 
3384
 
 
3385
@item :class
 
3386
 
 
3387
One of @var{:input-outpu}t, @var{:input-only}, or @var{:copy}.
 
3388
 
 
3389
@item :visual
 
3390
 
 
3391
A @var{card29} ID specifying the visual type of the new window.
 
3392
 
 
3393
@item :background
 
3394
@itemx :backing-pixel
 
3395
@itemx :backing-planes
 
3396
@itemx :backing-store
 
3397
@itemx :bit-gravity
 
3398
@itemx :border
 
3399
@itemx :border-width
 
3400
@itemx :colormap
 
3401
@itemx :cursor
 
3402
@itemx :do-not-propagate-mask
 
3403
@itemx :event
 
3404
@itemx :gravity
 
3405
@itemx :override-redirect
 
3406
@itemx :save-under
 
3407
 
 
3408
Initial attribute values for the new window. If @var{nil}, the default
 
3409
value is defined by the X protocol.See paragraph
 
3410
@end table
 
3411
 
 
3412
Creates and returns a window. A @var{:parent} window must be
 
3413
specified; the first window created by a client will have a root
 
3414
window as its @var{:parent}. The new window is initially unmapped and
 
3415
is placed on top of its siblings in the stacking order. A
 
3416
@var{:create-notify} event is generated by the server.
 
3417
 
 
3418
The @var{:class} of a window can be @var{:input-output} or
 
3419
@var{:input-only}. Windows of class @var{:input-only} cannot be used
 
3420
as the destination drawable for graphics output and can never receive
 
3421
@var{:exposure} events, but otherwise operate the same as
 
3422
@var{:input-output} windows. The @var{:class} can also be @var{:copy},
 
3423
in which case the new window has the same class as its @var{:parent}.
 
3424
 
 
3425
For an @var{:input-output} window, the @var{:visual} and @var{:depth}
 
3426
must be a combination supported by the @var{:parent}'s screen, but the
 
3427
@var{:depth} need not be the same as the @var{:parent}'s. The
 
3428
@var{:parent} of an @var{:input-output} window must also be
 
3429
@var{:input-output}. A @var{:depth} of 0 means that the depth of the
 
3430
@var{:parent} is used.
 
3431
 
 
3432
For an @var{:input-only} window, the @var{:depth} must be zero, and
 
3433
the @var{:visual} must be supported by the @var{:parent}'s screen. The
 
3434
@var{:parent} of an @var{:input-only} window can be of any class. The
 
3435
only attributes that can be given for an @var{:input-only} window are
 
3436
@var{:cursor}, @var{:do-not-propagate-mask}, @var{:event-mask},
 
3437
@var{:gravity}, and @var{:override-redirect}.
 
3438
 
 
3439
@table @var
 
3440
@item window
 
3441
Type @var{window}.
 
3442
@end table
 
3443
 
 
3444
@end defun
 
3445
 
 
3446
@node Window Attributes, Stacking Order, Creating Windows, Windows and Pixmaps
 
3447
@section Window Attributes
 
3448
 
 
3449
 
 
3450
The following paragraphs describe the CLX functions used to return or
 
3451
change window attributes. Using the @var{with-state} macro improves
 
3452
the performance of attribute access by batching related accesses in
 
3453
the minimum number of server requests.
 
3454
 
 
3455
@defun drawable-border-width drawable
 
3456
 
 
3457
@table @var
 
3458
@item drawable
 
3459
A @var{drawable} object.
 
3460
@end table
 
3461
 
 
3462
Returns the @emph{border-width} of the @emph{drawable} in pixels. It
 
3463
always returns zero if the @emph{drawable} is a pixmap or an
 
3464
@var{:input-only} window. Used with @code{setf}, this function also
 
3465
changes the border width of the @var{:input-only} window. The default
 
3466
border width of a new window is zero.
 
3467
 
 
3468
Changing just the border width leaves the outer left corner of a
 
3469
window in a fixed position but moves the absolute position of the
 
3470
window's origin. It is an error to make the border width of an
 
3471
@var{:input-only} window nonzero.
 
3472
 
 
3473
When changing the border-width of a window, if the override-redirect
 
3474
attribute of the window is @var{:off} and some other client has
 
3475
selected @var{:substructure-redirect} on the parent, a
 
3476
@var{:configure-request} event is generated, and no further processing
 
3477
is performed.  Otherwise, the border-width is changed.
 
3478
 
 
3479
@table @var
 
3480
@item border-width
 
3481
Type @var{card16}.
 
3482
@end table
 
3483
 
 
3484
@end defun
 
3485
 
 
3486
 
 
3487
@defun drawable-depth drawable
 
3488
 
 
3489
@table @var
 
3490
@item drawable
 
3491
A @var{drawable} object.
 
3492
@end table
 
3493
 
 
3494
Returns the depth of the specified @emph{drawable} (bits per pixel).
 
3495
 
 
3496
@table @var
 
3497
@item depth
 
3498
Type @var{card8}.
 
3499
@end table
 
3500
 
 
3501
@end defun
 
3502
 
 
3503
 
 
3504
@defun drawable-height drawable
 
3505
 
 
3506
@table @var
 
3507
@item inside-height
 
3508
Type @var{card16}.
 
3509
@end table
 
3510
 
 
3511
@end defun
 
3512
 
 
3513
 
 
3514
@defun drawable-width drawable
 
3515
 
 
3516
@table @var
 
3517
@item drawable
 
3518
A @var{drawable} object.
 
3519
@end table
 
3520
 
 
3521
These functions return the height or width of the
 
3522
@emph{drawable}. These coordinates define the inside size of the
 
3523
@emph{drawable}, in pixels. Used with @code{setf}, these functions also
 
3524
change the inside height or width of a window. However, the height or
 
3525
width of a pixmap cannot be changed.
 
3526
 
 
3527
Changing the width and height resizes a window without changing its
 
3528
position or stacking priority.
 
3529
 
 
3530
Changing the size of a mapped window may cause the window to lose its
 
3531
contents and generate an @var{:exposure} event. If a mapped window is
 
3532
made smaller, @var{:exposure} events are generated on windows that it
 
3533
formerly obscured.
 
3534
 
 
3535
When changing the size of a window, if the override-redirect attribute
 
3536
of the window is @var{:off} and some other client has selected
 
3537
@var{:substructure-redirect} on the parent, a @var{:configure-request}
 
3538
event is generated, and no further processing is performed. Otherwise,
 
3539
if another client has selected @var{:resize-redirect} on the window, a
 
3540
@var{:resize-request} event is generated, and the current inside width
 
3541
and height are maintained. Note that the override-redirect attribute
 
3542
of the window has no effect on @var{:resize-redirect} and that
 
3543
@var{:substructure-redirect} on the parent has precedence over
 
3544
@var{:resize-redirect} on the window.
 
3545
 
 
3546
When the inside size of the window is changed, the children of the
 
3547
window can move according to their window gravity. Depending on the
 
3548
window's bit gravity, the contents of the window can also be moved.
 
3549
 
 
3550
@table @var
 
3551
@item inside-width
 
3552
Type @var{card16}.
 
3553
@end table
 
3554
 
 
3555
@end defun
 
3556
 
 
3557
 
 
3558
@defun drawable-x drawable
 
3559
 
 
3560
@table @var
 
3561
@item outside-left
 
3562
Type @var{int16}.
 
3563
@end table
 
3564
 
 
3565
@end defun
 
3566
 
 
3567
 
 
3568
@defun drawable-y drawable
 
3569
 
 
3570
@table @var
 
3571
@item drawable
 
3572
A @var{drawable} object.
 
3573
@end table
 
3574
 
 
3575
These functions return the x or y coordinate of the specified
 
3576
@emph{drawable}. They always return zero if the @emph{drawable} is a
 
3577
pixmap. These coordinates define the location of the top left pixel of
 
3578
the window's border or of the window, if it has no border. Used with
 
3579
@code{setf}, these functions also change the x or y coordinate of a
 
3580
window. However, the x or y coordinate of a pixmap cannot be changed.
 
3581
 
 
3582
Changing the x and y coordinates moves a window without changing its
 
3583
size or stacking priority. Moving a mapped window generates
 
3584
@var{:exposure} events on any formerly obscured windows.
 
3585
 
 
3586
When changing the position of a window, if the override-redirect
 
3587
attribute of the window is @var{:off} and some other client has
 
3588
selected @var{:substructure-redirect} on the parent, a
 
3589
@var{:configure-request} event is generated, and no further processing
 
3590
is performed.  Otherwise, the window is moved.
 
3591
 
 
3592
@table @var
 
3593
@item outside-top
 
3594
Type @var{int16}.
 
3595
@end table
 
3596
 
 
3597
@end defun
 
3598
 
 
3599
 
 
3600
@defun window-all-event-masks window
 
3601
 
 
3602
@table @var
 
3603
@item window
 
3604
A @var{window}.
 
3605
@end table
 
3606
 
 
3607
Returns the inclusive-or of the event masks selected on the
 
3608
specified @emph{window} by all clients.
 
3609
@table @var
 
3610
@item all-event-masks
 
3611
Type @var{mask32}.
 
3612
@end table
 
3613
 
 
3614
@end defun
 
3615
 
 
3616
 
 
3617
@defun setf (window-background) window background
 
3618
 
 
3619
@table @var
 
3620
@item window
 
3621
A @var{window}.
 
3622
@item background
 
3623
Either a @var{pixel}, a @var{pixmap}, @var{:none}, or @var{:parent-relative}.
 
3624
@end table
 
3625
 
 
3626
Changes the @emph{background} attribute of the @emph{window} to the
 
3627
specified value. This operation is not allowed on an @var{:input-only}
 
3628
window. Changing the background does not cause the window contents to
 
3629
be changed. Note that the background of a window cannot be returned
 
3630
from the X server. The default background of a new window is
 
3631
@var{:none}.
 
3632
 
 
3633
In general, the server automatically fills in exposed areas of the
 
3634
window when they are first made visible. A background pixmap is tiled
 
3635
to fill each area. However, if the background is @var{:none}, the
 
3636
server will not modify exposed areas. If the background is
 
3637
@var{:parent-relative}, the window and its parent must have the same
 
3638
depth. In this case, the window shares the same background as its
 
3639
parent. The parent's background is not copied and is reexamined
 
3640
whenever the window's background is required. If the background is
 
3641
@var{:parent-relative}, the background pixmap tile origin is the same
 
3642
as the parent's; otherwise, the tile origin is the window origin.
 
3643
 
 
3644
@table @var
 
3645
@item background
 
3646
Either a @var{pixel}, a @var{pixmap}, @var{:none}, or @var{:parent-relative}.
 
3647
@end table
 
3648
 
 
3649
@end defun
 
3650
 
 
3651
 
 
3652
@defun window-backing-pixel window
 
3653
 
 
3654
@table @var
 
3655
@item window
 
3656
A @var{window}.
 
3657
@end table
 
3658
 
 
3659
Returns and (with @code{setf}) changes the value of the backing-pixel
 
3660
attribute for the specified @emph{window}. Changing the backing-pixel
 
3661
attribute of a mapped window may have no immediate effect. The default
 
3662
backing-pixel of a new window is zero.
 
3663
 
 
3664
@table @var
 
3665
@item backing-pixel
 
3666
Type @var{pixel}.
 
3667
@end table
 
3668
 
 
3669
@end defun
 
3670
 
 
3671
 
 
3672
@defun window-backing-planes window
 
3673
 
 
3674
@table @var
 
3675
@item window
 
3676
A @var{window}.
 
3677
@end table
 
3678
 
 
3679
Returns and (with @code{setf}) changes the value of the backing-planes
 
3680
attribute for the specified @emph{window}. Changing the backing-planes
 
3681
attribute of a mapped window may have no immediate effect. The default
 
3682
backing-planes of a new window is all one's.
 
3683
 
 
3684
@table @var
 
3685
@item backing-planes
 
3686
Type @var{pixel}.
 
3687
@end table
 
3688
 
 
3689
@end defun
 
3690
 
 
3691
 
 
3692
@defun window-backing-store window
 
3693
 
 
3694
@table @var
 
3695
@item window
 
3696
A @var{window}.
 
3697
@end table
 
3698
 
 
3699
Returns and (with @code{setf}) changes the value of the backing-store
 
3700
attribute for the specified @emph{window}. Changing the backing-store
 
3701
attribute of an obscured window to @var{:when-mapped} or @var{:always}
 
3702
may have no immediate effect. The default backing-store of a new
 
3703
window is @var{:not-useful}.
 
3704
 
 
3705
@table @var
 
3706
@item backing-store-type
 
3707
One of @var{:always}, @var{:not-useful}, or @var{:when-mapped}.
 
3708
@end table
 
3709
 
 
3710
@end defun
 
3711
 
 
3712
 
 
3713
@defun window-bit-gravity window
 
3714
 
 
3715
@table @var
 
3716
@item window
 
3717
A @var{window}.
 
3718
@end table
 
3719
 
 
3720
Returns and (with @code{setf}) changes the bit-gravity attribute of the
 
3721
@emph{window}. If a window is reconfigured without changing its inside
 
3722
width or height, the contents of the window move with the window and
 
3723
are not lost. Otherwise, the contents of the resized window are either
 
3724
moved or lost, depending on its bit-gravity attribute. The default
 
3725
bit-gravity of a new window is @var{:forget}.
 
3726
 
 
3727
For example, suppose a window's size is changed by @emph{W} pixels
 
3728
in width and @emph{H} pixels in height. The following table shows,
 
3729
for each bit-gravity value, the change in position (relative to the
 
3730
window origin) that results for each pixel of the window contents.
 
3731
 
 
3732
@multitable {Bit-Gravity} {X Change} {Y Change}
 
3733
@item @var{:center} @tab @emph{W/}2 @tab @emph{H/}2
 
3734
@item @var{:east} @tab @emph{W} @tab @emph{H/}2
 
3735
@item @var{:north} @tab @emph{W/}2 @tab 0
 
3736
@item @var{:north-east} @tab @emph{W} @tab 0
 
3737
@item @var{:north-west} @tab 0 @tab 0
 
3738
@item @var{:south} @tab @emph{W/}2 @tab @emph{H}
 
3739
@item @var{:south-east} @tab W @tab H
 
3740
@item @var{:south-west} @tab 0 @tab H
 
3741
@item @var{:west} @tab 0 @tab H/2
 
3742
@end multitable
 
3743
 
 
3744
 
 
3745
A @var{:static} bit-gravity indicates the contents or window should
 
3746
not move relative to the origin of the root window.
 
3747
 
 
3748
A server can choose to ignore the specified bit-gravity attribute
 
3749
and use @var{:forget} instead.  A @var{:forget} bit-gravity
 
3750
attribute indicates that the window contents are always discarded
 
3751
after a size change, even if backing-store or save-under attributes
 
3752
are @var{:on}. The window's background is displayed (unless it is
 
3753
@var{:none}), and zero or more @var{:exposure} events are
 
3754
generated.
 
3755
@table @var
 
3756
@item bit-gravity
 
3757
Type @var{bit-gravity}.
 
3758
@end table
 
3759
 
 
3760
@end defun
 
3761
 
 
3762
 
 
3763
@defun setf (window-border) window border
 
3764
 
 
3765
@table @var
 
3766
@item window
 
3767
A @var{window}.
 
3768
@item border
 
3769
Either a @var{pixel}, a @var{pixmap}, or @var{:copy}.
 
3770
@end table
 
3771
 
 
3772
Changes the @emph{border} attribute of the @emph{window} to the
 
3773
specified value. This operation is not allowed on an
 
3774
@var{:input-only} window. Changing the border attribute also causes
 
3775
the window border to be repainted. Note that the border of a window
 
3776
cannot be returned from the X server. The default border of a new
 
3777
window is @var{:copy}.
 
3778
 
 
3779
A border pixmap is tiled to fill the border. The border pixmap tile
 
3780
origin is the same as the background tile origin. A border pixmap
 
3781
and the window must have the same root and depth. If the border is
 
3782
@var{:copy}, the parent's border is copied and used; subsequent
 
3783
changes to the parent's border do not affect the window border.
 
3784
@table @var
 
3785
@item border
 
3786
Either a @var{pixel}, a @var{pixmap}, or @var{:copy}.
 
3787
@end table
 
3788
 
 
3789
@end defun
 
3790
 
 
3791
 
 
3792
@defun window-class window
 
3793
 
 
3794
@table @var
 
3795
@item window
 
3796
A @var{window}.
 
3797
@end table
 
3798
 
 
3799
Returns the @emph{class} of the specified @emph{window}.
 
3800
@table @var
 
3801
@item class
 
3802
Either @var{:input-output} or @var{:input-only}.
 
3803
@end table
 
3804
 
 
3805
@end defun
 
3806
 
 
3807
 
 
3808
@defun window-colormap window
 
3809
 
 
3810
@table @var
 
3811
@item window
 
3812
A @var{window}.
 
3813
@end table
 
3814
 
 
3815
Returns and (with @code{setf}) changes the value of the colormap
 
3816
attribute for the specified @emph{window}. A value of @var{:copy} is
 
3817
never returned, since the parent's colormap attribute is actually
 
3818
copied, but the attribute can be set to @var{:copy} in a @code{setf}
 
3819
form. Changing the colormap of a window (defining a new map, not
 
3820
changing the contents of the existing map) generates a
 
3821
@var{:colormap-notify} event. Changing the colormap of a visible
 
3822
window may have no immediate effect on the screen
 
3823
(@pxref{install-colormap}). The default colormap of a new window is
 
3824
@var{:copy}.
 
3825
@table @var
 
3826
@item colormap
 
3827
Type @var{colormap} or @var{null}.
 
3828
@end table
 
3829
 
 
3830
@end defun
 
3831
 
 
3832
 
 
3833
@defun window-colormap-installed-p window
 
3834
 
 
3835
@table @var
 
3836
@item window
 
3837
A @var{window}.
 
3838
@end table
 
3839
 
 
3840
Returns non-@var{nil} if the colormap associated with this
 
3841
@emph{window} is installed. Otherwise, this function returns
 
3842
@var{nil}.
 
3843
@table @var
 
3844
@item colormap-installed-p
 
3845
Type @var{boolean}.
 
3846
@end table
 
3847
 
 
3848
@end defun
 
3849
 
 
3850
 
 
3851
@defun setf (window-cursor) window cursor
 
3852
 
 
3853
@table @var
 
3854
@item window
 
3855
A @var{window}.
 
3856
@item cursor
 
3857
Either @var{cursor} or @var{:none}.
 
3858
@end table
 
3859
 
 
3860
Changes the @emph{cursor} attribute of the @emph{window} to the
 
3861
specified value. Changing the cursor of a root window to @var{:none}
 
3862
restores the default cursor. Note that the cursor of window cannot be
 
3863
returned from the X server. The default cursor of a new window is
 
3864
@var{:none}.
 
3865
 
 
3866
@table @var
 
3867
@item cursor
 
3868
Type @var{cursor} or @var{:none}.
 
3869
@end table
 
3870
 
 
3871
@end defun
 
3872
 
 
3873
 
 
3874
@defun window-display window
 
3875
 
 
3876
@table @var
 
3877
@item window
 
3878
A @var{window}.
 
3879
@end table
 
3880
 
 
3881
Returns the @var{display} object associated with the specified
 
3882
@emph{window}.
 
3883
@table @var
 
3884
@item display
 
3885
Type @var{display}.
 
3886
@end table
 
3887
 
 
3888
@end defun
 
3889
 
 
3890
 
 
3891
@defun window-do-not-propagate-mask window
 
3892
 
 
3893
@table @var
 
3894
@item window
 
3895
A @var{window}.
 
3896
@end table
 
3897
 
 
3898
Returns and (with @code{setf}) changes the do-not-propagate-mask
 
3899
attribute for the window.  The default do-not-propagate-mask of a new
 
3900
window is zero.
 
3901
 
 
3902
If a window receives an event from one of the user input devices, and
 
3903
if no client has selected to receive the event, the event can instead
 
3904
be propagated up the window hierarchy to the first ancestor for which
 
3905
some client has selected it. However, any event type selected by the
 
3906
do-not-propagate-mask is not be propagated. The types of events that
 
3907
can be selected by the do-not-propagate-mask are those of type
 
3908
@var{device-event-mask-class}. @xref{Selecting Events}.
 
3909
@table @var
 
3910
@item do-not-propagate-mask
 
3911
Type @var{mask32}.
 
3912
@end table
 
3913
 
 
3914
@end defun
 
3915
 
 
3916
 
 
3917
@defun window-equal window-1 window-2
 
3918
 
 
3919
@table @var
 
3920
@item window-1
 
3921
@itemx window-2
 
3922
The windows to compare for equality.
 
3923
@end table
 
3924
 
 
3925
Returns non-@var{nil} if the two arguments are the same window, and
 
3926
@var{nil} if they are not.
 
3927
@table @var
 
3928
@item equal-p
 
3929
Type @var{boolean}.
 
3930
@end table
 
3931
 
 
3932
@end defun
 
3933
 
 
3934
 
 
3935
@defun window-event-mask window
 
3936
 
 
3937
@table @var
 
3938
@item window
 
3939
A @var{window}.
 
3940
@end table
 
3941
 
 
3942
Returns and (with @code{setf}) changes the value of the event-mask
 
3943
attribute for the @emph{window}.  The default event-mask of a new
 
3944
window is zero.
 
3945
@table @var
 
3946
@item event-mask
 
3947
Type @var{mask32}.
 
3948
@end table
 
3949
 
 
3950
@end defun
 
3951
 
 
3952
 
 
3953
@defun window-gravity window
 
3954
 
 
3955
@table @var
 
3956
@item window
 
3957
A @var{window}.
 
3958
@end table
 
3959
 
 
3960
Returns and (with @code{setf}) changes the gravity attribute of the
 
3961
@emph{window}. If a parent window is reconfigured without changing its
 
3962
inside width or height, then all child windows move with the parent
 
3963
and are not changed. Otherwise, each child of the resized parent is
 
3964
moved, depending on the child's gravity attribute. The default gravity
 
3965
of a new window is @var{:north-west}.
 
3966
 
 
3967
For example, suppose the size of the window's parent is changed by
 
3968
@emph{W} pixels in width and @emph{H} pixels in height. The following
 
3969
table shows, for each possible gravity value, the resulting change in
 
3970
the window's position relative to its parent's origin. When the window
 
3971
is moved, two events are generated--a @var{:configure-notify} event
 
3972
followed by a @var{:gravity-notify} event.
 
3973
 
 
3974
@multitable {Gravity} {X Change} {Y Change}
 
3975
@item @var{:center} @tab @emph{W/}2 @tab @emph{H/}2
 
3976
@item @var{:east} @tab @emph{W} @tab @emph{H/}2
 
3977
@item @var{:north} @tab @emph{W/}2 @tab 0
 
3978
@item @var{:north-east} @tab @emph{W} @tab 0
 
3979
@item @var{:north-west} @tab 0 @tab 0
 
3980
@item @var{:south} @tab @emph{W/}2 @tab @emph{H}
 
3981
@item @var{:south-east} @tab W @tab H
 
3982
@item @var{:south-west} @tab 0 @tab H
 
3983
@item @var{:west} @tab 0 @tab H/2
 
3984
@end multitable
 
3985
 
 
3986
 
 
3987
A @var{:static} gravity indicates that the position of the window
 
3988
should not move relative to the origin of the root window.
 
3989
 
 
3990
An @var{:unmap} gravity is like @var{:north-west}, except the window
 
3991
is also unmapped and an @var{:unmap-notify} event is generated. This
 
3992
@var{:unmap-notify} event is generated after the
 
3993
@var{:configure-notify} event is generated for the parent.
 
3994
@table @var
 
3995
@item gravity
 
3996
Type @var{win-gravity}.
 
3997
@end table
 
3998
 
 
3999
@end defun
 
4000
 
 
4001
 
 
4002
@defun window-id window
 
4003
 
 
4004
@table @var
 
4005
@item window
 
4006
A @var{window}.
 
4007
@end table
 
4008
 
 
4009
Returns the unique ID assigned to @emph{window}.
 
4010
@table @var
 
4011
@item id
 
4012
Type @var{resource-id}.
 
4013
@end table
 
4014
 
 
4015
@end defun
 
4016
 
 
4017
 
 
4018
@defun window-map-state window
 
4019
 
 
4020
@table @var
 
4021
@item window
 
4022
A @var{window}.
 
4023
@end table
 
4024
 
 
4025
Returns the map state of @emph{window}. A window is @var{:unviewable}
 
4026
if it is mapped but some ancestor is unmapped.
 
4027
@table @var
 
4028
@item map-state
 
4029
One of @var{:unmapped}, @var{:unviewable}, or @var{:viewable}.
 
4030
@end table
 
4031
 
 
4032
@end defun
 
4033
 
 
4034
 
 
4035
@defun window-override-redirect window
 
4036
 
 
4037
@table @var
 
4038
@item window
 
4039
A @var{window}.
 
4040
@end table
 
4041
 
 
4042
Returns and (with @code{setf}) changes the value of the
 
4043
override-redirect attribute for @emph{window}.  The default
 
4044
override-redirect of a new window is @var{:off}.
 
4045
 
 
4046
The override-redirect attribute determines whether or not attempts to
 
4047
change window geometry or parent hierarchy can be @emph{redirected} by
 
4048
a window manager or some other client. The functions that might be
 
4049
affected by the override-redirect attribute are
 
4050
@var{circulate-window-down}, @var{circulate-window-up},
 
4051
@var{drawable-border-width}, @var{drawable-height},
 
4052
@var{drawable-width}, @var{drawable-x}, @var{drawable-y},
 
4053
@var{map-window}, and @var{window-priority}.
 
4054
@table @var
 
4055
@item override-redirect
 
4056
Either @var{:on} or @var{:off}.
 
4057
@end table
 
4058
 
 
4059
@end defun
 
4060
 
 
4061
 
 
4062
@defun window-p object
 
4063
 
 
4064
@table @var
 
4065
@item window-p
 
4066
Type @var{boolean}.
 
4067
@end table
 
4068
 
 
4069
Returns non-@var{nil} if the @emph{object} argument is a window; otherwise, it returns @var{nil}.
 
4070
@end defun
 
4071
 
 
4072
@defun window-plist window
 
4073
 
 
4074
@table @var
 
4075
@item window
 
4076
A @var{window}.
 
4077
@end table
 
4078
 
 
4079
Returns and (with @code{setf}) sets the property list for the specified
 
4080
@emph{window}. This function provides a hook where extensions can hang
 
4081
data.
 
4082
@table @var
 
4083
@item plist
 
4084
A property list.
 
4085
@end table
 
4086
 
 
4087
@end defun
 
4088
 
 
4089
 
 
4090
 
 
4091
@defun setf (window-priority window) (&optional sibling) mode
 
4092
 
 
4093
@table @var
 
4094
@item window
 
4095
A @var{window}.
 
4096
 
 
4097
@item sibling
 
4098
An optional argument specifying that @emph{window} is to be restacked
 
4099
relative to this sibling @var{window}.
 
4100
 
 
4101
@item mode
 
4102
One of @var{:above}, @var{:below}, @var{:bottom-if}, @var{:opposite}, or @var{:top-if}.
 
4103
@end table
 
4104
 
 
4105
Changes the stacking priority element of the @emph{window} to the
 
4106
specified value. It is an error if the @emph{sibling} argument is
 
4107
specified and is not actually a sibling of the window. Note that the
 
4108
priority of an existing window cannot be returned from the X server.
 
4109
 
 
4110
When changing the priority of a window, if the override-redirect
 
4111
attribute of the window is @var{:off} and some other client has
 
4112
selected :substructure-redirect on the parent, a :configure-request
 
4113
event is generated, and no further processing is
 
4114
performed. Otherwise, the priority is changed.
 
4115
@table @var
 
4116
@item mode
 
4117
One of @var{:above}, @var{:below}, @var{:bottom-if}, @var{:opposite}, or @var{:top-if}.
 
4118
@end table
 
4119
 
 
4120
@end defun
 
4121
 
 
4122
 
 
4123
@defun window-save-under window
 
4124
 
 
4125
@table @var
 
4126
@item window
 
4127
A @var{window}.
 
4128
@end table
 
4129
 
 
4130
Returns and (with @code{setf}) changes the value of the save-under
 
4131
attribute for the specified @emph{window}. Changing the save-under
 
4132
attribute of a mapped window may have no immediate effect.
 
4133
@table @var
 
4134
@item save-under
 
4135
Either @var{:on} or @var{:off}.
 
4136
@end table
 
4137
 
 
4138
@end defun
 
4139
 
 
4140
@defun window-visual window
 
4141
 
 
4142
@table @var
 
4143
@item window
 
4144
A @var{window}.
 
4145
@end table
 
4146
 
 
4147
Returns the @emph{visual-type} associated with the specified @emph{window}.
 
4148
@table @var
 
4149
@item visual-type
 
4150
Type @var{card29}.
 
4151
@end table
 
4152
 
 
4153
@end defun
 
4154
 
 
4155
 
 
4156
 
 
4157
@defmac with-state drawable &body body
 
4158
@anchor{with-state}
 
4159
 
 
4160
Batches successive read and write accesses to window attributes and
 
4161
drawable geometry, in order to minimize the number of requests sent to
 
4162
the server. Batching occurs automatically within the dynamic extent of
 
4163
the @emph{body}. The @emph{body} is not executed within a
 
4164
@var{with-display} form.
 
4165
 
 
4166
All window attributes can be returned or changed in a single
 
4167
request. Similarly, all drawable geometry values can be returned or
 
4168
changed in a single request. @var{with-state} combines accesses to
 
4169
these values into the minimum number of server requests necessary to
 
4170
guarantee that each read access returns the current server state of
 
4171
the @emph{drawable}.  The number of server requests sent depends on
 
4172
the sequence of calls to reader and @code{setf} functions within the
 
4173
dynamic extent of the @emph{body}. There are two groups of reader and
 
4174
@code{setf} functions--the Window Attributes group and the Drawable
 
4175
Geometry group--as shown in Table 4-1.
 
4176
 
 
4177
@multitable {Group} {Reader Functions} {Setf Functions}
 
4178
 
 
4179
@item Window Attributes @tab @var{window-all-event-masks} @tab @var{window-background}
 
4180
 
 
4181
@item @tab @var{window-backing-pixel} @tab @var{window-backing-pixel}
 
4182
@item @tab @var{window-backing-planes} @tab @var{window-backing-planes}
 
4183
@item @tab @var{window-backing-store} @tab @var{window-backing-store}
 
4184
@item @tab @var{window-bit-gravity} @tab @var{window-bit-gravity}
 
4185
@item @tab @var{window-class} @tab @var{window-border}
 
4186
@item @tab @var{window-colormap} @tab @var{window-colormap}
 
4187
@item @tab @var{window-colormap-installed-p} @tab @var{window-cursor}
 
4188
@item @tab @var{window-do-not-propagate-mask} @tab @var{window-do-not-propagate-mask}
 
4189
@item @tab @var{window-event-mask} @tab @var{window-event-mask}
 
4190
@item @tab @var{window-gravity} @tab @var{window-gravity}
 
4191
@item @tab @var{window-map-state} @tab
 
4192
@item @tab @var{window-override-redirect} @tab @var{window-override-redirect}
 
4193
@item @tab @var{window-save-under} @tab @var{window-save-under}
 
4194
@item @tab @var{window-visual} @tab
 
4195
 
 
4196
@item Drawable Geometry @tab @var{drawable-border-width} @tab @var{drawable-border-width}
 
4197
 
 
4198
@item @tab @var{drawable-depth} @tab @var{drawable-height}
 
4199
@item @tab @var{drawable-height} @tab @var{drawable-width}
 
4200
@item @tab @var{drawable-root} @tab @var{drawable-x}
 
4201
@item @tab @var{drawable-width} @tab @var{drawable-y}
 
4202
@item @tab @var{drawable-x} @tab @var{window-priority}
 
4203
@item @tab @var{drawable-y} @tab
 
4204
 
 
4205
@end multitable
 
4206
 
 
4207
 
 
4208
The results from a sequence of calls to @code{setf} functions in a
 
4209
given group are cached and sent in a single server request, either
 
4210
upon exit from the @emph{body} or when a reader function from the
 
4211
corresponding group is called.
 
4212
 
 
4213
@var{with-state} sends a single request to update all its cached
 
4214
values for the @emph{drawable} before the first call to a reader
 
4215
function within the @emph{body} and also before the first call to a
 
4216
reader function following a sequence of calls to @code{setf} functions
 
4217
from the corresponding group.
 
4218
 
 
4219
@table @var
 
4220
@item drawable
 
4221
A @var{display}.
 
4222
@item body
 
4223
The forms in which attributes accesses are batched.
 
4224
@end table
 
4225
 
 
4226
@end defmac
 
4227
 
 
4228
 
 
4229
@node Stacking Order, Window Hierarchy, Window Attributes, Windows and Pixmaps
 
4230
@section Stacking Order
 
4231
 
 
4232
 
 
4233
Sibling windows can @emph{stack} on top of each other. Windows above
 
4234
can @emph{obscure} or @emph{occlude} lower windows. This relationship
 
4235
between sibling windows is known as the stacking order. The
 
4236
@var{window-priority} function can be used to change the stacking
 
4237
order of a single window. CLX also provides functions to raise or
 
4238
lower children of a window.  Raising a mapped window can generate
 
4239
@var{:exposure} events for the window and any mapped subwindows that
 
4240
were formerly obscured. Lowering a mapped window can generate
 
4241
@var{:exposure} events on any windows it formerly obscured.
 
4242
 
 
4243
@defun circulate-window-down window
 
4244
 
 
4245
@table @var
 
4246
@item window
 
4247
A @var{window}.
 
4248
@end table
 
4249
 
 
4250
Lowers the highest mapped child of the specified @emph{window} that
 
4251
partially or completely occludes another child to the bottom of the
 
4252
stack. Completely unobscured children are unaffected. Exposure
 
4253
processing is performed on formerly obscured windows.
 
4254
 
 
4255
If some other client has selected @var{:substructure-redirect} on the
 
4256
@emph{window}, a @var{:circulate-request} event is generated, and no
 
4257
further processing is performed. Otherwise, the child window is
 
4258
lowered and a @var{:circulate-notify} event is generated if the
 
4259
@emph{window} is actually restacked.
 
4260
 
 
4261
@end defun
 
4262
 
 
4263
 
 
4264
@defun circulate-window-up window
 
4265
 
 
4266
@table @var
 
4267
@item window
 
4268
A @var{window}.
 
4269
@end table
 
4270
 
 
4271
Raises the lowest mapped child of the specified @emph{window} that is
 
4272
partially or completely occluded by another child to the top of the
 
4273
stack. Completely unobscured children are unaffected. Exposure
 
4274
processing is performed on formerly obscured windows.
 
4275
 
 
4276
If another client has selected @var{:substructure-redirect} on the
 
4277
@emph{window}, a @var{:circulate-request} event is generated, and no
 
4278
further processing is performed. Otherwise, the child window is raised
 
4279
and a @var{:circulate-notify} event is generated if the @emph{window}
 
4280
is actually restacked.
 
4281
 
 
4282
@end defun
 
4283
 
 
4284
@node Window Hierarchy, Mapping Windows, Stacking Order, Windows and Pixmaps
 
4285
@section Window Hierarchy
 
4286
 
 
4287
 
 
4288
All the windows in X are arranged in a strict hierarchy. At the top of
 
4289
the hierarchy are the root windows, which cover the display
 
4290
screens. Each root window is partially or completely covered by its
 
4291
child windows. All windows, except for root windows, have
 
4292
parents. Child windows can have their own children. In this way, a
 
4293
tree of arbitrary depth on each screen can be created. CLX provides
 
4294
several functions for examining and modifying the window hierarchy.
 
4295
 
 
4296
@defun drawable-root drawable
 
4297
 
 
4298
@table @var
 
4299
@item drawable
 
4300
A @var{drawable}.
 
4301
@end table
 
4302
 
 
4303
Returns the root window of the specified @emph{drawable}.
 
4304
 
 
4305
@table @var
 
4306
@item root-window
 
4307
Type @var{window}.
 
4308
@end table
 
4309
 
 
4310
@end defun
 
4311
 
 
4312
@defun query-tree window &key (:result-type `list)
 
4313
 
 
4314
@table @var
 
4315
@item window
 
4316
A @var{window}.
 
4317
@item :result-type
 
4318
A valid type specifier for a sub-type of @var{sequence}. The default is a @var{list}.
 
4319
@end table
 
4320
 
 
4321
Returns the @emph{children} windows, the @emph{parent} window, and the
 
4322
@emph{root} window for the specified @emph{window}. The children are
 
4323
returned as a sequence of windows in current stacking order, from
 
4324
bottom-most (first) to top-most (last). The @var{:result-type}
 
4325
specifies the type of children sequence returned.
 
4326
 
 
4327
@table @var
 
4328
@item children
 
4329
Type @var{sequence} of @var{window}.
 
4330
@item parent
 
4331
Type @var{window} or @var{null}.
 
4332
@item root
 
4333
Type @var{window}.
 
4334
@end table
 
4335
 
 
4336
@end defun
 
4337
 
 
4338
 
 
4339
@defun reparent-window window parent x y
 
4340
 
 
4341
@table @var
 
4342
@item window
 
4343
A @var{window}.
 
4344
@item parent
 
4345
The new parent @var{window}.
 
4346
@item x
 
4347
@itemx y
 
4348
The position (type @var{int16}) of the @emph{window} in its new
 
4349
@emph{parent}. These coordinates are relative to the @emph{parent}'s
 
4350
origin, and specify the new position of the upper, left, outer corner
 
4351
of the @emph{window}.
 
4352
@end table
 
4353
 
 
4354
Changes a @emph{window}'s @emph{parent} within a single
 
4355
screen. There is no way to move a window between screens.
 
4356
 
 
4357
The specified @emph{window} is reparented by inserting it as a child
 
4358
of the specified @emph{parent}. If the @emph{window} is mapped, an
 
4359
@var{unmap-window} operation is automatically performed on the
 
4360
specified @emph{window}. The @emph{window} is then removed from its
 
4361
current position in the hierarchy and inserted as the child of the
 
4362
specified @emph{parent}. The @emph{window} is placed on top in the
 
4363
stacking order with respect to sibling windows.
 
4364
 
 
4365
After reparenting the specified @emph{window,} a
 
4366
@var{:reparent-notify} event is generated. The override-redirect
 
4367
attribute of the @emph{window} is passed on in this event. Window
 
4368
manager clients normally should ignore this event if this attribute is
 
4369
@var{:on}. @xref{Events and Input}, for more information on
 
4370
@var{:reparent-notify} event processing. Finally, if the specified
 
4371
@emph{window} was originally mapped, a @var{map-window} operation is
 
4372
automatically performed on it.
 
4373
 
 
4374
The X server performs normal exposure processing on formerly obscured
 
4375
windows. It might not generate @var{:exposure} events for regions from
 
4376
the initial @var{unmap-window} operation if they are immediately
 
4377
obscured by the final @var{map-window} operation.
 
4378
 
 
4379
It is an error if any of the following are true:
 
4380
 
 
4381
@itemize @bullet
 
4382
 
 
4383
@item
 
4384
The new @emph{parent} window is not on the same screen as the old parent window.
 
4385
 
 
4386
@item
 
4387
The new @emph{parent} window is the specified @emph{window} or an
 
4388
inferior of the specified @emph{window}.
 
4389
 
 
4390
@item
 
4391
The specified @emph{window} has a @var{:parent-relative} background
 
4392
attribute and the new @emph{parent} window is not the same depth as
 
4393
the specified @emph{window}.
 
4394
@end itemize
 
4395
 
 
4396
 
 
4397
 
 
4398
@end defun
 
4399
 
 
4400
@defun translate-coordinates source source-x source-y destination
 
4401
 
 
4402
@table @var
 
4403
@item source
 
4404
A @var{window} defining the source coordinate system.
 
4405
 
 
4406
@item source-x
 
4407
@itemx source-y
 
4408
Coordinates (@var{int16}) relative to the origin of the @emph{source}
 
4409
@var{window}.
 
4410
 
 
4411
@item destination
 
4412
A @var{window} defining the destination coordinate system.
 
4413
 
 
4414
@end table
 
4415
 
 
4416
Returns the position defined by @emph{source-x} and @emph{source-y}
 
4417
(relative to the origin of the @emph{source} window), expressed as
 
4418
coordinates relative to the origin of the @emph{destination} window.
 
4419
 
 
4420
@table @var
 
4421
@item destination-x
 
4422
Type @var{int16} or @var{null}.
 
4423
@item destination-y
 
4424
Type @var{int16} or @var{null}.
 
4425
@item destination-child
 
4426
Type @var{window} or @var{null}.
 
4427
@end table
 
4428
 
 
4429
@end defun
 
4430
 
 
4431
 
 
4432
@node Mapping Windows, Destroying Windows, Window Hierarchy, Windows and Pixmaps
 
4433
@section Mapping Windows
 
4434
 
 
4435
A window is considered mapped if a @var{map-window} call has been made
 
4436
on it. When windows are first created, they are not mapped because an
 
4437
application may wish to create a window long before it is mapped to
 
4438
the screen. A mapped window may not be visible on the screen for one
 
4439
of the following reasons:
 
4440
 
 
4441
@itemize @bullet
 
4442
 
 
4443
@item  It is obscured by another opaque sibling window.
 
4444
@item  One of its ancestors is not mapped.
 
4445
@item  It is entirely clipped by an ancestor.
 
4446
 
 
4447
@end itemize
 
4448
 
 
4449
 
 
4450
A subwindow will appear on the screen as long as all of its ancestors
 
4451
are mapped and not obscured by a sibling or clipped by an
 
4452
ancestor. Mapping a window that has an unmapped ancestor does not
 
4453
display the window, but marks it as eligible for display when the
 
4454
ancestor becomes mapped. Such a window is called unviewable. When all
 
4455
its ancestors are mapped, the window becomes viewable and remains
 
4456
visible on the screen if not obscured by any sibling or ancestor.
 
4457
 
 
4458
Any output to a window not visible on the screen is
 
4459
discarded. @var{:exposure} events are generated for the window when
 
4460
part or all of it becomes visible on the screen. A client only
 
4461
receives the @var{:exposure} events if it has selected them. Mapping
 
4462
or unmapping a window does not change its stacking order priority.
 
4463
 
 
4464
@defun map-window window
 
4465
 
 
4466
@table @var
 
4467
@item window
 
4468
A @var{window}.
 
4469
@end table
 
4470
@anchor{map-window}
 
4471
 
 
4472
Maps the @emph{window}. This function has no effect when the
 
4473
@emph{window} is already mapped.
 
4474
 
 
4475
If the override-redirect attribute of the @emph{window} is @var{:off}
 
4476
and another client has selected @var{:substructure-redirect} on the
 
4477
parent window, the X server generates a @var{:map-request} event and
 
4478
the @var{map-window} function does not map the
 
4479
@emph{window}. Otherwise, the @emph{window} is mapped, and the X
 
4480
server generates a @var{:map-notify} event.
 
4481
 
 
4482
If the @emph{window} becomes visible and no earlier contents for it
 
4483
are remembered, @var{map-window} tiles the window with its
 
4484
background. If no background was defined for the window, the existing
 
4485
screen contents are not altered, and the X server generates one or
 
4486
more @var{:exposure} events. If a backing-store was maintained while
 
4487
the window was unmapped, no @var{:exposure} events are generated. If a
 
4488
backing-store will now be maintained, a full window exposure is always
 
4489
generated. Otherwise, only visible regions may be reported.  Similar
 
4490
tiling and exposure take place for any newly viewable inferiors.
 
4491
 
 
4492
@var{map-window} generates @var{:exposure} events on each
 
4493
@var{:input-output} window that it causes to become visible.
 
4494
 
 
4495
 
 
4496
 
 
4497
@end defun
 
4498
 
 
4499
@defun map-subwindows window
 
4500
 
 
4501
@table @var
 
4502
@item window
 
4503
A @var{window}.
 
4504
@end table
 
4505
 
 
4506
Maps all child windows for a specified @emph{window} in top-to-bottom
 
4507
stacking order. The X server generates an @var{:exposure} event on
 
4508
each newly visible window. This function is much more efficient than
 
4509
mapping each child individually.
 
4510
 
 
4511
 
 
4512
 
 
4513
@end defun
 
4514
 
 
4515
 
 
4516
@defun unmap-window window
 
4517
 
 
4518
@table @var
 
4519
@item window
 
4520
A @var{window}.
 
4521
@end table
 
4522
 
 
4523
Unmaps the specified @emph{window} and causes the X server to generate
 
4524
an @var{:unmap-notify} event. If the specified @emph{window} is
 
4525
already unmapped, @var{unmap-window} has no effect.  Normal exposure
 
4526
processing on formerly obscured windows is performed. Any child window
 
4527
is no longer viewable. Unmapping the @emph{window} generates
 
4528
@var{:exposure} events on windows that were formerly obscured by
 
4529
@emph{window} and its children.
 
4530
 
 
4531
 
 
4532
 
 
4533
@end defun
 
4534
 
 
4535
 
 
4536
@defun unmap-subwindows window
 
4537
 
 
4538
@table @var
 
4539
@item window
 
4540
A @var{window}.
 
4541
@end table
 
4542
 
 
4543
Unmaps all child windows for the specified @emph{window} in bottom to
 
4544
top stacking order. The X server generates an @var{:unmap-notify}
 
4545
event on each child and @var{:exposure} events on formerly obscured
 
4546
windows. Using this function is much more efficient than unmapping
 
4547
child windows individually.
 
4548
 
 
4549
 
 
4550
 
 
4551
@end defun
 
4552
 
 
4553
 
 
4554
@node Destroying Windows, Pixmaps, Mapping Windows, Windows and Pixmaps
 
4555
@section Destroying Windows
 
4556
 
 
4557
 
 
4558
CLX provides functions to destroy a window or destroy all children of
 
4559
a window. Note that by default, windows are destroyed when a
 
4560
connection is closed. For further information,
 
4561
@xref{Closing the Display}, and @xref{Client Termination}.
 
4562
 
 
4563
@defun destroy-window window
 
4564
 
 
4565
@table @var
 
4566
@item window
 
4567
A @var{window}.
 
4568
@end table
 
4569
 
 
4570
Destroys the specified @emph{window} as well as all of its
 
4571
inferiors. The windows should never again be referenced. If the
 
4572
specified @emph{window} is mapped, it is automatically unmapped.  The
 
4573
window and all of its inferiors are then destroyed, and a
 
4574
@var{:destroy-notify} event is generated for each window. The ordering
 
4575
of the @var{:destroy-notify} events is such that for any given window
 
4576
being destroyed, @var{:destroy-notify} is generated on the window's
 
4577
inferiors before being generated on the window. The ordering among
 
4578
siblings and across sub-hierarchies is not otherwise constrained. If
 
4579
the @emph{window} is a root window, no windows are
 
4580
destroyed. Destroying a mapped window generates @var{:exposure} events
 
4581
on other windows that the mapped window obscured.
 
4582
 
 
4583
 
 
4584
 
 
4585
@end defun
 
4586
 
 
4587
@defun destroy-subwindows window
 
4588
 
 
4589
@table @var
 
4590
@item window
 
4591
A @var{window}.
 
4592
@end table
 
4593
 
 
4594
Destroys all inferiors of the specified @emph{window}, in bottom to
 
4595
top stacking order. The X server generates a @var{:destroy-notify}
 
4596
event for each window. This is much more efficient than deleting many
 
4597
windows individually. The inferiors should never be referenced again.
 
4598
 
 
4599
 
 
4600
@end defun
 
4601
 
 
4602
 
 
4603
@node Pixmaps,  , Destroying Windows, Windows and Pixmaps
 
4604
@section Pixmaps
 
4605
 
 
4606
 
 
4607
A @emph{pixmap} is a three-dimensional array of bits. A pixmap is
 
4608
normally thought of as a two-dimensional array of pixels, where each
 
4609
pixel can be a value from 0 to 2@emph{n}-1, where @emph{n}
 
4610
is the depth of the pixmap. A pixmap can also be thought of as a stack
 
4611
of @emph{n} bitmaps. A @emph{bitmap} is a single bit pixmap of depth
 
4612
1. CLX provides functions to:
 
4613
 
 
4614
@itemize @bullet
 
4615
 
 
4616
@item  Create or free a pixmap
 
4617
 
 
4618
@item  Test if an object is a pixmap
 
4619
 
 
4620
@item  Test if two pixmap objects are equal
 
4621
 
 
4622
@item  Return the pixmap resource ID from a @var{pixmap} object
 
4623
@end itemize
 
4624
 
 
4625
 
 
4626
 
 
4627
Note that pixmaps can only be used on the screen where they were
 
4628
created. Pixmaps are off-screen server resources that are used for a
 
4629
number of operations. These include defining patterns for cursors or
 
4630
as the source for certain raster operations.
 
4631
 
 
4632
@defun create-pixmap &key :width :height :depth :drawable
 
4633
 
 
4634
@table @var
 
4635
@item :width
 
4636
@itemx :height
 
4637
The nonzero width and height (type @var{card16}).
 
4638
 
 
4639
@item :depth
 
4640
The depth (type @var{card8}) of the pixmap.
 
4641
 
 
4642
@item :drawable
 
4643
A @var{drawable} which determines the screen where the pixmap will be used.
 
4644
@end table
 
4645
 
 
4646
Creates a pixmap of the specified @var{:width}, @var{:height}, and
 
4647
@var{:depth}. It is valid to pass a window whose class is
 
4648
@var{:input-only} as the @var{:drawable} argument. The @var{:width}
 
4649
and @var{:height} arguments must be nonzero. The @var{:depth} must be
 
4650
supported by the screen of the specified @var{:drawable}.
 
4651
 
 
4652
@table @var
 
4653
@item pixmap
 
4654
Type @var{pixmap}.
 
4655
@end table
 
4656
 
 
4657
@end defun
 
4658
 
 
4659
 
 
4660
@defun free-pixmap pixmap
 
4661
 
 
4662
@table @var
 
4663
@item pixmap
 
4664
A @var{pixmap}.
 
4665
@end table
 
4666
 
 
4667
Allows the X server to free the pixmap storage when no other server
 
4668
resources reference it. The pixmap should never be referenced again.
 
4669
 
 
4670
 
 
4671
 
 
4672
@end defun
 
4673
 
 
4674
 
 
4675
@defun pixmap-display pixmap
 
4676
 
 
4677
@table @var
 
4678
@item pixmap
 
4679
A @var{pixmap}.
 
4680
@end table
 
4681
 
 
4682
Returns the @var{display} object associated with the specified @emph{pixmap}.
 
4683
 
 
4684
@table @var
 
4685
@item display
 
4686
Type @var{display}.
 
4687
@end table
 
4688
 
 
4689
@end defun
 
4690
 
 
4691
 
 
4692
@defun pixmap-equal pixmap-1 pixmap-2
 
4693
 
 
4694
@table @var
 
4695
@item pixmap-1
 
4696
@itemx pixmap-2
 
4697
A three-dimensional array of bits to be tested.
 
4698
@end table
 
4699
 
 
4700
Returns true if the two arguments refer to the same server resource,
 
4701
and @var{nil} if they do not.
 
4702
 
 
4703
 
 
4704
 
 
4705
@end defun
 
4706
 
 
4707
 
 
4708
@defun pixmap-id pixmap
 
4709
 
 
4710
@table @var
 
4711
@item pixmap
 
4712
A @var{pixmap}.
 
4713
@end table
 
4714
 
 
4715
Returns the unique resource ID that has been assigned to the specified
 
4716
@emph{pixmap}.
 
4717
 
 
4718
@table @var
 
4719
@item id
 
4720
Type @var{resource-id}.
 
4721
@end table
 
4722
 
 
4723
@end defun
 
4724
 
 
4725
 
 
4726
@defun pixmap-p object
 
4727
 
 
4728
@table @var
 
4729
@item pixmap
 
4730
Type @var{boolean}.
 
4731
@end table
 
4732
 
 
4733
Returns true if the argument is a @var{pixmap} object and @var{nil}
 
4734
otherwise.
 
4735
 
 
4736
@end defun
 
4737
 
 
4738
@defun pixmap-plist pixmap
 
4739
 
 
4740
@table @var
 
4741
@item pixmap
 
4742
A @var{pixmap}.
 
4743
@end table
 
4744
 
 
4745
Returns and (with @code{setf}) sets the property list for the specified
 
4746
@emph{pixmap}. This function provides a hook where extensions can add
 
4747
data.
 
4748
 
 
4749
@table @var
 
4750
@item plist
 
4751
A property list.
 
4752
@end table
 
4753
 
 
4754
@end defun
 
4755
 
 
4756
 
 
4757
@node Graphics Contexts, Graphic Operations, Windows and Pixmaps, Top
 
4758
@chapter Graphics Contexts
 
4759
 
 
4760
Clients of the X Window System specify the visual attributes of
 
4761
graphical output primitives by using @emph{graphics contexts}. A
 
4762
graphics context is a set of graphical attribute values such as
 
4763
foreground color, font, line style, and so forth. Like a window, a
 
4764
graphics context is another kind of X server resource which is created
 
4765
and maintained at the request of a client program. The client program,
 
4766
which may use several different graphics contexts at different times,
 
4767
is responsible for specifying a graphics context to use with each
 
4768
graphical output function.
 
4769
 
 
4770
CLX represents a graphics context by an object of type @var{gcontext}
 
4771
and defines functions to create, modify, and manipulate @var{gcontext}
 
4772
objects. By default, CLX also records the contents of graphics
 
4773
contexts in a cache associated with each display. This local caching
 
4774
of graphics contexts has two important advantages:
 
4775
 
 
4776
@enumerate
 
4777
 
 
4778
@item
 
4779
Communication efficiency -- Changes to attribute values in a
 
4780
@var{gcontext} are first made only in the local cache. Just before a
 
4781
@var{gcontext} is actually used, CLX automatically sends any changes
 
4782
to the X server, batching all changes into a single request.
 
4783
 
 
4784
@item
 
4785
Inquiring @var{gcontext} contents -- Accessor functions can be used
 
4786
to return the value of any individual @var{gcontext} component by
 
4787
reading the copy of the @var{gcontext} from the cache. This kind of
 
4788
inquiry is not supported by the basic X protocol. There is no way for
 
4789
a client program to request an X server to return the contents of a
 
4790
@var{gcontext}.
 
4791
@end enumerate
 
4792
 
 
4793
 
 
4794
Caching graphics contexts can result in a synchronization problem if
 
4795
more than one client program modifies a graphics context. However,
 
4796
this problem is unusual. Sharing a graphics context among several
 
4797
clients, while possible, is not expected to be useful and is not very
 
4798
easy to do. At any rate, a client program can choose to not cache a
 
4799
@var{gcontext} when it is created.
 
4800
 
 
4801
Each client program must determine its own policy for creating and
 
4802
using graphics contexts. Depending on the display hardware and the
 
4803
server implementation, creating a new graphics context can be more or
 
4804
less expensive than modifying an existing one. In general, some amount
 
4805
of graphics context information can be cached in the display hardware,
 
4806
in which case modifying the hardware cache is faster than replacing
 
4807
it. Typical display hardware can cache only a small number of graphics
 
4808
contexts. Graphics output is fastest when only a few graphics contexts
 
4809
are used without heavy modifications.
 
4810
 
 
4811
This section explains the CLX functions used to:
 
4812
 
 
4813
@itemize @bullet
 
4814
 
 
4815
@item  Create a graphics context
 
4816
 
 
4817
@item  Return the contents of a graphics context
 
4818
 
 
4819
@item  Change the contents of a graphics context
 
4820
 
 
4821
@item  Copy a graphics context
 
4822
 
 
4823
@item  Free a graphics context
 
4824
@end itemize
 
4825
 
 
4826
 
 
4827
@menu
 
4828
* Creating Graphics Contexts::
 
4829
* Graphics Context Attributes::
 
4830
* Copying Graphics Contexts::
 
4831
* Destroying Graphics Contexts::
 
4832
* Graphics Context Cache::
 
4833
@end menu
 
4834
 
 
4835
@node Creating Graphics Contexts, Graphics Context Attributes, Graphics Contexts, Graphics Contexts
 
4836
@section Creating Graphics Contexts
 
4837
 
 
4838
To create a graphics context, use @var{create-gcontext}.
 
4839
 
 
4840
@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
 
4841
 
 
4842
@table @var
 
4843
@item :cache-p
 
4844
Specifies if this graphics context should be cached locally by CLX. If
 
4845
@var{nil} then the state is not cached, otherwise a local cache is
 
4846
kept.
 
4847
@item :drawable
 
4848
The @var{drawable} whose root and depth are to be associated with
 
4849
this graphics context. This is a required keyword argument.
 
4850
@item :arc-mode
 
4851
@itemx :background
 
4852
@itemx :cap-style
 
4853
@itemx :clip-mask
 
4854
@itemx :clip-ordering
 
4855
@itemx :clip-x
 
4856
@itemx :clip-y
 
4857
@itemx :dash-offset
 
4858
@itemx :dashes
 
4859
@itemx :exposures
 
4860
@itemx :fill-rule
 
4861
@itemx :fill-style
 
4862
@itemx :font
 
4863
@itemx :foreground
 
4864
@itemx :function
 
4865
@itemx :join-style
 
4866
@itemx :line-style
 
4867
@itemx :line-width
 
4868
@itemx :plane-mask
 
4869
@itemx :stipple
 
4870
@itemx :subwindow-mode
 
4871
@itemx :tile
 
4872
@itemx :ts-x
 
4873
@itemx :ts-y
 
4874
Initial attribute values for the graphics context.
 
4875
@end table
 
4876
 
 
4877
Creates, initializes, and returns a graphics context
 
4878
(@var{gcontext}). The graphics context can only be used with
 
4879
destination drawables having the same root and depth as the specified
 
4880
@var{:drawable}. If @var{:cache-p} is non-@var{nil}, the graphics
 
4881
context state is cached locally, and changing a component has no
 
4882
effect unless the new value differs from the cached value.  Changes to
 
4883
a graphics context (@code{setf} and @var{with-gcontext}) are always
 
4884
deferred regardless of the cache mode and sent to the server only when
 
4885
required by a local operation or by an explicit call to
 
4886
@var{force-gcontext-changes}.
 
4887
 
 
4888
All of the graphics context components are set to the values that are
 
4889
specified by the keyword arguments, except that a value of @var{nil}
 
4890
causes the default value to be used. These default values are as
 
4891
follows:
 
4892
 
 
4893
@multitable {Component} {Default Value}
 
4894
@item @var{arc-mode} @tab @var{:pie-slice}
 
4895
@item @var{background} @tab 1
 
4896
@item @var{cap-style} @tab @var{:butt}
 
4897
@item @var{clip-mask} @tab @var{:none}
 
4898
@item @var{clip-ordering} @tab @var{:unsorted}
 
4899
@item @var{clip-x} @tab 0
 
4900
@item @var{clip-y} @tab 0
 
4901
@item @var{dash-offset} @tab 0
 
4902
@item @var{dashes} @tab 4 (that is, the list '(4, 4))
 
4903
@item @var{exposures} @tab @var{:on}
 
4904
@item @var{fill-rule} @tab @var{:even-odd}
 
4905
@item @var{fill-style} @tab @var{:solid}
 
4906
@item @var{font} @tab server dependent
 
4907
@item @var{foreground} @tab 0
 
4908
@item @var{function} @tab @var{boole-1}
 
4909
@item @var{join-style} @tab @var{:miter}
 
4910
@item @var{line-style} @tab @var{:solid}
 
4911
@item @var{line-width} @tab 0
 
4912
@item @var{plane-mask} @tab A bit mask of all ones
 
4913
@item @var{stipple} @tab Pixmap of unspecified size filled with ones
 
4914
@item @var{subwindow-mode} @tab @var{:clip-by-children}
 
4915
@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)
 
4916
@item @var{ts-x} @tab 0
 
4917
@item @var{ts-y} @tab 0
 
4918
@end multitable
 
4919
 
 
4920
 
 
4921
Note that foreground and background do not default to any values that
 
4922
are likely to be useful on a color display. Since specifying a
 
4923
@var{nil} value means use the default, this implies for clip-mask that
 
4924
an empty rectangle sequence cannot be specified as an empty list;
 
4925
@var{:none} must be used instead. Specifying a @var{stringable} for
 
4926
font causes an implicit @var{open-font} call to occur.
 
4927
 
 
4928
@table @var
 
4929
@item gcontext
 
4930
Type @var{gcontext}.
 
4931
@end table
 
4932
 
 
4933
@end defun
 
4934
 
 
4935
 
 
4936
@node Graphics Context Attributes, Copying Graphics Contexts, Creating Graphics Contexts, Graphics Contexts
 
4937
@section Graphics Context Attributes
 
4938
 
 
4939
The following paragraphs describe the CLX functions used to return or
 
4940
change the attributes of a @var{gcontext}. Functions that return the
 
4941
contents of a @var{gcontext} return @var{nil} if the last value stored
 
4942
is unknown (for example, if the @var{gcontext} was not cached or if
 
4943
the @var{gcontext} was not created by the inquiring client).
 
4944
 
 
4945
@defun gcontext-arc-mode gcontext
 
4946
 
 
4947
@table @var
 
4948
@item gcontext
 
4949
A @var{gcontext}.
 
4950
@end table
 
4951
 
 
4952
Returns and (with @code{setf}) changes the arc-mode attribute of the
 
4953
specified graphics context.
 
4954
 
 
4955
The arc-mode attribute of a graphics context controls the kind of
 
4956
filling, if any, to be done by the @var{draw-arcs} function. A value
 
4957
of @var{:chord} specifies that arcs are filled inward to the chord
 
4958
between the end points of the arc. @var{:pie-slice} specifies that
 
4959
arcs are filled inward to the center point of the arc, creating a pie
 
4960
slice effect.
 
4961
 
 
4962
@table @var
 
4963
@item arc-mode
 
4964
Either @var{:chord} or @var{:pie-slice}.
 
4965
@end table
 
4966
 
 
4967
@end defun
 
4968
 
 
4969
 
 
4970
@defun gcontext-background gcontext
 
4971
 
 
4972
@table @var
 
4973
@item gcontext
 
4974
A @var{gcontext}.
 
4975
@end table
 
4976
 
 
4977
Returns and (with @code{setf}) changes the background attribute of the
 
4978
specified graphics context.
 
4979
 
 
4980
The background attribute specifies the pixel value drawn for pixels
 
4981
that are not set in a bitmap and for pixels that are cleared by a
 
4982
graphics operation, such as the gaps in dashed lines.
 
4983
 
 
4984
@table @var
 
4985
@item background
 
4986
Type @var{card32}.
 
4987
@end table
 
4988
 
 
4989
@end defun
 
4990
 
 
4991
 
 
4992
@defun gcontext-cache-p gcontext
 
4993
 
 
4994
@table @var
 
4995
@item gcontext
 
4996
A @var{gcontext}.
 
4997
@end table
 
4998
 
 
4999
Returns and (with @code{setf}) changes the local cache mode for the
 
5000
@emph{gcontext}. If true, the state of the @emph{gcontext} is cached
 
5001
by CLX and changes to its attributes have no effect unless the new
 
5002
value differs from its cached value.
 
5003
 
 
5004
@table @var
 
5005
@item cache-p
 
5006
Type @var{boolean}.
 
5007
@end table
 
5008
 
 
5009
@defun gcontext-cap-style gcontext
 
5010
 
 
5011
@table @var
 
5012
@item gcontext
 
5013
A @var{gcontext}.
 
5014
@end table
 
5015
 
 
5016
Returns and (with @code{setf}) changes the cap-style attribute of the
 
5017
specified graphics context.
 
5018
 
 
5019
The cap-style attribute of a graphics context defines how the end
 
5020
points of a path are drawn. The possible values and their
 
5021
interpretations are as follows:
 
5022
@multitable {Cap-Style} {Interpretations}
 
5023
@item @var{:butt}
 
5024
@tab Square at the end point (perpendicular to the slope of the line) with no projection beyond.
 
5025
 
 
5026
@item @var{:not-last}
 
5027
@tab
 
5028
Equivalent to @var{:butt}, except that for a line-width of zero or one
 
5029
the final end point is not drawn.
 
5030
 
 
5031
@item @var{:projecting}
 
5032
@tab
 
5033
Square at the end, but the path continues beyond the end point for a
 
5034
distance equal to half the line-width. This is equivalent to
 
5035
@var{:butt} for line-width zero or one.
 
5036
 
 
5037
@item @var{:round}
 
5038
@tab
 
5039
A circular arc with the radius equal to 1/2 of the line-width,
 
5040
centered on the end point. This is equivalent to @var{:butt} for
 
5041
line-width zero or one.
 
5042
@end multitable
 
5043
 
 
5044
The following table describes what happens when the end points of a
 
5045
line are identical.  The effect depends on both the cap style and line
 
5046
width.
 
5047
 
 
5048
@multitable {Cap-Style} {Line-Width} {Effect}
 
5049
@item @var{:butt} @tab thin
 
5050
@tab
 
5051
Device dependent, but the desired effect is that a single pixel is
 
5052
drawn.
 
5053
 
 
5054
@item @var{:butt} @tab wide
 
5055
@tab
 
5056
Nothing is drawn.
 
5057
 
 
5058
@item @var{:not-last} @tab thin
 
5059
@tab
 
5060
Device dependent, but the desired effect is that nothing is drawn.
 
5061
 
 
5062
@item @var{:projecting} @tab thin
 
5063
@tab
 
5064
Same as @var{:butt} with thin line-width.
 
5065
 
 
5066
@item @var{:projecting} @tab wide
 
5067
@tab
 
5068
The closed path is a square, aligned with the coordinate axes,
 
5069
centered at the end point, with sides equal to the line-width.
 
5070
 
 
5071
@item @var{:round} @tab wide
 
5072
@tab
 
5073
The closed path is a circle, centered at the end point, with diameter equal to the line-width.
 
5074
 
 
5075
@item @var{:round} @tab thin
 
5076
@tab
 
5077
Same as @var{:butt} with thin line-width.
 
5078
 
 
5079
@end multitable
 
5080
 
 
5081
@table @var
 
5082
@item cap-style
 
5083
One of @var{:butt}, @var{:not-last}, @var{:projecting}, or @var{:round}.
 
5084
@end table
 
5085
 
 
5086
@end defun
 
5087
 
 
5088
 
 
5089
@defun gcontext-clip-mask gcontext &optional ordering
 
5090
 
 
5091
@table @var
 
5092
@item gcontext
 
5093
A @var{gcontext}.
 
5094
@item ordering
 
5095
One of @var{:unsorted}, @var{:y-sorted}, @var{:yx-banded}, @var{:yx-sorted}, or @var{nil}.
 
5096
@end table
 
5097
 
 
5098
Returns and (with @code{setf}) changes the clip-mask attribute of the
 
5099
graphics context.
 
5100
 
 
5101
When changing the clip-mask attribute, the new clip-mask can be
 
5102
specified as a pixmap or a @var{rect-seq} or as the values @var{:none}
 
5103
or @var{nil}. The ordering argument can be specified only with
 
5104
@code{setf} when the new clip-mask is a @var{rect-seq}.
 
5105
 
 
5106
The clip-mask attribute of a graphics context affects all graphics
 
5107
operations and is used to restrict output to the destination
 
5108
drawable. The clip-mask does not clip the source of a graphics
 
5109
operation. A value of @var{:none} for clip-mask indicates that no
 
5110
clipping is to be done.
 
5111
 
 
5112
If a pixmap is specified as the clip-mask, it must have depth one and
 
5113
the same root as the specified graphics context. Pixels where the
 
5114
clip-mask has a one bit are drawn. Pixels outside the area covered by
 
5115
the clip-mask or where the clip-mask has a zero bit are not drawn.
 
5116
 
 
5117
If a sequence of rectangles is specified as the clip-mask, the output
 
5118
is clipped to remain contained within the rectangles. The rectangles
 
5119
should be non-intersecting, or the results of graphics operations will
 
5120
be undefined. The rectangle coordinates are interpreted relative to
 
5121
the clip origin. Note that the sequence of rectangles can be empty,
 
5122
which effectively disables output. This is the opposite of setting the
 
5123
clip-mask to @var{:none}.
 
5124
 
 
5125
If known by the client, the ordering of clip-mask rectangles can be
 
5126
specified to provide faster operation by the server. A value of
 
5127
@var{:unsorted} means the rectangles are in arbitrary order. A value
 
5128
of @var{:y-sorted} means that the rectangles are non-decreasing in
 
5129
their Y origin. A @var{:yx-sorted} value is like @var{:y-sorted} with
 
5130
the additional constraint that all rectangles with an equal Y origin
 
5131
are non-decreasing in their X origin. A @var{:yx-banded} value
 
5132
additionally constrains @var{:yx-sorted} by requiring that, for every
 
5133
possible Y scan line, all rectangles that include that scan line have
 
5134
an identical Y origins and Y extents. If incorrect ordering is
 
5135
specified, the X server may generate an error, but it is not required
 
5136
to do so. If no error is generated, the results of the graphics
 
5137
operations are undefined.
 
5138
 
 
5139
 
 
5140
 
 
5141
@end defun
 
5142
 
 
5143
 
 
5144
@defun gcontext-clip-x gcontext
 
5145
 
 
5146
@table @var
 
5147
@item gcontext
 
5148
A @var{gcontext}.
 
5149
@end table
 
5150
 
 
5151
Returns and (with @code{setf}) changes the clip-x attribute of the
 
5152
specified graphics context.
 
5153
 
 
5154
The clip-x and clip-y attributes specify the origin for the clip-mask,
 
5155
whether it is a pixmap or a sequence of rectangles. These coordinates
 
5156
are interpreted relative to the origin of whatever destination
 
5157
drawable is specified in a graphics operation.
 
5158
 
 
5159
@table @var
 
5160
@item clip-x
 
5161
Type @var{int16}.
 
5162
@end table
 
5163
 
 
5164
@end defun
 
5165
 
 
5166
@defun gcontext-clip-y gcontext
 
5167
 
 
5168
@table @var
 
5169
@item gcontext
 
5170
A @var{gcontext}.
 
5171
@end table
 
5172
 
 
5173
Returns and (with @code{setf}) changes the clip-y attribute of the
 
5174
specified graphics context.
 
5175
 
 
5176
The clip-x and clip-y attributes specify the origin for the clip-mask,
 
5177
whether it is a pixmap or a sequence of rectangles. These coordinates
 
5178
are interpreted relative to the origin of whatever destination
 
5179
drawable is specified in a graphics operation.
 
5180
@table @var
 
5181
@item clip-y
 
5182
Type @var{int16}.
 
5183
@end table
 
5184
 
 
5185
@end defun
 
5186
 
 
5187
 
 
5188
@defun gcontext-dash-offset gcontext
 
5189
 
 
5190
@table @var
 
5191
@item gcontext
 
5192
A @var{gcontext}.
 
5193
@end table
 
5194
 
 
5195
Returns and (with @code{setf}) changes the dash-offset attribute of the
 
5196
specified graphics context.
 
5197
 
 
5198
The dash-offset attribute of a graphics context defines the phase of
 
5199
the pattern contained in the dashes attribute. This phase specifies
 
5200
how many elements (pixels) into the path the pattern should actually
 
5201
begin in any single graphics operation. Dashing is continuous through
 
5202
path elements combined with a join-style, but is reset to the
 
5203
dash-offset each time a cap-style is applied at a line end point.
 
5204
@table @var
 
5205
@item dash-offset
 
5206
Type @var{card16}.
 
5207
@end table
 
5208
 
 
5209
@end defun
 
5210
 
 
5211
 
 
5212
@defun gcontext-dashes gcontext
 
5213
 
 
5214
@table @var
 
5215
@item gcontext
 
5216
A @var{gcontext}.
 
5217
@end table
 
5218
 
 
5219
Returns and (with @code{setf}) changes the dashes attribute of the
 
5220
specified graphics context.  The sequence must be non-empty and the
 
5221
elements must be non-zero @var{card8} values.
 
5222
 
 
5223
The dashes attribute in a graphics context specifies the pattern that
 
5224
is used for graphics operations which use the dashed line styles. It
 
5225
is a non-@var{nil} sequence with each element representing the length
 
5226
of a single dash or space. The initial and alternating elements of the
 
5227
dashes are the even dashes, while the others are the odd dashes. An
 
5228
odd length sequence is equivalent to the same sequence concatenated
 
5229
with itself to produce an even length sequence. All of the elements of
 
5230
a dashes sequence must be non-zero.
 
5231
 
 
5232
Specifying a single integer value, @emph{N}, for the dashes attribute
 
5233
is an abbreviated way of specifying a two element sequence with both
 
5234
elements equal to the specified value [@emph{N}, @emph{N}].
 
5235
 
 
5236
The unit of measure for dashes is the same as in the ordinary
 
5237
coordinate system. Ideally, a dash length is measured along the slope
 
5238
of the line, but server implementations are only required to match
 
5239
this ideal for horizontal and vertical lines.
 
5240
@table @var
 
5241
@item dashes
 
5242
Type @var{sequence} or @var{card8}.
 
5243
@end table
 
5244
 
 
5245
@end defun
 
5246
 
 
5247
 
 
5248
@defun gcontext-display gcontext
 
5249
 
 
5250
@table @var
 
5251
@item gcontext
 
5252
A @var{gcontext}.
 
5253
@end table
 
5254
 
 
5255
Returns the @var{display} object associated with the specified
 
5256
@emph{gcontext}.
 
5257
@table @var
 
5258
@item display
 
5259
Type @var{display}.
 
5260
@end table
 
5261
 
 
5262
@end defun
 
5263
 
 
5264
 
 
5265
@defun gcontext-equal gcontext-1 gcontext-2
 
5266
 
 
5267
@table @var
 
5268
@item gcontext-1
 
5269
@itemx gcontext-2
 
5270
A @var{gcontext}.
 
5271
@end table
 
5272
 
 
5273
Returns true if the two arguments refer to the same server resource,
 
5274
and @var{nil} if they do not.
 
5275
@table @var
 
5276
@item equal-p
 
5277
Type @var{boolean}.
 
5278
@end table
 
5279
 
 
5280
@end defun
 
5281
 
 
5282
 
 
5283
@defun gcontext-exposures gcontext
 
5284
 
 
5285
@table @var
 
5286
@item gcontext
 
5287
A @var{gcontext}.
 
5288
@end table
 
5289
 
 
5290
Returns and (with @code{setf}) changes the exposures attribute of the
 
5291
specified graphics context.
 
5292
 
 
5293
The exposures attribute in a graphics context controls the generation
 
5294
of @var{:graphics-exposure} events for calls to the @var{copy-area}
 
5295
and @var{copy-plane} functions. If @var{:on},
 
5296
@var{:graphics-exposure} events will be reported when calling the
 
5297
@var{copy-area} and @var{copy-plane} functions with this graphics
 
5298
context. Otherwise, if @var{:off}, the events will not be reported.
 
5299
@table @var
 
5300
@item exposures
 
5301
Either @var{:off} or @var{:on}.
 
5302
@end table
 
5303
 
 
5304
@end defun
 
5305
 
 
5306
 
 
5307
@defun gcontext-fill-rule gcontext
 
5308
 
 
5309
@table @var
 
5310
@item gcontext
 
5311
A @var{gcontext}.
 
5312
@end table
 
5313
 
 
5314
Returns and (with @code{setf}) changes the fill-rule attribute of the
 
5315
specified graphics context.
 
5316
 
 
5317
The fill-rule attribute in a graphics context specifies the rule used
 
5318
to determine the interior of a filled area. It can be specified as
 
5319
either @var{:even-odd} or @var{:winding}.
 
5320
 
 
5321
The @var{:even-odd} rule defines a point to be inside if any infinite
 
5322
ray starting at the point crosses the border an odd number of
 
5323
times. Tangencies do not count as a crossing.
 
5324
 
 
5325
The @var{:winding} rule defines a point to be inside if any infinite
 
5326
ray starting at the point crosses an unequal number of clockwise and
 
5327
counterclockwise directed border segments. A clockwise directed border
 
5328
segment crosses the ray from left to right as observed from the
 
5329
point. A counterclockwise segment crosses the ray from right to left
 
5330
as observed from the point. The case where a directed line segment is
 
5331
coincident with the ray is uninteresting because you can simply choose
 
5332
a different ray that is not coincident with a segment.
 
5333
 
 
5334
For both @var{:even-odd} and @var{:winding}, a point is infinitely small, and the border is an
 
5335
infinitely thin line. A pixel is inside if the center point of the pixel is inside, and the center
 
5336
point is not on the border. If the center point is on the border, the pixel is inside if, and
 
5337
only if, the polygon interior is immediately to its right (x increasing direction). Pixels
 
5338
with centers along a horizontal edge are a special case and are inside if, and only if, the
 
5339
polygon interior is immediately below (y increasing direction).
 
5340
@table @var
 
5341
@item fill-rule
 
5342
Either @var{:even-odd} or @var{:winding}.
 
5343
@end table
 
5344
 
 
5345
@end defun
 
5346
 
 
5347
@defun gcontext-fill-style gcontext
 
5348
 
 
5349
@table @var
 
5350
@item gcontext
 
5351
A @var{gcontext}.
 
5352
@end table
 
5353
 
 
5354
Returns and (with @code{setf}) changes the fill-style attribute of the
 
5355
specified graphics context.
 
5356
 
 
5357
The fill-style attribute of a graphics context defines the contents of
 
5358
the source for line, text, and fill graphics operations. It determines
 
5359
whether the source image is drawn with a solid color, a tile, or a
 
5360
stippled tile. The possible values and their meanings are as follows:
 
5361
 
 
5362
@table @var
 
5363
@item :opaque-stippled
 
5364
Filled with a tile with the same width and height as stipple, but with
 
5365
the background value used everywhere stipple has a zero and the
 
5366
foreground pixel value used everywhere stipple has a one.
 
5367
 
 
5368
@item :solid
 
5369
Filled with the foreground pixel value.
 
5370
 
 
5371
@item :stippled
 
5372
Filled with the foreground pixel value masked by stipple.
 
5373
 
 
5374
@item :tiled
 
5375
Filled with tile.
 
5376
@end table
 
5377
 
 
5378
 
 
5379
When drawing lines with line-style @var{:double-dash}, the filling of
 
5380
the odd dashes are controlled by the fill-style in the following
 
5381
manner:
 
5382
 
 
5383
@table @var
 
5384
@item :opaque-stippled
 
5385
Same as for even dashes.
 
5386
 
 
5387
@item :solid
 
5388
Filled with the background pixel value.
 
5389
 
 
5390
@item :stippled
 
5391
Filled with the background pixel value masked by stipple.
 
5392
 
 
5393
@item :tiled
 
5394
Filled the same as the even dashes.
 
5395
@end table
 
5396
 
 
5397
@table @var
 
5398
@item fill-style
 
5399
One of @var{:opaque-stippled}, @var{:solid}, @var{:stippled}, or @var{:tiled}.
 
5400
@end table
 
5401
 
 
5402
@end defun
 
5403
 
 
5404
 
 
5405
@defun gcontext-font gcontext &optional metrics-p
 
5406
 
 
5407
@table @var
 
5408
@item gcontext
 
5409
A @var{gcontext}.
 
5410
 
 
5411
@item metrics-p
 
5412
Specifies whether a pseudo-font is returned when the real font stored
 
5413
in the graphics context is not known. The default is @var{nil}, which
 
5414
means do not return a pseudo-font.
 
5415
@end table
 
5416
 
 
5417
Returns and (with @code{setf}) changes the @emph{font} attribute of the
 
5418
specified graphics context. If the stored font is known, it is
 
5419
returned. If it is not known and the @emph{metrics-p} argument is
 
5420
@var{nil}, then @var{nil} is returned. If the font is not known and
 
5421
@emph{metrics-p} is true, then a pseudo-font is constructed and
 
5422
returned. For a constructed pseudo-font, full metric and property
 
5423
information can be obtained, but it does not have a name or a resource
 
5424
ID, and attempts to use it where a resource ID is required results in
 
5425
an invalid-font error.
 
5426
 
 
5427
The font attribute in a graphics context defines the default text font
 
5428
used in text drawing operations. When setting the value of the font
 
5429
attribute, either a @var{font} object or a font name can be used. If a
 
5430
font name is passed, @var{open-font} is call automatically to get the
 
5431
@var{font} object.
 
5432
 
 
5433
@table @var
 
5434
@item font
 
5435
Type @var{font} or @var{null}.
 
5436
@end table
 
5437
@end defun
 
5438
 
 
5439
@end defun
 
5440
 
 
5441
 
 
5442
 
 
5443
@defun gcontext-foreground gcontext
 
5444
 
 
5445
@table @var
 
5446
@item gcontext
 
5447
A @var{gcontext}.
 
5448
@end table
 
5449
 
 
5450
Returns and (with @code{setf}) changes the foreground attribute of the
 
5451
specified graphics context.
 
5452
 
 
5453
The foreground attribute of a graphics context specifies the pixel
 
5454
value drawn for set bits in a bitmap and for bits set by a graphics
 
5455
operation.
 
5456
@table @var
 
5457
@item foreground
 
5458
Type @var{card32}.
 
5459
@end table
 
5460
 
 
5461
@end defun
 
5462
 
 
5463
 
 
5464
@defun gcontext-function gcontext
 
5465
 
 
5466
@table @var
 
5467
@item gcontext
 
5468
A @var{gcontext}.
 
5469
@end table
 
5470
 
 
5471
Returns the @emph{function} of the specified graphics context.
 
5472
 
 
5473
In all graphic operations, given a source pixel and a corresponding
 
5474
destination pixel, the resulting pixel drawn is computed bitwise on
 
5475
the bits of the source and destination pixels. That is, a logical
 
5476
operation is used to combine each bit plane of corresponding source
 
5477
and destination pixels. The graphics context function attribute
 
5478
specifies the logical operation used via one of the 16 operation codes
 
5479
defined by Common Lisp for the @var{boole} function.
 
5480
 
 
5481
The following table shows each of the logical operation codes that can
 
5482
be given by the function attribute. For each operation code, its
 
5483
result is shown as a logical function of a source pixel @emph{S} and a
 
5484
destination pixel @emph{D}.
 
5485
 
 
5486
@multitable {Symbol} {Result}
 
5487
@item @var{boole-1}
 
5488
@tab @emph{S}
 
5489
@item @var{boole-2}
 
5490
@tab @emph{D}
 
5491
@item @var{boole-andc1}
 
5492
@tab (logandc1 @emph{S D})
 
5493
@item @var{boole-andc2}
 
5494
@tab (logandc2 @emph{S D})
 
5495
@item @var{boole-and}
 
5496
@tab (logand @emph{S D})
 
5497
@item @var{boole-c1}
 
5498
@tab (lognot @emph{S})
 
5499
@item @var{boole-c2}
 
5500
@tab (lognot @emph{D})
 
5501
@item @var{boole-clr}
 
5502
@tab 0
 
5503
@item @var{boole-eqv}
 
5504
@tab (logeqv @emph{S D})
 
5505
@item @var{boole-ior}
 
5506
@tab (logior @emph{S D})
 
5507
@item @var{boole-nand}
 
5508
@tab (lognand @emph{S D})
 
5509
@item @var{boole-nor}
 
5510
@tab (lognor @emph{S D})
 
5511
@item @var{boole-orc1}
 
5512
@tab (logorc1 @emph{S D})
 
5513
@item @var{boole-orc2}
 
5514
@tab (logorc2 @emph{S D})
 
5515
@item @var{boole-set}
 
5516
@tab 1
 
5517
@item @var{boole-xor}
 
5518
@tab (logxor @emph{S D})
 
5519
@end multitable
 
5520
 
 
5521
@table @var
 
5522
@item function
 
5523
Type @var{boole-constant}.
 
5524
@end table
 
5525
 
 
5526
@end defun
 
5527
 
 
5528
 
 
5529
@defun gcontext-id gcontext
 
5530
 
 
5531
@table @var
 
5532
@item gcontext
 
5533
A @var{gcontext}.
 
5534
@end table
 
5535
 
 
5536
Returns the unique ID that has been assigned to the specified graphics
 
5537
context.
 
5538
@table @var
 
5539
@item id
 
5540
Type @var{resource-id}.
 
5541
@end table
 
5542
 
 
5543
@end defun
 
5544
 
 
5545
 
 
5546
@defun gcontext-join-style gcontext
 
5547
 
 
5548
@table @var
 
5549
@item gcontext
 
5550
A @var{gcontext}.
 
5551
@end table
 
5552
 
 
5553
Returns and (with @code{setf}) changes the join-style attribute of the
 
5554
specified graphics context.
 
5555
 
 
5556
The join-style attribute of a graphics context defines how the segment
 
5557
intersections are drawn for wide polylines. The possible values and
 
5558
their interpretations are as follows:
 
5559
 
 
5560
@table @var
 
5561
@item :bevel
 
5562
Uses @var{:butt} end point styles with the triangular notch filled.
 
5563
@item :miter
 
5564
The outer edges of two lines extend to meet at an angle.
 
5565
@item :round
 
5566
A circular arc with diameter equal to the line-width, centered on the join point.
 
5567
@end table
 
5568
 
 
5569
When the end points of a polyline segment are identical, the effect is
 
5570
as if the segment was removed from the polyline. When a polyline is a
 
5571
single point, the effect is the same as when the cap-style is applied
 
5572
at both end points.
 
5573
 
 
5574
@table @var
 
5575
@item join-style
 
5576
One of @var{:bevel}, @var{:miter}, or @var{:round}.
 
5577
@end table
 
5578
 
 
5579
@end defun
 
5580
 
 
5581
 
 
5582
@defun gcontext-line-style gcontext
 
5583
 
 
5584
@table @var
 
5585
@item gcontext
 
5586
A @var{gcontext}.
 
5587
@end table
 
5588
 
 
5589
Returns and (with @code{setf}) changes the line-style attribute of the
 
5590
specified graphics context.
 
5591
 
 
5592
The line-style attribute of a graphics context specifies how (which
 
5593
sections of) lines are drawn for a path in graphics operations. The
 
5594
possible values and their meanings are as follows:
 
5595
 
 
5596
@table @var
 
5597
@item :solid
 
5598
The full path is drawn.
 
5599
 
 
5600
@item :double-dash
 
5601
The full path is drawn, but the even dashes are filled differently
 
5602
than the odd dashes. The @var{:butt} style is used where even and odd
 
5603
dashes meet (see paragraph 5.4.7, Fill-Rule and
 
5604
Fill-Style).
 
5605
 
 
5606
@item :on-off-dash
 
5607
Only the even dashes are drawn, with cap-style applied to all internal
 
5608
ends of the individual dashes, except @var{:not-last} is treated as
 
5609
@var{:butt}.
 
5610
@end table
 
5611
 
 
5612
@table @var
 
5613
@item line-style
 
5614
One of @var{:dash}, @var{:double-dash}, or @var{:solid}.
 
5615
@end table
 
5616
 
 
5617
@end defun
 
5618
 
 
5619
 
 
5620
@defun gcontext-line-width gcontext
 
5621
 
 
5622
@table @var
 
5623
@item gcontext
 
5624
A @var{gcontext}.
 
5625
@end table
 
5626
 
 
5627
Returns the @emph{line-width} of the specified graphics context.
 
5628
 
 
5629
The line-width is measured in pixels and can be greater than or equal
 
5630
to one (wide line) or can be the special value zero (thin line).
 
5631
 
 
5632
Wide lines are drawn centered on the path described by the graphics
 
5633
operation. Unless otherwise specified by the join-style or cap-style,
 
5634
the bounding box of a wide line with end points [x1, y1], [x2, y2],
 
5635
and width w is a rectangle with vertices at the following real
 
5636
coordinates:
 
5637
 
 
5638
[x1 - (w*@emph{sin}/2), y1 + (w*@emph{cos}/2)], [x1+ (w*@emph{sin}/2), y1 - (w*@emph{cos}/2)],@*
 
5639
[x2 - (w*@emph{sin}/2), y2 + (w*@emph{cos}/2)], [x2 + (w*@emph{sin}/2), y2 - (w*@emph{cos}/2)]
 
5640
 
 
5641
where @emph{sin} is the sine of the angle of the line and @emph{cos}
 
5642
is the cosine of the angle of the line. A pixel is part of the line
 
5643
and, hence, is drawn if the center of the pixel is fully inside the
 
5644
bounding box (which is viewed as having infinitely thin edges). If the
 
5645
center of the pixel is exactly on the bounding box, it is part of the
 
5646
line if, and only if, the interior is immediately to its right (x
 
5647
increasing direction). Pixels with centers on a horizontal edge are a
 
5648
special case and are part of the line if, and only if, the interior is
 
5649
immediately below (y increasing direction).
 
5650
 
 
5651
Thin lines (zero line-width) are always one pixel wide lines drawn
 
5652
using an unspecified, device dependent algorithm. There are only two
 
5653
constraints on this algorithm.
 
5654
 
 
5655
@enumerate
 
5656
@item
 
5657
If a line is drawn unclipped from [x1,y1] to [x2,y2] and if another
 
5658
line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], a point
 
5659
[x,y] is touched by drawing the first line if, and only if, the
 
5660
point [x+dx,y+dy] is touched by drawing the second line.
 
5661
 
 
5662
@item
 
5663
The effective set of points comprising a line cannot be affected by
 
5664
clipping. That is, a point is touched in a clipped line if, and only
 
5665
if, the point lies inside the clipping region and the point would be
 
5666
touched by the line when drawn unclipped.
 
5667
@end enumerate
 
5668
 
 
5669
 
 
5670
A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels
 
5671
as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style
 
5672
and join-style. Implementors are encouraged to make this property true
 
5673
for thin lines, but it is not required. A line-width of zero may
 
5674
differ from a line-width of one in which pixels are drawn. This
 
5675
permits the use of many manufacturer's line drawing hardware, which
 
5676
may run much faster than the more precisely specified wide lines.
 
5677
 
 
5678
In general, drawing a thin line is faster than drawing a wide line of
 
5679
width one. However, because of their different drawing algorithms,
 
5680
thin lines may not mix well, aesthetically speaking, with wide
 
5681
lines. If it is desirable to obtain precise and uniform results across
 
5682
all displays, a client should always use a line-width of one, rather
 
5683
than a line-width of zero.
 
5684
@table @var
 
5685
@item line-width
 
5686
Type @var{card16}.
 
5687
@end table
 
5688
 
 
5689
@end defun
 
5690
 
 
5691
 
 
5692
@defun gcontext-p gcontext
 
5693
 
 
5694
@table @var
 
5695
@item gcontext
 
5696
Type @var{boolean}.
 
5697
@end table
 
5698
 
 
5699
 
 
5700
 
 
5701
Returns non-@var{nil} if the argument is a graphics context and
 
5702
 
 
5703
@end defun
 
5704
 
 
5705
 
 
5706
 
 
5707
 
 
5708
@defun gcontext-plane-mask gcontext
 
5709
 
 
5710
@table @var
 
5711
@item gcontext
 
5712
A @var{gcontext}.
 
5713
@end table
 
5714
 
 
5715
Returns the @emph{plane-mask} of the specified graphics context.
 
5716
 
 
5717
The plane-mask attribute of a graphics context specifies which bit
 
5718
planes of the destination drawable are modified during a graphic
 
5719
operation. The plane-mask is a pixel value in which a 1 bit means that
 
5720
the corresponding bit plane will be modified and a 0 bit means that
 
5721
the corresponding bit plane will not be affected during a graphic
 
5722
operations. Thus, the actual result of a graphic operation depends on
 
5723
both the function and plane-mask attributes of the graphics context
 
5724
and is given by the following expression:
 
5725
 
 
5726
@lisp
 
5727
(logior (logand
 
5728
         (boole function source destination)
 
5729
         plane-mask)
 
5730
 
 
5731
        (logandc2
 
5732
         destination
 
5733
         plane-mask))
 
5734
@end lisp
 
5735
 
 
5736
@table @var
 
5737
@item plane-mask
 
5738
Type @var{card32}.
 
5739
@end table
 
5740
 
 
5741
@end defun
 
5742
 
 
5743
 
 
5744
@defun gcontext-plist gcontext
 
5745
 
 
5746
@table @var
 
5747
@item gcontext
 
5748
A @var{gcontext}.
 
5749
@end table
 
5750
 
 
5751
 
 
5752
 
 
5753
Returns and (with @code{setf}) sets the property list for the specified
 
5754
@emph{gcontext}. This function provides a hook where extensions can
 
5755
add data.
 
5756
 
 
5757
@table @var
 
5758
@item gcontext-p
 
5759
Type @var{list}.
 
5760
@end table
 
5761
 
 
5762
@end defun
 
5763
 
 
5764
 
 
5765
@defun gcontext-stipple gcontext
 
5766
 
 
5767
@table @var
 
5768
@item gcontext
 
5769
A @var{gcontext}.
 
5770
@end table
 
5771
 
 
5772
Returns the @emph{stipple} of the specified graphics context.
 
5773
 
 
5774
The stipple attribute of a graphics context is a bitmap used to
 
5775
prevent certain pixels in the destination of graphics operations from
 
5776
being affected by tiling.
 
5777
 
 
5778
The stipple and tile have the same origin. This origin point is
 
5779
interpreted relative to the origin of whatever destination drawable is
 
5780
specified in a graphics request. The stipple pixmap must have depth
 
5781
one and must have the same root as the graphics context. The tile
 
5782
pixmap must have the same root and depth as the graphics context. For
 
5783
stipple operations where the fill-style is @var{:stippled} (but not
 
5784
@var{:opaque-stippled}), the stipple pattern is tiled in a single
 
5785
plane and acts as an additional clip mask to be @var{and}ed with the
 
5786
clip-mask.  Any size pixmap can be used for stipple or tile, although
 
5787
some sizes may be faster to use than others.
 
5788
 
 
5789
Specifying a pixmap for stipple or tile in a graphics context might or
 
5790
might not result in a copy being made. If the pixmap is later used as
 
5791
the destination for a graphics operation, the change might or might
 
5792
not be reflected in the graphics context. If the pixmap is used both
 
5793
as the destination for a graphics operation and as a stipple or tile,
 
5794
the results are not defined.
 
5795
 
 
5796
Some displays have hardware support for tiling or stippling with
 
5797
patterns of specific sizes. Tiling and stippling operations that
 
5798
restrict themselves to those sizes may run much faster than such
 
5799
operations with arbitrary size patterns. CLX provides functions to
 
5800
determine the best size for stipple or tile (see
 
5801
@var{query-best-stipple} and @var{query-best-tile}).
 
5802
 
 
5803
@table @var
 
5804
@item stipple
 
5805
Type @var{pixmap}.
 
5806
@end table
 
5807
 
 
5808
@end defun
 
5809
 
 
5810
 
 
5811
@defun gcontext-subwindow-mode gcontext
 
5812
 
 
5813
@table @var
 
5814
@item gcontext
 
5815
A @var{gcontext}.
 
5816
@end table
 
5817
 
 
5818
Returns and (with @code{setf}) changes the subwindow-mode attribute of
 
5819
the specified graphics context.
 
5820
 
 
5821
The subwindow-mode attribute of a graphics context specifies whether
 
5822
subwindows obscure the contents of their parent window during a
 
5823
graphics operation. For a value of @var{:clip-by-children}, both
 
5824
source and destination windows are clipped by all viewable
 
5825
@var{:input-output} class children. This clipping is in addition to
 
5826
the clipping provided by the clip-mode attribute. For a value of
 
5827
@var{:include-inferiors}, neither the source nor destination window
 
5828
is clipped by its inferiors. This results in the inclusion of
 
5829
subwindow contents in the source and the drawing through of subwindow
 
5830
boundaries of the destination. The use of @var{:include-inferiors} on
 
5831
a window of one depth with mapped inferiors of differing depth is not
 
5832
illegal, but the semantics are not defined by the core protocol.
 
5833
@table @var
 
5834
@item subwindow-mode
 
5835
One of @var{:clip-by-children} or @var{:include-inferiors}.
 
5836
@end table
 
5837
 
 
5838
@end defun
 
5839
 
 
5840
 
 
5841
@defun gcontext-tile gcontext
 
5842
 
 
5843
@table @var
 
5844
@item gcontext
 
5845
A @var{gcontext}.
 
5846
@end table
 
5847
 
 
5848
Returns the @emph{tile} of the specified graphics context.
 
5849
 
 
5850
The tile attribute is a pixmap used to fill in areas for graphics
 
5851
operations. It is so named because copies of it are laid out side by
 
5852
side to fill the area.
 
5853
 
 
5854
The stipple and tile have the same origin. This origin point is
 
5855
interpreted relative to the origin of whatever destination drawable is
 
5856
specified in a graphics request. The stipple pixmap must have depth
 
5857
one and must have the same root as the graphics context. The tile
 
5858
pixmap must have the same root and depth as the graphics context. For
 
5859
stipple operations where the fill-style is @var{:stippled} (but not
 
5860
@var{:opaque-stippled}), the stipple pattern is tiled in a single
 
5861
plane and acts as an additional clip mask to be @var{and}ed with the
 
5862
clip-mask.  Any size pixmap can be used for stipple or tile, although
 
5863
some sizes may be faster to use than others.
 
5864
 
 
5865
Specifying a pixmap for stipple or tile in a graphics context might or
 
5866
might not result in a copy being made. If the pixmap is later used as
 
5867
the destination for a graphics operation, the change might or might
 
5868
not be reflected in the graphics context. If the pixmap is used both
 
5869
as the destination for a graphics operation and as a stipple or tile,
 
5870
the results are not defined.
 
5871
 
 
5872
Some displays have hardware support for tiling or stippling with
 
5873
patterns of specific sizes. Tiling and stippling operations that
 
5874
restrict themselves to those sizes may run much faster than such
 
5875
operations with arbitrary size patterns. CLX provides functions to
 
5876
determine the best size for stipple or tile (see
 
5877
@var{query-best-stipple} and @var{query-best-tile}).
 
5878
@table @var
 
5879
@item tile
 
5880
Type @var{pixmap}.
 
5881
@end table
 
5882
 
 
5883
@end defun
 
5884
 
 
5885
 
 
5886
@defun gcontext-ts-x gcontext
 
5887
 
 
5888
@table @var
 
5889
@item gcontext
 
5890
A @var{gcontext}.
 
5891
@end table
 
5892
 
 
5893
Returns the @emph{ts-x} attribute of the specified graphics context.
 
5894
 
 
5895
The ts-x and ts-y attributes of a graphics context are the coordinates
 
5896
of the origin for tile pixmaps and the stipple.
 
5897
@table @var
 
5898
@item ts-x
 
5899
Type @var{int16}.
 
5900
@end table
 
5901
 
 
5902
@end defun
 
5903
 
 
5904
 
 
5905
@defun gcontext-ts-y gcontext
 
5906
 
 
5907
@table @var
 
5908
@item gcontext
 
5909
A @var{gcontext}.
 
5910
@end table
 
5911
 
 
5912
Returns the @emph{ts-y} attribute of the specified graphics context.
 
5913
 
 
5914
The ts-x and ts-y attributes of a graphics context are the coordinates
 
5915
of the origin for tile pixmaps and the stipple.
 
5916
@table @var
 
5917
@item ts-y
 
5918
Type @var{int16}.
 
5919
@end table
 
5920
 
 
5921
@end defun
 
5922
 
 
5923
 
 
5924
@defun query-best-stipple width height drawable
 
5925
 
 
5926
@table @var
 
5927
@item width
 
5928
@itemx height
 
5929
Specifies the width and height of the desired stipple pattern.
 
5930
@item drawable
 
5931
A @var{drawable}.
 
5932
@end table
 
5933
 
 
5934
Returns the @emph{best-width} and @emph{best-height} for stipple
 
5935
pixmaps on the @emph{drawable}.
 
5936
 
 
5937
The @emph{drawable} indicates the screen and possibly the window class
 
5938
and depth. An @var{:input-only} window cannot be specified as the
 
5939
@emph{drawable}. The size is returned as width and height values.
 
5940
 
 
5941
@table @var
 
5942
@item best-width
 
5943
@itemx best-height
 
5944
Type @var{card16}.
 
5945
@end table
 
5946
 
 
5947
@end defun
 
5948
 
 
5949
 
 
5950
@defun query-best-tile width height drawable
 
5951
 
 
5952
@table @var
 
5953
@item width
 
5954
@itemx height
 
5955
Specifies the width and height of the desired tile pattern.
 
5956
@item drawable
 
5957
A @var{drawable}.
 
5958
@end table
 
5959
 
 
5960
Returns the @emph{best-width} and @emph{best-height} for tile pixmaps
 
5961
on the @emph{drawable}.
 
5962
 
 
5963
The @emph{drawable} indicates the screen and possibly the window class
 
5964
and depth. An @var{:input-only} window cannot be specified as the
 
5965
@emph{drawable}. The size is returned as width and height values.
 
5966
 
 
5967
@table @var
 
5968
@item best-width
 
5969
@itemx best-height
 
5970
Type @var{card16}.
 
5971
@end table
 
5972
 
 
5973
@end defun
 
5974
 
 
5975
 
 
5976
@node Copying Graphics Contexts, Destroying Graphics Contexts, Graphics Context Attributes, Graphics Contexts
 
5977
@section Copying Graphics Contexts
 
5978
 
 
5979
CLX provides functions to copy some or all attribute values from one
 
5980
graphics context to another. These functions are generally more
 
5981
efficient than using @code{setf} to copy @var{gcontext} attributes
 
5982
individually.
 
5983
 
 
5984
@defun copy-gcontext source destination
 
5985
 
 
5986
@table @var
 
5987
@item source
 
5988
The source @var{gcontext}.
 
5989
@item destination
 
5990
The destination @var{gcontext}.
 
5991
@end table
 
5992
 
 
5993
Copies all the values of the attributes of the source graphics context
 
5994
into the destination graphics context. The source and destination
 
5995
graphics contexts must have the same root and depth.
 
5996
 
 
5997
 
 
5998
 
 
5999
@end defun
 
6000
 
 
6001
 
 
6002
@defun copy-gcontext-components source destination &rest keys
 
6003
 
 
6004
@table @var
 
6005
@item source
 
6006
The source @var{gcontext}.
 
6007
@item destination
 
6008
The destination @var{gcontext}.
 
6009
 
 
6010
@item keys
 
6011
The remaining arguments are keywords, of type @var{gcontext-key},
 
6012
which specify which attributes of the graphics context are to be
 
6013
copied.
 
6014
@end table
 
6015
 
 
6016
Copies the values of the specified attributes of the source graphics
 
6017
context to the destination graphics context. The source and
 
6018
destination graphics contexts must have the same root and depth.
 
6019
 
 
6020
 
 
6021
@end defun
 
6022
 
 
6023
 
 
6024
@node Destroying Graphics Contexts, Graphics Context Cache, Copying Graphics Contexts, Graphics Contexts
 
6025
@section Destroying Graphics Contexts
 
6026
 
 
6027
To destroy a graphics context, use @var{free-gcontext.}
 
6028
 
 
6029
@defun free-gcontext gcontext
 
6030
 
 
6031
@table @var
 
6032
@item gcontext
 
6033
A @var{gcontext}.
 
6034
@end table
 
6035
 
 
6036
Deletes the association between the assigned resource ID and the
 
6037
specified graphics context, and then destroys the graphics context.
 
6038
 
 
6039
 
 
6040
@end defun
 
6041
 
 
6042
 
 
6043
@node Graphics Context Cache,  , Destroying Graphics Contexts, Graphics Contexts
 
6044
@section Graphics Context Cache
 
6045
 
 
6046
CLX provides a set of functions to control the automatic graphics context
 
6047
caching mechanism.
 
6048
 
 
6049
 
 
6050
@defun force-gcontext-changes gcontext
 
6051
 
 
6052
@table @var
 
6053
@item gcontext
 
6054
A @var{gcontext}.
 
6055
@end table
 
6056
 
 
6057
Forces any delayed changes to the specified graphics context to be
 
6058
sent out to the server.  Note that @var{force-gcontext-changes} is
 
6059
called by all of the graphics functions.
 
6060
 
 
6061
 
 
6062
 
 
6063
@end defun
 
6064
 
 
6065
@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
 
6066
@anchor{with-gcontext}
 
6067
 
 
6068
Changes the indicated graphics context components to the specified
 
6069
values only within the dynamic extent of the body. @var{with-gcontext}
 
6070
works on a per-process basis in a multiprocessing environment. The
 
6071
@emph{body} is not surrounded by a @var{with-display} form. If there
 
6072
is no local cache for the specified graphics context, or if some of
 
6073
the component states are unknown, @var{with-gcontext} does the save
 
6074
and restore by creating a temporary graphics context and copying
 
6075
components to and from it using @var{copy-gcontext-components}.
 
6076
 
 
6077
@table @var
 
6078
@item gcontext
 
6079
A @var{gcontext}.
 
6080
@item :arc-mode
 
6081
@itemx :background
 
6082
@itemx :cap-style
 
6083
@itemx :clip-mask
 
6084
@itemx :clip-ordering
 
6085
@itemx :clip-x
 
6086
@itemx :clip-y
 
6087
@itemx :dashes
 
6088
@itemx :dash-offset
 
6089
@itemx :exposures
 
6090
@itemx :fill-rule
 
6091
@itemx :fill-style
 
6092
@itemx :font
 
6093
@itemx :foreground
 
6094
@itemx :function
 
6095
@itemx :join-style
 
6096
@itemx :line-style
 
6097
@itemx :line-width
 
6098
@itemx :plane-mask
 
6099
@itemx :stipple
 
6100
@itemx :subwindow-mode
 
6101
@itemx :tile
 
6102
@itemx :ts-x
 
6103
@itemx :ts-y
 
6104
These keyword arguments and associated values specify which graphics
 
6105
context components are to be changed. Any components not specified are
 
6106
left unmodified. @xref{Creating Graphics Contexts}, for more information.
 
6107
@item body
 
6108
The body of code which will have access to the altered graphics context.
 
6109
@end table
 
6110
 
 
6111
@end defmac
 
6112
 
 
6113
@node Graphic Operations, Images, Graphics Contexts, Top
 
6114
@chapter Graphic Operations
 
6115
 
 
6116
Once connected to an X server, a client can use CLX functions to
 
6117
perform graphic operations on drawables.
 
6118
 
 
6119
This section describes CLX functions to:
 
6120
 
 
6121
@itemize @bullet
 
6122
 
 
6123
@item  Operate on areas and planes
 
6124
 
 
6125
@item  Draw points
 
6126
 
 
6127
@item  Draw lines
 
6128
 
 
6129
@item  Draw rectangles
 
6130
 
 
6131
@item  Draw arcs
 
6132
 
 
6133
@item  Draw text
 
6134
 
 
6135
@end itemize
 
6136
 
 
6137
 
 
6138
@menu
 
6139
* Area and Plane Operations::
 
6140
* Drawing Points::
 
6141
* Drawing Lines::
 
6142
* Drawing Rectangles::
 
6143
* Drawing Arcs::
 
6144
* Drawing Text::
 
6145
@end menu
 
6146
 
 
6147
@node Area and Plane Operations, Drawing Points, Graphic Operations, Graphic Operations
 
6148
@section Area and Plane Operations
 
6149
 
 
6150
 
 
6151
@var{clear-area} clears an area or an entire window to the background.
 
6152
Since pixmaps do not have backgrounds, they cannot be filled by using
 
6153
the functions described in the following paragraphs. Instead, you
 
6154
should use @var{draw-rectangle}, which sets the pixmap to a known
 
6155
value. @xref{Drawing Rectangles}, for information on
 
6156
@var{draw-rectangle}.
 
6157
 
 
6158
@defun clear-area window &key (:x 0) (:y 0) :width :height :exposures-p
 
6159
 
 
6160
@table @var
 
6161
@item window
 
6162
A @var{window}.
 
6163
 
 
6164
@item :x
 
6165
@itemx :y
 
6166
Upper-left corner of the area to be cleared. These coordinates are
 
6167
relative to the @emph{window} origin. Type is @var{int16}.
 
6168
 
 
6169
@item :width
 
6170
The width of the area to clear or @var{nil} to clear to the remaining
 
6171
width of the window. Type is @var{card16} or @var{null}.
 
6172
 
 
6173
@item :height
 
6174
The height of the area to clear or @var{nil} to clear to the remaining
 
6175
height of the window. Type is @var{card16} or @var{null}.
 
6176
 
 
6177
@item :exposures-p
 
6178
Specifies if @var{:exposure} events should be generated for the
 
6179
affected areas. Type @var{boolean}.
 
6180
@end table
 
6181
 
 
6182
Draws a rectangular area in the specified @emph{window} with the
 
6183
background pixel or pixmap of the @emph{window}. The @var{:x} and
 
6184
@var{:y} coordinates are relative to the @emph{window} origin, and
 
6185
specify the upper-left corner of the rectangular area that is to be
 
6186
cleared. A @var{nil} or zero value for @var{:height} or @var{:width}
 
6187
clears the remaining area (height - y or width - x). If the
 
6188
@emph{window} has a defined background tile, the rectangle is tiled by
 
6189
using a plane-mask of all ones and a function of @var{:copy}. If the
 
6190
@emph{window} has background @var{:none}, the contents of the
 
6191
@emph{window} are not changed. In either case, if @var{:exposures-p}
 
6192
is non-@var{nil}, then one or more @var{:exposure} events are
 
6193
generated for regions of the rectangle that are either visible or are
 
6194
being retained in a backing store.
 
6195
 
 
6196
To clear the entire area in a specified @emph{window}, use
 
6197
(@var{clear-area} @emph{window}).
 
6198
 
 
6199
 
 
6200
@end defun
 
6201
 
 
6202
@defun copy-area source gcontext source-x source-y width height destination destination-x destination-y
 
6203
 
 
6204
@table @var
 
6205
@item source
 
6206
Source @var{drawable}.
 
6207
 
 
6208
@item gcontext
 
6209
The graphics context to use during the copy operation.
 
6210
 
 
6211
@item source-x
 
6212
@itemx source-y
 
6213
The x and y coordinates of the upper-left corner of the area in the
 
6214
@emph{source} @var{drawable}. These coordinates are relative to the
 
6215
@emph{source} @var{drawable} origin.  Type is @var{int16}.
 
6216
 
 
6217
@item width
 
6218
@itemx height
 
6219
The width and height of the area being copied. These apply to both the
 
6220
@emph{source} and @emph{destination} areas. Type is @var{card16}.
 
6221
 
 
6222
@item destination
 
6223
The destination @var{drawable}.
 
6224
 
 
6225
@item destination-x
 
6226
@itemx destination-y
 
6227
The x and y coordinates of the upper left corner of the area in the
 
6228
@emph{destination} @var{drawable}. These coordinates are relative to
 
6229
the @emph{destination} @var{drawable} origin. Type is @var{int16}.
 
6230
@end table
 
6231
 
 
6232
Copies the specified rectangular area from the @emph{source}
 
6233
@var{drawable} to the specified rectangular area of the
 
6234
@emph{destination} @var{drawable}, combining them as specified in the
 
6235
supplied graphics context (@emph{gcontext}). The @emph{x} and @emph{y}
 
6236
coordinates are relative to their respective drawable origin, with
 
6237
each pair specifying the upper left corner of the area.
 
6238
 
 
6239
If either regions of the @emph{source} area are obscured and have not
 
6240
been retained in backing store, or regions outside the boundaries of
 
6241
the @emph{source} @var{drawable} are specified, those regions are not
 
6242
copied. Instead, the following occurs on all corresponding
 
6243
@emph{destination} regions that are either visible or are retained in
 
6244
backing store:
 
6245
 
 
6246
@itemize @bullet
 
6247
 
 
6248
@item
 
6249
If the @emph{destination} rectangle is a window with a background
 
6250
other than @var{:none}, these corresponding regions of the
 
6251
@emph{destination} are tiled, using plane-mask of all ones and
 
6252
function of @var{boole-1} (copy source), with that background.
 
6253
 
 
6254
@item
 
6255
If the exposures attribute of the graphics context is @var{:on},
 
6256
then @var{:graphics-exposure} events for all corresponding
 
6257
@emph{destination} regions are generated (regardless of tiling or
 
6258
whether the @emph{destination} is a window or a pixmap).
 
6259
 
 
6260
@item
 
6261
If exposures is @var{:on} but no regions are exposed, a
 
6262
@var{:no-exposure} event is generated.  Note that by default,
 
6263
exposures is @var{:on} for new graphics contexts. @xref{Graphics Contexts}, for further information.
 
6264
 
 
6265
@end itemize
 
6266
 
 
6267
 
 
6268
@end defun
 
6269
 
 
6270
@defun copy-plane source gcontext plane source-x source-y width height destination destination-x destination-y
 
6271
 
 
6272
@table @var
 
6273
@item source
 
6274
The source @var{drawable}.
 
6275
@item gcontext
 
6276
The graphics context to use during the copy operation.
 
6277
@item plane
 
6278
Specifies the bit-plane of the @emph{source} @var{drawable}. Exactly one bit must be set.
 
6279
Type is @var{pixel}.
 
6280
@item source-x
 
6281
@itemx source-y
 
6282
The @emph{x} and @emph{y} coordinates of the upper-left corner of the
 
6283
area in the @emph{source} @var{drawable}. These coordinates are
 
6284
relative to the @emph{source} @var{drawable} origin.  Type is
 
6285
@var{int16}.
 
6286
 
 
6287
@item width
 
6288
@itemx height
 
6289
The width and height of the area being copied. These apply to both the
 
6290
@emph{source} and @emph{destination} areas. Type is @var{card16}.
 
6291
 
 
6292
@item destination
 
6293
The destination @var{drawable}.
 
6294
 
 
6295
@item destination-x
 
6296
@itemx destination-y
 
6297
 
 
6298
The x and y coordinates of the upper-left corner of the destination
 
6299
area in the @emph{destination} @var{drawable}. These coordinates are
 
6300
relative to the @emph{destination} @var{drawable} origin. Type is
 
6301
@var{int16}.
 
6302
@end table
 
6303
 
 
6304
Uses a single bit plane of the specified rectangular area of the
 
6305
@emph{source} @var{drawable} along with the specified graphics context
 
6306
(@emph{gcontext}) to modify the specified rectangle area of the
 
6307
@emph{destination} @var{drawabl}e. The drawables specified by the
 
6308
@emph{source} and @emph{destination} arguments must have the same root
 
6309
but need not have the same depth.
 
6310
 
 
6311
Effectively, this operation forms a pixmap of the same depth as
 
6312
@emph{destination} and with a size specified by the @emph{source}
 
6313
area. It then uses the foreground and background from the graphics
 
6314
context (foreground where the bit-plane in @emph{source} contains a
 
6315
one bit, background where the bit-plane in @emph{source} contains a
 
6316
zero bit), and the equivalent of a @var{copy-area} operation is
 
6317
performed with all the same exposure semantics. This can also be
 
6318
thought of as using the specified region of the @emph{source}
 
6319
bit-plane as a stipple with a fillstyle of @var{:opaque-stippled} for
 
6320
filling a rectangular area of the @emph{destination}.
 
6321
 
 
6322
 
 
6323
 
 
6324
@end defun
 
6325
 
 
6326
@node Drawing Points, Drawing Lines, Area and Plane Operations, Graphic Operations
 
6327
@section Drawing Points
 
6328
 
 
6329
The @var{draw-point} and @var{draw-points} functions make use of the following graphics
 
6330
context components: function, plane-mask, foreground, subwindow-mode, clip-x,
 
6331
clip-y, clip-ordering, clip-region and clip-mask.
 
6332
 
 
6333
The @var{draw-point} function uses the foreground pixel and function components of the
 
6334
graphics context to draw a single point into the specified drawable, while @var{draw-points}
 
6335
draws multiple points into the specified drawable. These functions are not affected by
 
6336
the tile or stipple in the graphics context.
 
6337
 
 
6338
 
 
6339
@defun draw-point drawable gcontext x y
 
6340
 
 
6341
@table @var
 
6342
@item drawable
 
6343
The destination @var{drawable}.
 
6344
@item gcontext
 
6345
The graphics context for drawing the point.
 
6346
@item x
 
6347
@itemx y
 
6348
The @emph{x} and @emph{y} coordinates of the point drawn. Type is @var{int16}.
 
6349
@end table
 
6350
Combines the foreground pixel in the @emph{gcontext} with the pixel in
 
6351
the @emph{drawable} specified by the @emph{x} and @emph{y}
 
6352
coordinates.
 
6353
 
 
6354
 
 
6355
@end defun
 
6356
 
 
6357
@defun draw-points drawable gcontext points &optional relative-p
 
6358
 
 
6359
@table @var
 
6360
@item drawable
 
6361
The destination @var{drawable}.
 
6362
@item gcontext
 
6363
The graphics context for drawing the points.
 
6364
@item points
 
6365
A list of points to be drawn in the order listed. The first point is always relative
 
6366
to the @emph{drawable}'s origin; if @emph{relative-p}, the rest of the points are drawn relative to the
 
6367
previous point, else they are drawn relative to the @emph{drawable}'s origin. Type is
 
6368
@var{point-seq}.
 
6369
@item relative-p
 
6370
Specifies the coordinate mode used for drawing the pixels either relative to
 
6371
the origin or to the previous point. Type @var{boolean}.
 
6372
@end table
 
6373
 
 
6374
Combines the foreground pixels in the graphics context with the pixels
 
6375
at each point in the @emph{drawable}. The points are drawn in the
 
6376
order listed.
 
6377
 
 
6378
@var{draw-points} requires a mode argument, @emph{relative-p} that
 
6379
indicates whether the points are relative to the destination origin or
 
6380
to the previous point. In either case, the first point is always
 
6381
relative to the destination origin. The rest of the points are
 
6382
relative either to the @emph{drawable}'s origin or to the previous
 
6383
point, depending on the value of @emph{relative-p}.
 
6384
 
 
6385
 
 
6386
@end defun
 
6387
 
 
6388
 
 
6389
@node Drawing Lines, Drawing Rectangles, Drawing Points, Graphic Operations
 
6390
@section Drawing Lines
 
6391
 
 
6392
 
 
6393
The @var{draw-line}, @var{draw-lines}, and @var{draw-segments} functions use the following
 
6394
graphics context components: background, cap-style, clip-x-origin, clip-y-origin,
 
6395
clip-mask, dash-list, dash-offset, fill-style, foreground, function, plane-mask, line-width,
 
6396
line-style, stipple, subwindow-mode, tile, ts-x-origin, and ts-y-origin.
 
6397
 
 
6398
The @var{draw-lines} function also uses the join-style graphics context component.
 
6399
 
 
6400
@defun draw-line drawable gcontext x1 y1 x2 y2 &optional relative-p
 
6401
 
 
6402
@table @var
 
6403
@item drawable
 
6404
The destination @var{drawable}.
 
6405
@item gcontext
 
6406
The graphics context for drawing the line.
 
6407
@item x1
 
6408
@itemx y1
 
6409
@itemx x2
 
6410
@itemx y2
 
6411
The end points of the line.
 
6412
@item relative-p
 
6413
Specifies the coordinate mode used for drawing the line either relative to
 
6414
the origin or the previous point. In either case, the first point is always drawn
 
6415
relative to the @emph{drawable}'s origin.
 
6416
@end table
 
6417
 
 
6418
Draws a line from the point @emph{x1},@emph{y1} to the point
 
6419
@emph{x2},@emph{y2}. When @emph{relative-p} is true, the first point
 
6420
is relative to the destination origin but the second point is relative
 
6421
to the first point.  When @emph{relative-p} is @var{nil}, both points
 
6422
are relative to the destination origin.
 
6423
 
 
6424
 
 
6425
@end defun
 
6426
 
 
6427
 
 
6428
@defun draw-lines drawable gcontext points &key :relative-p :fill-p (:shape :complex)
 
6429
 
 
6430
@table @var
 
6431
@item drawable
 
6432
The destination @var{drawable}.
 
6433
@item gcontext
 
6434
The graphics context for drawing the lines.
 
6435
@item points
 
6436
A list of points that define the lines. Type is @var{point-seq}.
 
6437
@item :relative-p
 
6438
The coordinate mode of the points.
 
6439
@item :fill-p
 
6440
When true, a filled polygon is drawn instead of a polyline.
 
6441
@item :shape
 
6442
A hint that allows the server to use the most efficient area fill algorithm.
 
6443
Either @var{:convex}, @var{:non-convex}, or @var{:complex}.
 
6444
@end table
 
6445
 
 
6446
Draws a line between each pair of @emph{points} in the points
 
6447
list. The lines are drawn in the order listed and join correctly at
 
6448
all intermediate points. The join-style graphics context component
 
6449
defines the type of joint to use. When the first and last points
 
6450
coincide, the first and last lines also join correctly to produce a
 
6451
hollow polygon.
 
6452
 
 
6453
When @var{:relative-p} is true, the first point is always relative to
 
6454
the destination origin, but the rest are relative to the previous
 
6455
point. When @var{:relative-p} is @var{nil}, the rest of the points
 
6456
are drawn relative to the destination origin.
 
6457
 
 
6458
When @var{:fill-p} is true, the polygon defined by the @emph{points}
 
6459
list is filled. The @var{:shape} keyword provides the server with a
 
6460
hint about how to fill the polygon. @var{:shape} can be either
 
6461
@var{:complex} (by default), @var{:convex}, or @var{:non-convex}.
 
6462
 
 
6463
The @var{:convex} operand is the simplest type of area and the
 
6464
fastest to fill. A fill area is convex if every straight line
 
6465
connecting any two interior points is entirely inside the area.  For
 
6466
example, triangles and rectangles are convex polygons.
 
6467
 
 
6468
The @var{:non-convex} operand is for filling an area that is not
 
6469
convex and is also not self-intersecting. Filling this type of area is
 
6470
harder than filling a convex area, but easier than filling one that is
 
6471
self-intersecting. For example, the shape of the letter "T" is
 
6472
non-convex and non-self-intersecting.
 
6473
 
 
6474
The @var{:complex} operand is the most general (and therefore the
 
6475
hardest) type of fill area. A complex fill area can be non-convex and
 
6476
self-intersecting. For example, draw the outline of a bow tie, without
 
6477
lifting your pencil or tracing over an edge twice. This shape is
 
6478
non-convex and intersects itself at the knot in the middle.
 
6479
 
 
6480
@var{NOTE:} Unless you are sure that a shape is @var{:convex} or
 
6481
@var{:non-convex}, it should always be drawn as a @var{:complex}
 
6482
shape. If @var{:convex} or @var{:non-convex} is specified
 
6483
incorrectly, the graphics result is undefined.
 
6484
 
 
6485
 
 
6486
@end defun
 
6487
 
 
6488
 
 
6489
@defun draw-segments drawable gcontext segments
 
6490
 
 
6491
@table @var
 
6492
@item drawable
 
6493
The destination @var{drawable} to receive the line segments.
 
6494
@item gcontext
 
6495
Specifies the graphics context for drawing the lines.
 
6496
@item segments
 
6497
The points list for the segments to draw. Type is @var{seq}.
 
6498
@end table
 
6499
 
 
6500
Draws multiple lines, not necessarily connected. @emph{segments} is a
 
6501
sequence of the form @{x1 y1 x2 y2@}*, in which each subsequence
 
6502
specifies the end points of a line segment. Line segments are drawn in
 
6503
the order given by @emph{segments}. Unlike @var{draw-lines}, no
 
6504
joining is performed at coincident end points.
 
6505
 
 
6506
 
 
6507
@end defun
 
6508
 
 
6509
 
 
6510
@node Drawing Rectangles, Drawing Arcs, Drawing Lines, Graphic Operations
 
6511
@section Drawing Rectangles
 
6512
 
 
6513
 
 
6514
The @var{draw-rectangle} and @var{draw-rectangles} functions draw
 
6515
hollow or filled outlines of the specified rectangle or rectangles as
 
6516
if a five-point polyline were specified for each rectangle, as
 
6517
follows:
 
6518
 
 
6519
@display
 
6520
[x,y,] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
 
6521
@end display
 
6522
 
 
6523
@var{draw-rectangle} and @var{draw-rectangles} use the following
 
6524
graphics context components: background, function, plane-mask,
 
6525
foreground, subwindow-mode, cap-style, clip-x, clip-y, clip-ordering,
 
6526
clip-region and clip-mask, dash-list, dash-offset, fill-style,
 
6527
join-style, line-width, line-style, stipple, tile, ts-x-origin, and
 
6528
ts-y-origin.
 
6529
 
 
6530
@defun draw-rectangle drawable gcontext x y width height &optional fill-p
 
6531
 
 
6532
@table @var
 
6533
@item drawable
 
6534
The destination @var{drawable}.
 
6535
 
 
6536
@item gcontext
 
6537
The graphics context for drawing the rectangle.
 
6538
 
 
6539
@item x
 
6540
@itemx y
 
6541
The x and y coordinates that define the upper left corner of the rectangle. The
 
6542
coordinates are relative to the destination origin. Type is @var{int16}.
 
6543
 
 
6544
@item width
 
6545
@itemx height
 
6546
Specifies the width and height that define the outline of the rectangle.
 
6547
Type is @var{card16}.
 
6548
 
 
6549
@item fill-p
 
6550
Specifies whether the rectangle is filled or not. Type @var{boolean}.
 
6551
@end table
 
6552
 
 
6553
Draws a rectangle defined by the @emph{x}, @emph{y}, @emph{width}, and
 
6554
 
 
6555
@emph{height} arguments.
 
6556
 
 
6557
 
 
6558
 
 
6559
@end defun
 
6560
 
 
6561
 
 
6562
@defun draw-rectangles drawable gcontext rectangles &optional fill-p
 
6563
 
 
6564
@table @var
 
6565
@item drawable
 
6566
The destination @var{drawable}.
 
6567
 
 
6568
@item gcontext
 
6569
The graphics context.
 
6570
 
 
6571
@item rectangles
 
6572
A list specifying the upper left corner x and y, width and height of the
 
6573
rectangles. Type is @var{rect-seq}.
 
6574
 
 
6575
@item fill-p
 
6576
Specified if the rectangles are filled or not. Type is @var{boolean}.
 
6577
@end table
 
6578
 
 
6579
Draws the rectangles in the order listed in @emph{rectangles}. For the
 
6580
specified @emph{rectangle} or @emph{rectangles}, no pixel is drawn
 
6581
more than once. The x and y coordinates of each rectangle are relative
 
6582
to the destination origin and define the upper left corner of the
 
6583
rectangle. If rectangles intersect, the intersecting pixels are drawn
 
6584
multiple times.
 
6585
 
 
6586
 
 
6587
 
 
6588
@end defun
 
6589
 
 
6590
@node Drawing Arcs, Drawing Text, Drawing Rectangles, Graphic Operations
 
6591
@section Drawing Arcs
 
6592
 
 
6593
@var{draw-arc} draws a single circular or an elliptical arc, while
 
6594
@var{draw-arcs} draws multiple circular or elliptical
 
6595
arcs. @var{draw-arc} and @var{draw-arcs} use the following graphics
 
6596
context components: arc-mode, background, cap-style, clip-x, clip-y,
 
6597
clip-mask, dash-list, dash-offset, fill-style, foreground, join-style,
 
6598
function, plane-mask, line-width, line-style, stipple, subwindow-mode,
 
6599
tile, ts-x-origin, and ts-y-origin.
 
6600
 
 
6601
@defun draw-arc drawable gcontext x y width height angle1 angle2 &optional fill-p
 
6602
 
 
6603
@table @var
 
6604
@item drawable
 
6605
The destination @var{drawable}.
 
6606
 
 
6607
@item gcontext
 
6608
The graphics context for drawing the arc.
 
6609
 
 
6610
@item x
 
6611
@itemx y
 
6612
The x and y coordinates of the arc rectangle relative to the origin of the @emph{drawable}.
 
6613
Type is @var{int16}.
 
6614
 
 
6615
@item width
 
6616
@itemx height
 
6617
Specifies the width and height of the rectangle. These are the major and
 
6618
minor axes of the arc. Type is @var{card16}.
 
6619
 
 
6620
@item angle1
 
6621
Specifies the start of the arc in radians. Type is @var{angle}.
 
6622
 
 
6623
@item angle2
 
6624
Specifies the direction and end point of the arc. Type is @var{angle}.
 
6625
 
 
6626
@item fill-p
 
6627
Specifies whether the arc is filled or not. Type @var{boolean}.
 
6628
@end table
 
6629
 
 
6630
Draws either a circular or an elliptical arc. Also, outlined or filled
 
6631
arcs can be drawn.  Each arc is specified by a rectangle (@emph{x},
 
6632
@emph{y}, @emph{width}, and @emph{height}) and two angles
 
6633
(@emph{angle1} and @emph{angle2}). The angles are signed integers in
 
6634
radians, with positive indicating counterclockwise motion and negative
 
6635
indicating clockwise motion. The start of the arc is specified by
 
6636
@emph{angle1}, and the path and extent of the arc is specified by
 
6637
@emph{angle2} relative to the start of the arc. If the magnitude of
 
6638
@emph{angle2} is greater than 360 degrees, it is truncated to 360
 
6639
degrees. The @emph{x} and @emph{y} coordinates of the rectangle are
 
6640
relative to the @emph{drawable}'s origin.
 
6641
 
 
6642
For example, an arc specified as
 
6643
[@emph{x},@emph{y},@emph{width},@emph{height},@emph{angle1},@emph{angle2}]
 
6644
has the origin of the major and minor axes at:
 
6645
 
 
6646
@display
 
6647
[@emph{x}+(@emph{width}/2),@emph{y}+(@emph{height}/2)]
 
6648
@end display
 
6649
 
 
6650
The infinitely thin path describing the entire circle/ellipse
 
6651
intersects the horizontal axis at:
 
6652
 
 
6653
@display
 
6654
[@emph{x},@emph{y}+(@emph{height}/2)] and [@emph{x}+@emph{width},@emph{y}+(@emph{height}/2)]
 
6655
@end display
 
6656
 
 
6657
The intersection of the vertical axis is at:
 
6658
 
 
6659
@display
 
6660
[@emph{x}+(@emph{width}/2),@emph{y}] and [@emph{x}+(@emph{width}/2),@emph{y}+@emph{height}]
 
6661
@end display
 
6662
 
 
6663
These coordinates can be fractional; that is, they are not truncated
 
6664
to discrete coordinates. Note that the angle values are slightly
 
6665
different in CLX than in the X protocol specification.
 
6666
 
 
6667
If @emph{fill-p} is @var{nil}, then only the outline of the arc is
 
6668
drawn. Otherwise, if @emph{fill-p} is true, @var{draw-arc} fills the
 
6669
area bounded by the arc outline and one or two line segments,
 
6670
depending on the arc-mode. If the arc-mode is @var{:chord}, the
 
6671
filled area is bounded by the arc outline and the line segment joining
 
6672
the arc end points. If the arc-mode is @var{:pie-slice}, the filled
 
6673
area is bounded by the arc outline and the two line segments joining
 
6674
each arc end point with the center point.
 
6675
 
 
6676
 
 
6677
 
 
6678
@end defun
 
6679
 
 
6680
 
 
6681
@defun draw-arcs drawable gcontext arcs &optional fill-p
 
6682
 
 
6683
@table @var
 
6684
@item drawable
 
6685
Specifies the @var{drawable} where you want the arcs drawn.
 
6686
@item gcontext
 
6687
Specifies the graphics context for drawing the arc.
 
6688
@item arcs
 
6689
A sequence containing the width, height, angle1, and angle2 arguments defining
 
6690
the arcs. See @var{draw-arc} for more detail. Type is @var{arc-seq}.
 
6691
@item fill-p
 
6692
Specifies whether the arcs are filled or not. Type is @var{boolean}.
 
6693
@end table
 
6694
 
 
6695
Draws circular or elliptical, outlined or filled arcs. Each arc is
 
6696
specified by a rectangle and two angles. For a more detailed
 
6697
description, see @var{draw-arc}.
 
6698
 
 
6699
The arcs are filled in the order listed. For any given arc, no pixel is drawn more than
 
6700
once. If regions intersect, the intersecting pixels are drawn multiple times.
 
6701
 
 
6702
 
 
6703
@end defun
 
6704
 
 
6705
 
 
6706
@node Drawing Text,  , Drawing Arcs, Graphic Operations
 
6707
@section Drawing Text
 
6708
 
 
6709
CLX provides functions for drawing text using text fonts provided by
 
6710
the X server.  An X font is array of character bit maps indexed by
 
6711
integer codes. @xref{Font and Characters}, for a complete discussion
 
6712
of the CLX functions used to manage fonts and characters.
 
6713
 
 
6714
Since Common Lisp programs typically represent text as sequences of
 
6715
characters (that is, strings), CLX text functions must be prepared to
 
6716
convert a Common Lisp character into the integer code used to index the
 
6717
appropriate character bitmap in a given font. The @var{:translate}
 
6718
argument to a text function is a function which performs this
 
6719
conversion. The default @var{:translate} function handles all
 
6720
characters that satisfy @var{graphic-char-p} by converting each
 
6721
character into its ASCII code. Note that the assumption made by the
 
6722
default @var{:translate} function--that is, that an X font indexes
 
6723
bitmaps by ASCII codes--is often valid, but other encodings are
 
6724
possible. In general, a @var{:translate} function can perform complex
 
6725
transformations. It can be used to convert non-character input, to
 
6726
handle non-ASCII character encodings, and to change the fonts used to
 
6727
access character bitmaps.  The complete behavior of a @var{:translate}
 
6728
function is given below by describing a prototypical
 
6729
@var{translate-function}.
 
6730
 
 
6731
CLX offers two different ways to draw text--filled text and block
 
6732
text. The @var{draw-glyph} and @var{draw-glyphs} functions create
 
6733
filled text, in which each character image is treated as an area to be
 
6734
filled according to the fill-style of the given graphics context,
 
6735
without otherwise disturbing the surrounding background. In addition,
 
6736
filled text sends a complex type of server request which allows a series
 
6737
of font indices, font changes, and horizontal position changes to be
 
6738
compiled into a single request. Filled text functions use the following
 
6739
graphics context attributes: background, clip-mask, clip-x-origin,
 
6740
clip-y-origin, fill-style, font, foreground, function, plane-mask,
 
6741
stipple, subwindow-mode, tile, ts-x-origin, ts-y-origin.
 
6742
 
 
6743
Block text is a rendering style commonly used by display terminals, in
 
6744
which each character image appears in the foreground pixel inside a
 
6745
rectangular character cell drawn in the graphics context background
 
6746
pixel. The @var{draw-image-glyph} and @var{draw-image-glyphs}
 
6747
functions create block text. Block text functions use the following
 
6748
graphics context attributes: background, clip-mask, clip-x-origin,
 
6749
clip-y-origin, font, foreground, plane-mask, stipple, subwindow-mode,
 
6750
tile, ts-x-origin, ts-y-origin.
 
6751
 
 
6752
 
 
6753
@defun draw-glyph drawable gcontext x y element &key :translate :width (:size :default)
 
6754
 
 
6755
@table @var
 
6756
@item drawable
 
6757
The destination @var{drawable}.
 
6758
 
 
6759
@item gcontext
 
6760
The graphics context for drawing text.
 
6761
 
 
6762
@item x
 
6763
@itemx y
 
6764
The left baseline position for the character drawn.
 
6765
 
 
6766
@item element
 
6767
A character or other object to be translated into a font index.
 
6768
 
 
6769
@item :translate
 
6770
A function to translate text to font indexes. Default is @var{#'translate-default}.
 
6771
 
 
6772
@item :width
 
6773
The total pixel width of the character actually drawn, if known.
 
6774
 
 
6775
@item :size
 
6776
Specifies the element size of the destination buffer given to @var{:translate} (8, 16, or
 
6777
@var{:default}).
 
6778
@end table
 
6779
 
 
6780
Draws a single character of filled text represented by the given
 
6781
@emph{element}. The given @emph{x} and @emph{y} specify the left
 
6782
baseline position for the character. The first return value is true if
 
6783
the character is successfully translated and drawn, or @var{nil} if
 
6784
the @var{:translate} function did not translate it. The second return
 
6785
value gives the total pixel width of the character actually drawn, if
 
6786
known.
 
6787
 
 
6788
Specifying a @var{:width} is a hint to improve performance. The
 
6789
@var{:width} is assumed to be the total pixel width of the character
 
6790
actually drawn. Specifying @var{:width} permits appending the output
 
6791
of subsequent calls to the same protocol request, provided
 
6792
@emph{gcontext} has not been modified in the interim. If @var{:width}
 
6793
is not specified, appending of subsequent output might not occur
 
6794
(unless @var{:translate} returns the character width).
 
6795
 
 
6796
The @var{:size} specifies the element size of the destination buffer
 
6797
given to @var{:translate} (either 8, 16, or @var{:default}). If
 
6798
@var{:default} is specified, the size is based on the current font,
 
6799
if known; otherwise, 16 is used.
 
6800
 
 
6801
@table @var
 
6802
@item output-p
 
6803
Type @var{boolean}.
 
6804
@item width
 
6805
Type @var{int32} or @var{null}.
 
6806
@end table
 
6807
 
 
6808
@end defun
 
6809
 
 
6810
@defun draw-glyphs drawable gcontext x y sequence &key (:start 0) :end :translate :width (:size :default)
 
6811
 
 
6812
@table @var
 
6813
@item drawable
 
6814
The destination @var{drawable}.
 
6815
@item gcontext
 
6816
The graphics context for drawing text.
 
6817
@item x
 
6818
@itemx y
 
6819
The left baseline position for the character drawn.
 
6820
@item sequence
 
6821
A sequence of characters or other objects to be translated into font indexes.
 
6822
@item :start
 
6823
@itemx :end
 
6824
Start and end indexes defining the elements to draw.
 
6825
@item :translate
 
6826
A function to translate text to font indexes. Default is
 
6827
@var{#'translate-default}.
 
6828
@item :width
 
6829
The total total pixel width of the character actually drawn, if known.
 
6830
@item :size
 
6831
The element size of the destination buffer given to @var{:translate} (8, 16, or
 
6832
@var{:default}).
 
6833
@end table
 
6834
 
 
6835
 
 
6836
Draws the filled text characters represented by the given
 
6837
sequence. @var{:start} and @var{:end} define the elements of the
 
6838
sequence which are drawn. The given @emph{x} and @emph{y} specify the
 
6839
left baseline position for the first character. The first return value
 
6840
is @var{nil} if all characters are successfully translated and drawn;
 
6841
otherwise, the index of the first untranslated sequence element is
 
6842
returned. The second return value gives the total pixel width of the
 
6843
characters actually drawn, if known.
 
6844
 
 
6845
Specifying a @var{:width} is a hint to improve performance. The
 
6846
@var{:width} is assumed to be the total pixel width of the character
 
6847
sequence actually drawn. Specifying @var{:width} permits appending
 
6848
the output of subsequent calls to the same protocol request, provided
 
6849
@emph{gcontext} has not been modified in the interim. If @var{:width}
 
6850
is not specified, appending of subsequent output might not occur
 
6851
(unless @var{:translate} returns the character width).
 
6852
 
 
6853
The @var{:size} specifies the element size of the destination buffer
 
6854
given to@var{ :translate} (either 8, 16, or @var{:default}). If
 
6855
@var{:default} is specified, the size is based on the current font,
 
6856
if known; otherwise, 16 is used.
 
6857
@table @var
 
6858
@item new-start
 
6859
Type @var{array-index} or @var{null}.
 
6860
@item width
 
6861
Type @var{int32} or @var{null}.
 
6862
@end table
 
6863
 
 
6864
@end defun
 
6865
 
 
6866
 
 
6867
@defun draw-image-glyph drawable gcontext x y element &key :translate :width (:size :default)
 
6868
 
 
6869
@table @var
 
6870
@item drawable
 
6871
The destination @var{drawable}.
 
6872
@item gcontext
 
6873
The graphics context for drawing text.
 
6874
@item x
 
6875
@itemx y
 
6876
The left baseline position for the character drawn.
 
6877
@item element
 
6878
A character or other object to be translated into a font index.
 
6879
@item :translate
 
6880
A function to translate text to font indexes. Default is
 
6881
@var{#'translate-default}.
 
6882
@item :width
 
6883
The total pixel width of the character actually drawn, if known.
 
6884
@item :size
 
6885
Specifies the element size of the destination buffer given to @var{:translate} (8, 16, or
 
6886
@var{:default}).
 
6887
@end table
 
6888
 
 
6889
 
 
6890
Draws a single character of block text represented by the given
 
6891
@emph{element}. The given @emph{x} and @emph{y} specify the left
 
6892
baseline position for the character. The first return value is true if
 
6893
the character is successfully translated and drawn, or @var{nil} if
 
6894
the @var{:translate} function did not translate it. The
 
6895
@var{:translate} function is allowed to return an initial font
 
6896
change. The second return value gives the total pixel width of the
 
6897
character actually drawn, if known.
 
6898
 
 
6899
The @var{:translate} function may not return a horizontal position
 
6900
change, since @var{draw-image-glyph} does not generate complex output
 
6901
requests.
 
6902
 
 
6903
Specifying a @var{:width} is a hint to improve performance. The
 
6904
@var{:width} is assumed to be the total pixel width of the character
 
6905
actually drawn. Specifying @var{:width} permits appending the output
 
6906
of subsequent calls to the same protocol request, provided
 
6907
@emph{gcontext} has not been modified in the interim. If @var{:width}
 
6908
is not specified, appending of subsequent output might not occur
 
6909
(unless @var{:translate} returns the character width).
 
6910
 
 
6911
The @var{:size} specifies the element size of the destination buffer
 
6912
given to @var{:translate} (either 8, 16, or @var{:default}). If
 
6913
@var{:default} is specified, the size is based on the current font,
 
6914
if known; otherwise, 16 is used.
 
6915
@table @var
 
6916
@item output-p
 
6917
Type @var{boolean}.
 
6918
@item width
 
6919
Type @var{int32} or @var{null}.
 
6920
@end table
 
6921
 
 
6922
@end defun
 
6923
 
 
6924
 
 
6925
 
 
6926
@defun draw-image-glyphs drawable gcontext x y sequence &key (:start 0) :end :translate :width (:size :default)
 
6927
@anchor{draw-image-glyphs}
 
6928
 
 
6929
@table @var
 
6930
@item drawable
 
6931
The destination @var{drawable}.
 
6932
@item x
 
6933
@itemx y
 
6934
The left baseline position for the character drawn.
 
6935
@item gcontext
 
6936
The graphics context for drawing text.
 
6937
@item sequence
 
6938
A sequence of characters or other objects to be translated into font indexes.
 
6939
@item :start
 
6940
@itemx :end
 
6941
Start and end indexes defining the elements to draw.
 
6942
@item :translate
 
6943
A function to translate text to font indexes. Default is
 
6944
@var{#'translate-default}.
 
6945
@item :width
 
6946
The total total pixel width of the character actually drawn, if known.
 
6947
@item :size
 
6948
The element size of the destination buffer given to @var{:translate} (8, 16, or
 
6949
@var{:default}).
 
6950
@end table
 
6951
 
 
6952
 
 
6953
Draws the block text characters represented by the given
 
6954
@var{sequence}. @var{:start} and @var{:end} define the elements of
 
6955
the @emph{sequence} which are drawn. The given @emph{x} and @emph{y}
 
6956
specify the left baseline position for the first character. The first
 
6957
return value is @var{nil} if all characters are successfully
 
6958
translated and drawn; otherwise, the index of the first untranslated
 
6959
sequence element is returned. The @var{:translate} function is
 
6960
allowed to return an initial font change. The second return value
 
6961
gives the total pixel width of the characters actually drawn, if
 
6962
known.
 
6963
 
 
6964
The @var{:translate} function may not return a horizontal position
 
6965
change, since @var{draw-image-glyphs} does not generate complex
 
6966
output requests.
 
6967
 
 
6968
Specifying a @var{:width} is a hint to improve performance. The
 
6969
@var{:width} is assumed to be the total pixel width of the character
 
6970
sequence actually drawn. Specifying @var{:width} permits appending
 
6971
the output of subsequent calls to the same protocol request, provided
 
6972
@emph{gcontext} has not been modified in the interim. If @var{:width}
 
6973
is not specified, appending of subsequent output might not occur
 
6974
(unless @var{:translate} returns the character width).
 
6975
 
 
6976
The @var{:size} specifies the element size of the destination buffer
 
6977
given to @var{:translate} (either 8, 16, or @var{:default}). If
 
6978
@var{:default} is specified, the size will be based on the current
 
6979
font, if known; otherwise, 16 is used.
 
6980
 
 
6981
@table @var
 
6982
@item new-start
 
6983
Type @var{array-index} or @var{null}.
 
6984
@item width
 
6985
Type @var{int32} or @var{null}.
 
6986
@end table
 
6987
 
 
6988
@end defun
 
6989
 
 
6990
 
 
6991
@defun translate-function source source-start source-end font destination destination-start
 
6992
 
 
6993
@table @var
 
6994
@item source
 
6995
A sequence of characters or other objects to be translated.
 
6996
@item source-start
 
6997
An array-index specifying the first @emph{source} element to be translated.
 
6998
@item source-end
 
6999
An array-index specifying the end of the @emph{source} subsequence to be
 
7000
translated.
 
7001
@item font
 
7002
The font indexed by translated @emph{source} elements.
 
7003
@item destination
 
7004
A vector where translated @emph{source} elements are stored.
 
7005
@item destination-start
 
7006
An array-index specifying the position to begin storing
 
7007
translated @emph{source} elements.
 
7008
@end table
 
7009
 
 
7010
 
 
7011
A function used as the @var{:translate} argument for text
 
7012
functions. Converts elements of the @emph{source} (sub)sequence
 
7013
into font indexes for the given @emph{font} and stores them into
 
7014
the @emph{destination} vector.
 
7015
 
 
7016
The @emph{destination} vector is created automatically by
 
7017
CLX. @emph{destination} is guaranteed to have room for (-
 
7018
@emph{source-end source-star}t) integer elements, starting at
 
7019
@emph{destination-start}. Elements of @emph{destination} can be
 
7020
either @var{card8} or @var{card16} integers, depending on the
 
7021
context. @emph{font} is the current font, if known, or @var{nil}
 
7022
otherwise. Starting with the element at @emph{source-start},
 
7023
@var{translate-function} should translate as many elements of
 
7024
@emph{source} as possible (up to the @emph{source-end} element)
 
7025
into indexes in the current @emph{font}, and store them into
 
7026
@emph{destination}. The first return value should be the source
 
7027
index of the first untranslated element.
 
7028
 
 
7029
The second return value indicates the changes which should be made
 
7030
to the current text output request before translating the
 
7031
remaining @emph{source} elements. If no further elements need to
 
7032
be translated, the second return value should be @var{nil}. If a
 
7033
horizontal motion is required before further translation, the
 
7034
second return value should be the change in x position. If a font
 
7035
change is required for further translation, the second return
 
7036
value should be the new font.
 
7037
 
 
7038
If known, the pixel width of the translated text can be returned as the third value; this can
 
7039
allow for appending of subsequent output to the same protocol request, if no overall
 
7040
width has been specified at the higher level.
 
7041
@table @var
 
7042
@item first-not-done
 
7043
Type @var{array-index}.
 
7044
@item to-continue
 
7045
Type @var{int16}, @var{font}, or @var{null}.
 
7046
@item current-width
 
7047
Type @var{int32} or @var{null}.
 
7048
@end table
 
7049
 
 
7050
@end defun
 
7051
 
 
7052
 
 
7053
 
 
7054
@node Images, Font and Characters, Graphic Operations, Top
 
7055
@chapter Images
 
7056
 
 
7057
The X protocol provides for the transfer of images (two-dimensional
 
7058
arrays of pixel data) between a client program and a
 
7059
@var{drawable}. The format for image data can vary considerably. In
 
7060
order to present a uniform data representation for the manipulation of a
 
7061
variety of images, CLX defines a special @var{image} data
 
7062
type. Additional @var{image} subtypes -- @var{image-xy} and
 
7063
@var{image-z} -- allow for the representation of an image either as a
 
7064
sequence of bit planes or as an array of pixels. CLX includes functions
 
7065
for accessing @var{image} objects; for transferring image data between
 
7066
@var{image} objects, @var{drawables}, and files; and also for direct
 
7067
transfer of raw image data.
 
7068
 
 
7069
@menu
 
7070
* Image Types::
 
7071
* Image Functions::
 
7072
* Image Files::
 
7073
* Direct Image Transfer::
 
7074
@end menu
 
7075
 
 
7076
@node Image Types, Image Functions, Images, Images
 
7077
@section Image Types
 
7078
 
 
7079
 
 
7080
The @var{image} data type is the base type for all @var{image}
 
7081
objects. @var{image-xy} and @var{image-z} are subtypes of the
 
7082
@var{image} type which furnish accessors specialized for different
 
7083
image representations.
 
7084
 
 
7085
@menu
 
7086
* Basic Images::
 
7087
* XY-Format Images::
 
7088
* Z-Format Images::
 
7089
@end menu
 
7090
 
 
7091
@node Basic Images, XY-Format Images, Image Types, Image Types
 
7092
@subsection Basic Images
 
7093
 
 
7094
The following paragraphs describe the CLX functions that can be used to
 
7095
access all types of @var{image} objects.
 
7096
 
 
7097
@defun image-blue-mask image
 
7098
 
 
7099
@table @var
 
7100
@item image
 
7101
An @var{image} object.
 
7102
@end table
 
7103
 
 
7104
 
 
7105
Returns (and with @code{setf}) changes the @emph{mask} that
 
7106
selects the pixel subfield for blue intensity values. The
 
7107
@emph{mask} is non-@var{nil} only for images for
 
7108
@var{:direct-color} or @var{:true-color} visual types.
 
7109
 
 
7110
@table @var
 
7111
@item mask
 
7112
Type @var{pixel} or @var{null}.
 
7113
@end table
 
7114
 
 
7115
@end defun
 
7116
 
 
7117
 
 
7118
@defun image-depth image
 
7119
 
 
7120
@table @var
 
7121
@item image
 
7122
An @var{image} object.
 
7123
@end table
 
7124
 
 
7125
Returns the @emph{depth} (that is, the number of bits per pixel)
 
7126
for the @emph{image}.
 
7127
@table @var
 
7128
@item depth
 
7129
Type @var{card8}.
 
7130
@end table
 
7131
 
 
7132
@end defun
 
7133
 
 
7134
 
 
7135
@defun image-green-mask image
 
7136
 
 
7137
@table @var
 
7138
@item image
 
7139
An @var{image} object.
 
7140
@end table
 
7141
 
 
7142
Returns (and with @code{setf}) changes the mask that selects the
 
7143
pixel subfield for green intensity values. The mask is
 
7144
non-@var{nil} only for images for @var{:direct-color} or
 
7145
@var{:true-color} visual types.
 
7146
@table @var
 
7147
@item mask
 
7148
Type @var{pixel} or @var{null}.
 
7149
@end table
 
7150
 
 
7151
@end defun
 
7152
 
 
7153
 
 
7154
@defun image-height image
 
7155
 
 
7156
@table @var
 
7157
@item image
 
7158
An @var{image} object.
 
7159
@end table
 
7160
 
 
7161
Returns the @emph{height} of the @emph{image} in pixels.
 
7162
@table @var
 
7163
@item height
 
7164
Type @var{card16}.
 
7165
@end table
 
7166
 
 
7167
@end defun
 
7168
 
 
7169
@defun image-name image
 
7170
 
 
7171
@table @var
 
7172
@item image
 
7173
An @var{image} object.
 
7174
@end table
 
7175
 
 
7176
Returns and (with @code{setf}) changes the @emph{name} string
 
7177
optionally associated with the @emph{image}.
 
7178
@table @var
 
7179
@item name
 
7180
Type @var{stringable} or @var{null}.
 
7181
@end table
 
7182
 
 
7183
@end defun
 
7184
 
 
7185
 
 
7186
@defun image-plist image
 
7187
 
 
7188
@table @var
 
7189
@item image
 
7190
An @var{image} object.
 
7191
@end table
 
7192
 
 
7193
 
 
7194
Returns and (with @code{setf}) changes the @emph{image} property
 
7195
list. The property list is a hook for added application
 
7196
extensions.
 
7197
@table @var
 
7198
@item plist
 
7199
Type @var{list}.
 
7200
@end table
 
7201
 
 
7202
@end defun
 
7203
 
 
7204
 
 
7205
@defun image-red-mask image
 
7206
 
 
7207
@table @var
 
7208
@item image
 
7209
An @var{image} object.
 
7210
@end table
 
7211
 
 
7212
 
 
7213
Returns (and with @code{setf}) changes the @emph{mask} which
 
7214
selects the pixel subfield for red intensity values. The
 
7215
@emph{mask} is non-@var{nil} only for images for
 
7216
@var{:direct-color} or @var{:true-color} visual types.
 
7217
@table @var
 
7218
@item mask
 
7219
Type @var{pixel} or @var{null}.
 
7220
@end table
 
7221
 
 
7222
@end defun
 
7223
 
 
7224
 
 
7225
@defun image-width image
 
7226
 
 
7227
@table @var
 
7228
@item image
 
7229
An @var{image} object.
 
7230
@end table
 
7231
 
 
7232
 
 
7233
Returns the @emph{width} of the @emph{image} in pixels.
 
7234
@table @var
 
7235
@item width
 
7236
Type @var{card16}.
 
7237
@end table
 
7238
 
 
7239
@end defun
 
7240
 
 
7241
 
 
7242
@defun image-x-hot image
 
7243
 
 
7244
@table @var
 
7245
@item image
 
7246
An @var{image} object.
 
7247
@end table
 
7248
 
 
7249
 
 
7250
Returns and (with @code{setf}) changes the x position of the hot
 
7251
spot for an image used as a cursor glyph. The hot spot position is
 
7252
specified relative to the upper-left origin of the @emph{image}.
 
7253
@table @var
 
7254
@item x-position
 
7255
Type @var{card16} or @var{null}.
 
7256
@end table
 
7257
 
 
7258
@end defun
 
7259
 
 
7260
 
 
7261
@defun image-y-hot image
 
7262
 
 
7263
@table @var
 
7264
@item image
 
7265
An @var{image} object.
 
7266
@end table
 
7267
 
 
7268
 
 
7269
Returns and (with @code{setf}) changes the y position of the hot
 
7270
spot for an image used as a cursor glyph. The hot spot position is
 
7271
specified relative to the upper-left origin of the @emph{image}.
 
7272
@table @var
 
7273
@item y-position
 
7274
Type @var{card16} or @var{null}.
 
7275
@end table
 
7276
 
 
7277
@end defun
 
7278
 
 
7279
 
 
7280
@node XY-Format Images, Z-Format Images, Basic Images, Image Types
 
7281
@subsection XY-Format Images
 
7282
 
 
7283
 
 
7284
The @var{image-xy} subtype represents an image as a sequence of
 
7285
bitmaps, one for each plane of the image, in most-significant to
 
7286
least-significant bit order. The following paragraphs describe the
 
7287
additional CLX functions that can be used to access @var{image-xy}
 
7288
objects.
 
7289
 
 
7290
@defun image-xy-bitmap-list image
 
7291
 
 
7292
@table @var
 
7293
@item image
 
7294
An @var{image-xy} object.
 
7295
@end table
 
7296
 
 
7297
 
 
7298
Returns and (with @code{setf}) changes the list of bitmap planes
 
7299
for the @emph{image}.
 
7300
@table @var
 
7301
@item bitmaps
 
7302
Type @var{list} of @var{bitmap}.
 
7303
@end table
 
7304
 
 
7305
@end defun
 
7306
 
 
7307
 
 
7308
@node Z-Format Images,  , XY-Format Images, Image Types
 
7309
@subsection Z-Format Images
 
7310
 
 
7311
 
 
7312
The @var{image-z} subtype represents an image as a two-dimensional
 
7313
array of pixels, in scanline order. The following paragraphs describe
 
7314
the additional CLX functions that can be used to access @var{image-z}
 
7315
objects.
 
7316
 
 
7317
@defun image-z-bits-per-pixel image
 
7318
 
 
7319
@table @var
 
7320
@item image
 
7321
An @var{image-z} object.
 
7322
@end table
 
7323
 
 
7324
 
 
7325
Returns and (with @code{setf}) changes the number of bits per data
 
7326
unit used to contain a pixel value for the @emph{image}. Depending
 
7327
on the storage format for image data, this value can be larger
 
7328
than the actual @emph{image} depth.
 
7329
@table @var
 
7330
@item pixel-data-size
 
7331
One of 1, 4, 8, 16, 24, or 32.
 
7332
@end table
 
7333
 
 
7334
@end defun
 
7335
 
 
7336
 
 
7337
@defun image-z-pixarray image
 
7338
 
 
7339
@table @var
 
7340
@item image
 
7341
An @var{image-z} object.
 
7342
@end table
 
7343
 
 
7344
Returns and (with @code{setf}) changes the two-dimensional array
 
7345
of pixel data for the @emph{image}.
 
7346
@table @var
 
7347
@item pixarray
 
7348
Type @var{pixarray}.
 
7349
@end table
 
7350
 
 
7351
@end defun
 
7352
 
 
7353
 
 
7354
 
 
7355
@node Image Functions, Image Files, Image Types, Images
 
7356
@section Image Functions
 
7357
 
 
7358
The following paragraphs describe the CLX functions used to:
 
7359
 
 
7360
@itemize @bullet
 
7361
@item  Create an @var{image} object.
 
7362
 
 
7363
@item  Copy an image or a subimage.
 
7364
 
 
7365
@item  Read an image from a @var{drawable}.
 
7366
 
 
7367
@item  Display an image to a @var{drawable}.
 
7368
@end itemize
 
7369
 
 
7370
 
 
7371
@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
 
7372
 
 
7373
@table @var
 
7374
@item :bit-lsb-first-p
 
7375
For a returned image, true if the order of bits in each @var{:data}
 
7376
byte is least-significant bit first.
 
7377
@item :bits-per-pixel
 
7378
One of 1, 4, 8, 16, 24, or 32.
 
7379
@item :blue-mask
 
7380
For @var{:true-color} or @var{:direct-color} images, a pixel mask.
 
7381
@item :byte-lsb-first-p
 
7382
For a returned @emph{image}, true if the @var{:data} byte order is
 
7383
least-significant byte first.
 
7384
@item :bytes-per-line
 
7385
For a returned @emph{image}, the number of @var{:data} bytes per scanline.
 
7386
@item :data
 
7387
Either a @var{list} of @var{bitmaps}, a @var{pixarray}, or an array of @var{card8} bytes.
 
7388
@item :depth
 
7389
The number of bits per displayed pixel.
 
7390
@item :format
 
7391
One of @var{:bitmap}, @var{:xy-format}, or @var{:z-format}.
 
7392
@item :green-mask
 
7393
For @var{:true-color} or @var{:direct-color} images, a pixel mask.
 
7394
@item :height
 
7395
A @var{card16} for the image height in pixels.
 
7396
@item :name
 
7397
An optional @var{stringable} for the image name.
 
7398
@item :plist
 
7399
An optional image property list.
 
7400
@item :red-mask
 
7401
For @var{:true-color} or @var{:direct-color} images, a pixel mask.
 
7402
@item :width
 
7403
A @var{card16} for the image width in pixels.
 
7404
@item :x-hot
 
7405
For a @var{cursor} image, the x position of the hot spot.
 
7406
@item :y-hot
 
7407
For a cursor image, the y position of the hot spot.
 
7408
@end table
 
7409
 
 
7410
Creates an @var{image} object from the given @var{:data} and
 
7411
returns either an @var{image}, @var{image-xy}, or an
 
7412
@var{image-z}, depending on the type of image @var{:data}. If the
 
7413
@var{:data} is a list, it is assumed to be a @var{list} of
 
7414
@var{bitmaps} and an @var{image-xy} is created. If the
 
7415
@var{:data} is a @var{pixarray}, an @var{image-z} is
 
7416
created. Otherwise, the @var{:data} must be an array of bytes
 
7417
(@var{card8}), in which case a basic @var{image} object is
 
7418
created.
 
7419
 
 
7420
If the @var{:data} is a list, each element must be a bitmap of
 
7421
equal size. @var{:width} and @var{:height} default to the bitmap
 
7422
width -- (@var{array-dimension bitmap} 1) -- and the bitmap height
 
7423
-- (@var{array-dimension bitmap} 0) -- respectively. @var{:depth}
 
7424
defaults to the number of bitmaps.
 
7425
 
 
7426
If the @var{:data} is a @var{pixarray}, @var{:width} and
 
7427
@var{:height} default to the @var{pixarray} width --
 
7428
(@var{array-dimension pixarray} 1), and the pixarray height --
 
7429
(@var{array-dimension pixarray} 0), respectively. @var{:depth}
 
7430
defaults to (@var{pixarray-depth} @var{:data}). The
 
7431
@var{:bits-per-pixel} is rounded to a valid size, if necessary. By
 
7432
default, the @var{:bits-per-pixel} is equal to the @var{:depth}.
 
7433
 
 
7434
If the @var{:data} is an array of @var{card8}, the @var{:width}
 
7435
and @var{:height} are required to interpret the image data
 
7436
correctly. The @var{:bits-per-pixel} defaults to the @var{:depth},
 
7437
and the @var{:depth} defaults to 1. @var{:bytes-per-line} defaults
 
7438
to:
 
7439
 
 
7440
@lisp
 
7441
(@var{floor} (@var{length :data}) (* @var{:bits-per-pixel :height}))
 
7442
@end lisp
 
7443
 
 
7444
The @var{:format} defines the storage format of image data bytes
 
7445
and can be one of the following values:
 
7446
 
 
7447
@table @var
 
7448
@item :xy-pixmap
 
7449
The @var{:data} is organized as a set of bitmaps representing image
 
7450
bit planes, appearing in most-significant to least-significant bit
 
7451
order.
 
7452
 
 
7453
@item :z-pixmap
 
7454
The @var{:data} is organized as a set of pixel values in scanline
 
7455
order.
 
7456
 
 
7457
@item :bitmap
 
7458
Similar to @var{:xy-pixmap}, except that the @var{:depth} must be 1,
 
7459
and 1 and 0 bits represent the foreground and background pixels,
 
7460
respectively.
 
7461
@end table
 
7462
 
 
7463
By default, the @var{:format} is @var{:bitmap} if @var{:depth} is
 
7464
1; otherwise, @var{:z-pixmap}.
 
7465
 
 
7466
@table @var
 
7467
Type @var{image}.
 
7468
@end table
 
7469
 
 
7470
@end defun
 
7471
 
 
7472
 
 
7473
@defun copy-image image &key (:x 0) (:y 0) :width :height :result-type
 
7474
 
 
7475
@table @var
 
7476
@item image
 
7477
An @var{image} object.
 
7478
@item :x
 
7479
@itemx :y
 
7480
@var{card16} values defining the position of the upper-left corner of the subimage
 
7481
copied.
 
7482
@item :width
 
7483
@itemx :height
 
7484
@var{card16} values defining the size of subimage copied.
 
7485
@item :result-type
 
7486
One of @var{'image-x}, @var{'image-xy}, or @var{'image-z}.
 
7487
@end table
 
7488
 
 
7489
 
 
7490
Returns a new image, of the given @var{:result-type}, containing a
 
7491
copy of the portion of the @emph{image} defined by @var{:x},
 
7492
@var{:y}, @var{:width}, and @var{:height}. By default,
 
7493
@var{:width} is:
 
7494
 
 
7495
@lisp
 
7496
(- (@var{image-width} @emph{image}) @var{:x})
 
7497
@end lisp
 
7498
 
 
7499
and @var{:height} is:
 
7500
 
 
7501
@lisp
 
7502
(- (@var{image-height} @emph{image}) @var{:y})
 
7503
@end lisp
 
7504
 
 
7505
If necessary, the new image is converted to the @var{:result-type},
 
7506
that can be one of the following values:
 
7507
 
 
7508
@table @code
 
7509
@item 'image-x
 
7510
A basic @var{image} object is returned.
 
7511
@item 'image-xy
 
7512
An @var{image-xy} is returned.
 
7513
@item 'image-z
 
7514
An @var{image-z} is returned.
 
7515
@end table
 
7516
 
 
7517
@table @var
 
7518
@item new-image
 
7519
Type @var{image}.
 
7520
@end table
 
7521
 
 
7522
@end defun
 
7523
 
 
7524
 
 
7525
@defun get-image drawable &key :x :y :width :height :plane-mask (:format :z-format) :result-type Function
 
7526
 
 
7527
@table @var
 
7528
@item drawable
 
7529
A @var{drawable}.
 
7530
@item :x
 
7531
@itemx :y
 
7532
@var{card16} values defining the upper-left @var{drawable} pixel returned. These
 
7533
arguments are required.
 
7534
@item :width
 
7535
@itemx :height
 
7536
@var{card16} values defining the size of the @emph{image} returned. These
 
7537
arguments are required.
 
7538
@item :plane-mask
 
7539
A pixel mask.
 
7540
@item :format
 
7541
Either @var{:xy-pixmap} or @var{:z-pixmap}.
 
7542
@item :result-type
 
7543
One of @var{'image-x}, @var{'image-xy}, or @var{'image-z}.
 
7544
@end table
 
7545
 
 
7546
 
 
7547
Returns an @emph{image} containing pixel values from the region of
 
7548
the @emph{drawable} given by @var{:x}, @var{:y}, @var{:width},
 
7549
and @var{:height}. The bits for all planes selected by 1 bits in
 
7550
the @var{:plane-mask} are returned as zero; the default
 
7551
@var{:plane-mask} is all 1 bits. The @var{:format} of the returned
 
7552
pixel values may be either @var{:xy-format} or @var{:z-format}.
 
7553
 
 
7554
The @var{:result-type} defines the type of image object returned:
 
7555
 
 
7556
@table @code
 
7557
@item 'image-x
 
7558
A basic @var{image} object is returned.
 
7559
@item 'image-xy
 
7560
An @var{image-xy} is returned.
 
7561
@item 'image-z
 
7562
An @var{image-z} is returned.
 
7563
@end table
 
7564
 
 
7565
 
 
7566
By default, @var{:result-type} is @var{'image-z} if @var{:format}
 
7567
is @var{:z-format} and @var{'image-xy} if @var{:format} is
 
7568
@var{:xy-format}.
 
7569
@table @var
 
7570
Type @var{image}.
 
7571
@end table
 
7572
 
 
7573
@end defun
 
7574
 
 
7575
@defun put-image drawable gcontext image &key (:src-x 0) (:src-y 0) :x :y :width :height :bitmap-p
 
7576
 
 
7577
@table @var
 
7578
@item drawable
 
7579
The destination @var{drawable}.
 
7580
@item gcontext
 
7581
The graphics context used to display the @emph{image}.
 
7582
@item image
 
7583
An @var{image} object.
 
7584
@item :src-x
 
7585
@itemx :src-y
 
7586
@var{card16} values defining the upper-left position of the @emph{image} region to
 
7587
display.
 
7588
@item :x
 
7589
@itemx :y
 
7590
The position in the @emph{drawable} where the @emph{image} region is displayed. These
 
7591
arguments are required.
 
7592
@item :width :height
 
7593
@var{card16} values defining the size of the @emph{image} region displayed.
 
7594
@item :bitmap-p
 
7595
If @emph{image} is depth 1, then if true, foreground and background pixels are
 
7596
used to display 1 and 0 bits of the @emph{image}.
 
7597
@end table
 
7598
 
 
7599
Displays a region of the @emph{image} defined by @var{:src-x},
 
7600
@var{:src-y}, @var{:width}, and @var{:height} on the destination
 
7601
d@emph{rawable}, with the upper-left pixel of the @emph{image}
 
7602
region displayed at the @emph{drawable} position given by @var{:x}
 
7603
and @var{:y}. By default, @var{:width} is:
 
7604
 
 
7605
@lisp
 
7606
(- (@var{image-width} @emph{image}) @var{:src-x})
 
7607
@end lisp
 
7608
 
 
7609
and @var{:height} is:
 
7610
 
 
7611
@lisp
 
7612
(- (@var{image-height} @emph{image}) @var{:src-y})
 
7613
@end lisp
 
7614
 
 
7615
The following attributes of the @emph{gcontext} are used to display
 
7616
the @var{image}: clip-mask, clip-x, clip-y, function, plane-mask,
 
7617
and subwindow-mode.
 
7618
 
 
7619
The @var{:bitmap-p} argument applies only to images of depth 1. In
 
7620
this case, if @var{:bitmap-p} is true or if the @emph{image} is a
 
7621
basic @var{image} object created with @var{:format :bitmap}, the
 
7622
@emph{image} is combined with the foreground and background pixels
 
7623
of the @var{gcontext}. 1 bits of the @emph{image} are displayed in
 
7624
the foreground pixel and 0 bits are displayed in the background
 
7625
pixel.
 
7626
 
 
7627
 
 
7628
@end defun
 
7629
 
 
7630
 
 
7631
@node Image Files, Direct Image Transfer, Image Functions, Images
 
7632
@section Image Files
 
7633
 
 
7634
 
 
7635
CLX provides functions that allow images to be written to a file in a standard X
 
7636
format. The following paragraphs describe the CLX functions used to:
 
7637
 
 
7638
@itemize @bullet
 
7639
@item  Read an image from a file.
 
7640
 
 
7641
@item  Write an image to a file.
 
7642
@end itemize
 
7643
 
 
7644
 
 
7645
@defun read-bitmap-file pathname
 
7646
 
 
7647
@table @var
 
7648
@item pathname
 
7649
An image file pathname.
 
7650
@end table
 
7651
 
 
7652
 
 
7653
Reads an image file in standard X format and returns an
 
7654
@var{image} object. The returned @emph{image} can have
 
7655
depth greater than one.
 
7656
@table @var
 
7657
@item image
 
7658
Type @var{image}.
 
7659
@end table
 
7660
 
 
7661
@end defun
 
7662
 
 
7663
 
 
7664
@defun write-bitmap-file pathname image &optional name
 
7665
 
 
7666
@table @var
 
7667
@item pathname
 
7668
An image file pathname.
 
7669
@item image
 
7670
An @var{image} object.
 
7671
@item name
 
7672
A @var{stringable} image name.
 
7673
@end table
 
7674
 
 
7675
Writes the @emph{image} to an image file in standard X
 
7676
format. The @emph{image} can have depth greater than
 
7677
one. The @emph{name} is an image identifier written to the
 
7678
file; the default @emph{name} is (@var{or}
 
7679
(@var{image-name} @emph{image}) @var{'image}).
 
7680
 
 
7681
 
 
7682
@end defun
 
7683
 
 
7684
 
 
7685
@node Direct Image Transfer,  , Image Files, Images
 
7686
@section Direct Image Transfer
 
7687
 
 
7688
 
 
7689
For cases where the @var{image} representation is not needed,
 
7690
CLX provides functions to read and display image data
 
7691
directly.
 
7692
@defun get-raw-image drawable &key :data (:start 0) :x :y :width :height :plane-mask (:format :z-format) (:result-type '(vector card8))
 
7693
 
 
7694
@table @var
 
7695
@item drawable
 
7696
A @var{drawable}.
 
7697
@item :data
 
7698
An optional @var{sequence} of @var{card8}.
 
7699
@item :start
 
7700
The index of the first @var{:data} element modified.
 
7701
@item :x
 
7702
@itemx :y
 
7703
@var{card16} values defining the size of the @var{image} returned. These arguments are
 
7704
required.
 
7705
@item :width
 
7706
@itemx :height
 
7707
@var{card16} values defining the size of the image returned.These
 
7708
arguments are required.
 
7709
@item :plane-mask
 
7710
A pixel mask.
 
7711
@item :format
 
7712
Either @var{:xy-pixmap} or @var{:z-pixmap}. This argument is required.
 
7713
@item :result-type
 
7714
The type of image data sequence to return.
 
7715
@end table
 
7716
 
 
7717
 
 
7718
Returns a sequence of image data from the region of the
 
7719
@emph{drawable} given by @var{:x}, @var{:y},
 
7720
@var{:width}, and @var{:height}. If @var{:data} is
 
7721
given, it is modified beginning with the element at the
 
7722
@var{:start} index and returned. The @emph{depth} and
 
7723
@emph{visua}l type ID of the @emph{drawable} are also
 
7724
returned.
 
7725
 
 
7726
The bits for all planes selected by 1 bits in the
 
7727
@var{:plane-mask} are returned as zero; the default
 
7728
@var{:plane-mask} is all 1 bits. The @var{:format} of
 
7729
the returned pixel values may be either
 
7730
@var{:xy-format} or @var{:z-format}. The
 
7731
@var{:result-type} defines the type of image data
 
7732
returned.
 
7733
 
 
7734
The calling program is responsible for handling the
 
7735
byte-order and bit-order returned by the server for the
 
7736
@emph{drawable}'s display (see @var{display-byte-order}
 
7737
and @var{display-image-lsb-first-p}).
 
7738
@table @var
 
7739
@item data
 
7740
Type @var{sequence} or @var{card8}.
 
7741
@item depth
 
7742
Type @var{card8}.
 
7743
@item visual
 
7744
Type @var{card29}.
 
7745
@end table
 
7746
 
 
7747
@end defun
 
7748
 
 
7749
 
 
7750
@defun put-raw-image drawable gcontext data &key (:start 0) :depth :x :y :width :height (:left-pad 0) :format
 
7751
 
 
7752
@table @var
 
7753
@item drawable
 
7754
The destination @var{drawable}.
 
7755
@item gcontext
 
7756
The graphics context used to display the image.
 
7757
@item data
 
7758
A sequence of integers.
 
7759
@item :start
 
7760
The index of the first element of @emph{data} displayed.
 
7761
@item :depth
 
7762
The number of bits per pixel displayed. This argument is required.
 
7763
@item :x
 
7764
@itemx :y
 
7765
The position in the @emph{drawable} where the image region is displayed. These
 
7766
arguments are required.
 
7767
@item :width
 
7768
@itemx :height
 
7769
@var{card16} values defining the size of the image region displayed. These
 
7770
arguments are required.
 
7771
@item :left-pad
 
7772
A @var{card8} specifying the number of leading bits to discard for each image
 
7773
scanline.
 
7774
@item :format
 
7775
One of @var{:bitmap}, @var{:xy-pixmap}, or @var{:z-pixmap}.
 
7776
@end table
 
7777
 
 
7778
Displays a region of the image data defined by @var{:start},
 
7779
@var{:left-pad}, @var{:width}, and @var{:height} on the
 
7780
destination @emph{drawable}, with the upper-left pixel of the image
 
7781
region displayed at the @emph{drawable} position given by @var{:x}
 
7782
and @var{:y}.
 
7783
 
 
7784
The @var{:format} can be either @var{:xy-pixmap},
 
7785
@var{:z-pixmap}, or @var{:bitmap}. If @var{:xy-pixmap} or
 
7786
@var{:z-pixmap} formats are used, @var{:depth} must match the
 
7787
depth of the destination @emph{drawable}. For @var{:xy-pixmap}, the
 
7788
data must be in XY format. For @var{:z-pixmap}, the data must be in
 
7789
Z format for the given @var{:depth}.
 
7790
 
 
7791
If the @var{:format} is @var{:bitmap}, the @var{:depth} must be
 
7792
1. In this case, the image is combined with the foreground and
 
7793
background pixels of the @emph{gcontext}. 1 bits of the image are
 
7794
displayed in the foreground pixel and 0 bits are displayed in the
 
7795
background pixel.
 
7796
 
 
7797
The @var{:left-pad} must be zero for @var{:z-pixmap} format. For
 
7798
@var{:bitmap} and @var{:xy-pixmap} formats, the @var{:left-pad}
 
7799
must be less than the bitmap-scanline-pad for the @emph{drawable}'s
 
7800
display (@pxref{display-bitmap-format}). The first
 
7801
@var{:left-pad} bits in every scanline are to be ignored by the
 
7802
server; the actual image begins that many bits into the data.
 
7803
 
 
7804
The following attributes of the @emph{gcontext} are used to display
 
7805
the @var{image}: clip-mask, clip-x, clip-y, function, plane-mask,
 
7806
and subwindow-mode.
 
7807
 
 
7808
The calling program is responsible for handling the byte-order and
 
7809
bit-order required by the server for the @emph{drawable}'s display
 
7810
(see @var{display-byte-order} and
 
7811
@var{display-image-lsb-first-p}).
 
7812
 
 
7813
 
 
7814
@end defun
 
7815
 
 
7816
 
 
7817
@node Font and Characters, Colors, Images, Top
 
7818
@chapter Font and Characters
 
7819
 
 
7820
An X server maintains a set of fonts used in the text operations
 
7821
requested by client programs. An X font is an array of character bit
 
7822
maps (or @emph{glyphs}) indexed by integer codes. In fact, font glyphs
 
7823
can also represent cursor shapes or other images and are not limited to
 
7824
character images. X supports both linear and matrix encoding of font
 
7825
indexes.  With linear encoding, a font index is interpreted as a single
 
7826
16-bit integer index into a one-dimensional array of glyphs. With matrix
 
7827
encoding, a font index is interpreted as a pair of 8-bit integer indexes
 
7828
into a two-dimensional array of glyphs. The type of index encoding used
 
7829
is font-dependent.
 
7830
 
 
7831
In order to access or use a font, a client program must first open it
 
7832
using the @var{open-font} function, sending a font name string as an
 
7833
identifier. @var{open-font} creates a CLX @var{font} object used to
 
7834
refer to the font in subsequent functions. Afterward, calling
 
7835
@var{open-font} with the same font name returns the same @var{font}
 
7836
object. When a font is no longer in use, a client program can call
 
7837
@var{close-font} to destroy the @var{font} object.
 
7838
 
 
7839
A font has several attributes which describe its geometry and its
 
7840
glyphs. CLX provides functions to return the attributes of a font, as
 
7841
well functions for accessing the attributes of individual font
 
7842
glyphs. Glyph attributes are referred to as @emph{character attributes},
 
7843
since characters are the most common type of font glyphs. A font also
 
7844
has a property list of values recorded by the X server. However, the set
 
7845
of possible font properties and their values are not standardized and
 
7846
are implementation-dependent. Typically, CLX maintains a cache of font
 
7847
and character attributes, in order to minimize server requests.
 
7848
However, the font cache mechanism is implementation-dependent and cannot
 
7849
be controlled by the client. In some cases, CLX may create a
 
7850
@emph{pseudo-font} object solely for the purpose of accessing font
 
7851
attributes. A pseudo-font is represented by a special type of
 
7852
@var{font} object that cannot be used in a @var{gcontext}. If
 
7853
necessary, CLX can automatically convert a pseudo-font into a true font,
 
7854
if the name of the pseudo-font is known.
 
7855
 
 
7856
The set of available fonts is server-dependent; that is, font names are
 
7857
not guaranteed to be portable from one server to the next. However, the
 
7858
public X implementation from MIT includes a set of fonts that are
 
7859
typically available with most X servers.
 
7860
 
 
7861
The following paragraphs describe CLX functions to:
 
7862
 
 
7863
@itemize @bullet
 
7864
@item  Open and close fonts.
 
7865
@item  List available fonts.
 
7866
@item  Access font attributes.
 
7867
@item  Access character attributes.
 
7868
@item  Return the size of a text string.
 
7869
@end itemize
 
7870
 
 
7871
@menu
 
7872
* Opening Fonts::
 
7873
* Listing Fonts::
 
7874
* Font Attributes::
 
7875
* Chracter Attributes::
 
7876
* Querying Text Size::
 
7877
@end menu
 
7878
 
 
7879
@node Opening Fonts, Listing Fonts, Font and Characters, Font and Characters
 
7880
@section Opening Fonts
 
7881
 
 
7882
 
 
7883
The following paragraphs discuss the CLX functions for opening and
 
7884
closing fonts.
 
7885
 
 
7886
@defun open-font display name
 
7887
 
 
7888
@table @var
 
7889
@item display
 
7890
A @var{display} object.
 
7891
@item name
 
7892
A font name string.
 
7893
@end table
 
7894
 
 
7895
Opens the font with the given @emph{name} and returns a
 
7896
@var{font} object. The name string should contain only ISO
 
7897
Latin-1 characters; case is not significant.
 
7898
 
 
7899
@table @var
 
7900
@item font
 
7901
Type @var{font}.
 
7902
@end table
 
7903
 
 
7904
@end defun
 
7905
 
 
7906
 
 
7907
@defun close-font font
 
7908
 
 
7909
@table @var
 
7910
@item font
 
7911
A @var{font} object.
 
7912
@end table
 
7913
 
 
7914
Deletes the association between the resource ID and the
 
7915
@emph{font}. The @emph{font} is freed when no other server
 
7916
resource references it. The @emph{font} can be unloaded by the X
 
7917
server if this is the last reference to the @emph{font} by any
 
7918
client. In any case, the @emph{font} should never again be
 
7919
referenced because its resource ID is destroyed. This might not
 
7920
generate a protocol request if the @emph{font} is
 
7921
reference-counted locally or if it is a pseudo-font.
 
7922
 
 
7923
@end defun
 
7924
 
 
7925
 
 
7926
@defun discard-font-info fonts
 
7927
 
 
7928
@table @var
 
7929
@item font
 
7930
A @var{font} object.
 
7931
@end table
 
7932
 
 
7933
Discards any state that can be re-obtained with
 
7934
@var{open-font}. This is simply a performance hint for
 
7935
memory-limited systems.
 
7936
 
 
7937
@end defun
 
7938
 
 
7939
@node Listing Fonts, Font Attributes, Opening Fonts, Font and Characters
 
7940
@section Listing Fonts
 
7941
 
 
7942
 
 
7943
The following paragraphs describe CLX functions that return fonts or
 
7944
font names that match a given pattern string. Such pattern strings
 
7945
should contain only ISO Latin-1 characters; case is not significant. The
 
7946
following pattern characters can be used for @emph{wildcard} matching:
 
7947
 
 
7948
@table @code
 
7949
@item #\*
 
7950
Matches any sequence of zero or more characters.
 
7951
@item #\?
 
7952
Matches any single character.
 
7953
@end table
 
7954
 
 
7955
For example, the pattern "T?mes Roman" matches the name "Times Roman"
 
7956
but not the name "Thames Roman". However, the pattern "T*mes Roman"
 
7957
matches both names.
 
7958
 
 
7959
@defun font-path display &key (:result-type 'list)
 
7960
 
 
7961
@table @var
 
7962
@item display
 
7963
A @var{display} object.
 
7964
@item :result-type
 
7965
Specifies the type of resulting sequence.
 
7966
@end table
 
7967
 
 
7968
Returns a @var{list} (by default) of names containing the current
 
7969
search path for fonts. With @code{setf}, this function sets the
 
7970
search path for font lookup. There is only one search path per
 
7971
server, not one per client. The interpretation of the names is
 
7972
server-dependent, but they are intended to specify directories to be
 
7973
searched in the order listed.
 
7974
 
 
7975
Setting the path to the empty list restores the default path
 
7976
defined for the server. Note that as a side-effect of
 
7977
executing this request, the server is guaranteed to flush
 
7978
all cached information about fonts for which there are
 
7979
currently no explicit resource IDs allocated.
 
7980
@table @var
 
7981
@item paths
 
7982
Type @var{sequence} of either @var{string} or @var{pathname}.
 
7983
@end table
 
7984
 
 
7985
@end defun
 
7986
 
 
7987
 
 
7988
@defun list-font-names display pattern &key (:max-fonts 65535) (:result-type 'list)
 
7989
 
 
7990
@table @var
 
7991
@item display
 
7992
A @var{display} object.
 
7993
@item pattern
 
7994
A string used to match font names. Only font names that match the pattern are
 
7995
returned.
 
7996
@item :max-fonts
 
7997
The maximum number of font names returned. Default is 65535.
 
7998
@item :result-type
 
7999
The type of sequence to return. Default is '@var{list}.
 
8000
@end table
 
8001
 
 
8002
Returns a sequence of strings containing the font names that match
 
8003
the @emph{pattern}. The fonts available are determined by the font
 
8004
search path; see @var{font-path}). The maximum number of font names
 
8005
returned is determined by @var{:max-fonts}.
 
8006
 
 
8007
@table @var
 
8008
@item font-name
 
8009
Type @var{sequence} of @var{string}.
 
8010
@end table
 
8011
 
 
8012
@end defun
 
8013
 
 
8014
 
 
8015
@defun list-fonts display pattern &key (:max-fonts 65535) (:result-type 'list)
 
8016
 
 
8017
@table @var
 
8018
@item display
 
8019
A @var{display} object.
 
8020
@item pattern
 
8021
A string used to match font names. Only fonts whose name matches the
 
8022
pattern are returned.
 
8023
@item :max-fonts
 
8024
The maximum number of fonts returned. Default is 65535.
 
8025
@item :result-type
 
8026
The type of sequence to return. Default is @var{'list}.
 
8027
@end table
 
8028
 
 
8029
Returns a sequence of pseudo-fonts corresponding to the available
 
8030
fonts whose names match the @emph{pattern}. The fonts available are
 
8031
determined by the font search path; see @var{font-path}). The
 
8032
maximum number of @var{font} objects returned is determined by
 
8033
@var{:max-fonts}.
 
8034
 
 
8035
@table @var
 
8036
@item font
 
8037
Type @var{sequence} of @var{font}.
 
8038
@end table
 
8039
 
 
8040
@end defun
 
8041
 
 
8042
 
 
8043
@node Font Attributes, Chracter Attributes, Listing Fonts, Font and Characters
 
8044
@section Font Attributes
 
8045
 
 
8046
 
 
8047
The following paragraphs describe the CLX functions used to access font
 
8048
attributes.
 
8049
 
 
8050
@defun font-all-chars-exist-p font
 
8051
 
 
8052
@table @var
 
8053
@item exists-p
 
8054
Type @var{boolean}.
 
8055
@end table
 
8056
 
 
8057
 
 
8058
Returns true if glyphs exist for all indexes in the range returned
 
8059
by @var{font-min-char} and @var{font-max-char}. Returns
 
8060
@var{nil} if an index in the range corresponds to empty glyph.
 
8061
 
 
8062
@table @var
 
8063
@item font
 
8064
A @var{font} object.
 
8065
@end table
 
8066
 
 
8067
@end defun
 
8068
 
 
8069
 
 
8070
@defun font-ascent font
 
8071
 
 
8072
@table @var
 
8073
@item ascent
 
8074
Type @var{int16}.
 
8075
@end table
 
8076
 
 
8077
 
 
8078
Returns the vertical @emph{ascent} of the @emph{font} used for
 
8079
interline spacing. The @emph{ascent} defines the nominal distance
 
8080
in pixels from the baseline to the bottom of the previous line of
 
8081
text.  Some font glyphs may actually extend beyond the font
 
8082
@emph{ascent}.
 
8083
@table @var
 
8084
@item font
 
8085
A @var{font} object.
 
8086
@end table
 
8087
 
 
8088
@end defun
 
8089
 
 
8090
 
 
8091
@defun font-default-char font
 
8092
 
 
8093
@table @var
 
8094
@item index
 
8095
Type @var{card16}.
 
8096
@end table
 
8097
 
 
8098
 
 
8099
Returns the @emph{index} of the glyph drawn when an invalid or
 
8100
empty glyph index is specified.  If the default index specifies an
 
8101
invalid or empty glyph, an invalid or empty index has no effect.
 
8102
@table @var
 
8103
@item font
 
8104
A @var{font} object.
 
8105
@end table
 
8106
 
 
8107
@end defun
 
8108
 
 
8109
 
 
8110
@defun font-descent font
 
8111
 
 
8112
@table @var
 
8113
@item descent
 
8114
Type @var{int16}.
 
8115
@end table
 
8116
 
 
8117
 
 
8118
Returns the vertical @emph{descent} of the @emph{font} used for
 
8119
interline spacing. The @emph{descent} defines the nominal distance
 
8120
in pixels from the baseline to the top of the next line of
 
8121
text. Some font glyphs may actually extend beyond the font
 
8122
@emph{descent}.
 
8123
@table @var
 
8124
@item font
 
8125
A @var{font} object.
 
8126
@end table
 
8127
 
 
8128
@end defun
 
8129
 
 
8130
 
 
8131
@defun font-direction font
 
8132
 
 
8133
@table @var
 
8134
@item direction
 
8135
Type @var{draw-direction}.
 
8136
@end table
 
8137
 
 
8138
 
 
8139
Returns the nominal drawing @emph{direction} for the
 
8140
@emph{font}. The font drawing direction is only a hint that
 
8141
indicates whether the @emph{char-width} of most font glyphs is
 
8142
positive (@var{:left-to-right} direction) or negative
 
8143
(@var{:right-to-left} direction). Note that X does not provide
 
8144
any direct support for vertical text.
 
8145
@table @var
 
8146
@item font
 
8147
A @var{font} object.
 
8148
@end table
 
8149
 
 
8150
@end defun
 
8151
 
 
8152
 
 
8153
@defun font-display font
 
8154
 
 
8155
@table @var
 
8156
@item font
 
8157
A @var{font} object.
 
8158
@end table
 
8159
 
 
8160
Returns the @var{display} object associated with the specified
 
8161
@emph{font}.
 
8162
 
 
8163
@table @var
 
8164
@item display
 
8165
Type @var{display}.
 
8166
@end table
 
8167
 
 
8168
@end defun
 
8169
 
 
8170
 
 
8171
@defun font-equal font-1 font-2
 
8172
 
 
8173
@table @var
 
8174
@item font-1
 
8175
@itemx font-2
 
8176
The @var{font} objects.
 
8177
@end table
 
8178
 
 
8179
Returns true if the two arguments refer to the same server
 
8180
resource and @var{nil} if they do not.
 
8181
 
 
8182
 
 
8183
@end defun
 
8184
 
 
8185
 
 
8186
@defun font-id font
 
8187
 
 
8188
@table @var
 
8189
@item font
 
8190
A @var{font} object.
 
8191
@end table
 
8192
 
 
8193
Returns the unique resource ID assigned to the specified @emph{font}.
 
8194
 
 
8195
@table @var
 
8196
@item id
 
8197
Type @var{resource-id}.
 
8198
@end table
 
8199
 
 
8200
@end defun
 
8201
 
 
8202
 
 
8203
@defun font-max-byte1 font
 
8204
 
 
8205
@table @var
 
8206
@item font
 
8207
A @var{font} object.
 
8208
@end table
 
8209
 
 
8210
 
 
8211
Returns zero if the @emph{font} uses linear index
 
8212
encoding. Otherwise, if the @emph{font} uses matrix index
 
8213
encoding, a value between 1 and 255 is returned that specifies the
 
8214
maximum value for the most significant byte of font indexes.
 
8215
@table @var
 
8216
@item max-byte1
 
8217
Type @var{card8}@emph{.}
 
8218
@end table
 
8219
 
 
8220
@end defun
 
8221
 
 
8222
 
 
8223
@defun font-max-byte2 font
 
8224
 
 
8225
@table @var
 
8226
@item font
 
8227
A @var{font} object.
 
8228
@end table
 
8229
 
 
8230
 
 
8231
Returns zero if the @emph{font} uses linear index
 
8232
encoding. Otherwise, if the @emph{font} uses matrix index
 
8233
encoding, a value between 1 and 255 is returned that specifies the
 
8234
maximum value for the least significant byte of font indexes.
 
8235
@table @var
 
8236
@item max-byte2
 
8237
Type @var{card8}@emph{.}
 
8238
@end table
 
8239
 
 
8240
@end defun
 
8241
 
 
8242
 
 
8243
@defun font-max-char font
 
8244
 
 
8245
@table @var
 
8246
@item font
 
8247
A @var{font} object.
 
8248
@end table
 
8249
 
 
8250
 
 
8251
Returns the maximum valid value used for linear encoded
 
8252
indexes. This function is not meaningful for fonts that use matrix
 
8253
index encoding.
 
8254
@table @var
 
8255
@item index
 
8256
Type @var{card16}.
 
8257
@end table
 
8258
 
 
8259
@end defun
 
8260
 
 
8261
 
 
8262
@defun font-min-byte1 font
 
8263
 
 
8264
@table @var
 
8265
@item font
 
8266
A @var{font} object.
 
8267
@end table
 
8268
 
 
8269
 
 
8270
Returns zero if the @emph{font} uses linear index
 
8271
encoding. Otherwise, if the @emph{font} uses matrix index
 
8272
encoding, a value between 1 and 255 is returned that specifies the
 
8273
minimum value for the most significant byte of font indexes.
 
8274
@table @var
 
8275
@item min-byte1
 
8276
Type @var{card8}.
 
8277
@end table
 
8278
 
 
8279
@end defun
 
8280
 
 
8281
 
 
8282
@defun font-min-byte2 font
 
8283
 
 
8284
@table @var
 
8285
@item font
 
8286
A @var{font} object.
 
8287
@end table
 
8288
 
 
8289
 
 
8290
Returns zero if the @emph{font} uses linear index
 
8291
encoding. Otherwise, if the @emph{font} uses matrix index
 
8292
encoding, a value between 1 and 255 is returned that specifies the
 
8293
minimum value for the least significant byte of font indexes.
 
8294
@table @var
 
8295
@item min-byte2
 
8296
Type @var{card8}.
 
8297
@end table
 
8298
 
 
8299
@end defun
 
8300
 
 
8301
 
 
8302
@defun font-min-char font
 
8303
 
 
8304
@table @var
 
8305
@item font
 
8306
A @var{font} object.
 
8307
@end table
 
8308
 
 
8309
 
 
8310
Returns the minimum valid value used for linear encoded
 
8311
indexes. This function is not meaningful for fonts that use matrix
 
8312
index encoding.
 
8313
@table @var
 
8314
@item index
 
8315
Type @var{card16}.
 
8316
@end table
 
8317
 
 
8318
@end defun
 
8319
 
 
8320
 
 
8321
@defun font-name font
 
8322
 
 
8323
@table @var
 
8324
@item font
 
8325
A @var{font} object.
 
8326
@end table
 
8327
 
 
8328
 
 
8329
Returns the name of the @emph{font}, or @var{nil} if @emph{font}
 
8330
is a pseudo-font.
 
8331
@table @var
 
8332
@item name
 
8333
Type @var{string} or @var{null}.
 
8334
@end table
 
8335
 
 
8336
@end defun
 
8337
 
 
8338
 
 
8339
@defun font-p font
 
8340
 
 
8341
Returns true if the argument is a @var{font} object and
 
8342
@var{nil} otherwise.
 
8343
 
 
8344
@table @var
 
8345
@item font-p
 
8346
Type @var{boolean}.
 
8347
@end table
 
8348
 
 
8349
@end defun
 
8350
 
 
8351
 
 
8352
@defun font-plist font
 
8353
 
 
8354
@table @var
 
8355
@item font
 
8356
A @var{font} object.
 
8357
@end table
 
8358
 
 
8359
 
 
8360
Returns and (with @code{setf}) sets the property list for the
 
8361
specified @emph{font}. This function provides a hook where
 
8362
extensions can add data.
 
8363
@table @var
 
8364
@item plist
 
8365
Type @var{list}.
 
8366
@end table
 
8367
 
 
8368
@end defun
 
8369
 
 
8370
 
 
8371
@defun font-properties font
 
8372
 
 
8373
@table @var
 
8374
@item font
 
8375
A @var{font} object.
 
8376
@end table
 
8377
 
 
8378
 
 
8379
Returns the list of font @emph{properties} recorded by the X
 
8380
server. The returned list is a property list of keyword/value
 
8381
pairs. The set of possible font property keywords is
 
8382
implementation-dependent.
 
8383
@table @var
 
8384
@item properties
 
8385
Type @var{list}.
 
8386
@end table
 
8387
 
 
8388
@end defun
 
8389
 
 
8390
 
 
8391
@defun font-property font name
 
8392
 
 
8393
@table @var
 
8394
@item font
 
8395
A @var{font} object.
 
8396
@item name
 
8397
A font property keyword.
 
8398
@end table
 
8399
 
 
8400
 
 
8401
Returns the value of the font @emph{property} specified by the
 
8402
@emph{name} keyword. The property value, if it exists, is returned
 
8403
as an uninterpreted 32-bit integer.
 
8404
@table @var
 
8405
@item property
 
8406
Type @var{int32} or @var{null}.
 
8407
@end table
 
8408
 
 
8409
@end defun
 
8410
 
 
8411
 
 
8412
@defun max-char-ascent font
 
8413
 
 
8414
@table @var
 
8415
@item font
 
8416
A @var{font} object.
 
8417
@end table
 
8418
 
 
8419
 
 
8420
Returns the maximum @var{char-ascent} value for all characters in
 
8421
@emph{font}.
 
8422
@table @var
 
8423
@item ascent
 
8424
Type @var{int16}.
 
8425
@end table
 
8426
 
 
8427
@end defun
 
8428
 
 
8429
 
 
8430
@defun max-char-attributes font
 
8431
 
 
8432
@table @var
 
8433
@item font
 
8434
A @var{font} object.
 
8435
@end table
 
8436
 
 
8437
 
 
8438
Returns the maximum @var{char-attributes} value for all
 
8439
characters in @emph{font}.
 
8440
@table @var
 
8441
@item attributes
 
8442
Type @var{int16}.
 
8443
@end table
 
8444
 
 
8445
@end defun
 
8446
 
 
8447
 
 
8448
@defun max-char-descent font
 
8449
 
 
8450
@table @var
 
8451
@item font
 
8452
A @var{font} object.
 
8453
@end table
 
8454
 
 
8455
 
 
8456
Returns the maximum @var{char-descent} value for all characters
 
8457
in @emph{font}.
 
8458
@table @var
 
8459
@item descent
 
8460
Type @var{int16}.
 
8461
@end table
 
8462
 
 
8463
@end defun
 
8464
 
 
8465
 
 
8466
@defun max-char-left-bearing font
 
8467
 
 
8468
@table @var
 
8469
@item font
 
8470
A @var{font} object.
 
8471
@end table
 
8472
 
 
8473
 
 
8474
Returns the maximum @var{char-left-bearing} value for all characters in @emph{font}.
 
8475
@table @var
 
8476
@item left-bearing
 
8477
Type @var{int16}.
 
8478
@end table
 
8479
 
 
8480
@end defun
 
8481
 
 
8482
 
 
8483
@defun max-char-right-bearing font
 
8484
 
 
8485
@table @var
 
8486
@item font
 
8487
A @var{font} object.
 
8488
@end table
 
8489
 
 
8490
 
 
8491
Returns the maximum @var{char-right-bearing} value for all
 
8492
characters in @emph{font}.
 
8493
@table @var
 
8494
@item right-bearing
 
8495
Type @var{int16}.
 
8496
@end table
 
8497
 
 
8498
@end defun
 
8499
 
 
8500
 
 
8501
@defun max-char-width font
 
8502
 
 
8503
@table @var
 
8504
@item font
 
8505
A @var{font} object.
 
8506
@end table
 
8507
 
 
8508
 
 
8509
Returns the maximum @var{char-width} value for all characters in
 
8510
@emph{font}.
 
8511
@table @var
 
8512
@item width
 
8513
Type @var{int16}.
 
8514
@end table
 
8515
 
 
8516
@end defun
 
8517
 
 
8518
 
 
8519
@defun min-char-ascent font
 
8520
 
 
8521
@table @var
 
8522
@item font
 
8523
A @var{font} object.
 
8524
@end table
 
8525
 
 
8526
 
 
8527
Returns the minimum @var{char-ascent} for all characters in
 
8528
@emph{font}.
 
8529
@table @var
 
8530
@item ascent
 
8531
Type @var{int16}.
 
8532
@end table
 
8533
 
 
8534
@end defun
 
8535
 
 
8536
 
 
8537
@defun min-char-attributes font
 
8538
 
 
8539
@table @var
 
8540
@item font
 
8541
A @var{font} object.
 
8542
@end table
 
8543
 
 
8544
 
 
8545
Returns the minimum @var{char-attributes} for all characters in @emph{font}.
 
8546
@table @var
 
8547
@item attributes
 
8548
Type @var{int16}.
 
8549
@end table
 
8550
 
 
8551
@end defun
 
8552
 
 
8553
 
 
8554
@defun min-char-descent font
 
8555
 
 
8556
@table @var
 
8557
@item font
 
8558
A @var{font} object.
 
8559
@end table
 
8560
 
 
8561
 
 
8562
Returns the minimum @var{char-descent} for all characters in @emph{font}.
 
8563
@table @var
 
8564
@item descent
 
8565
Type @var{int16}.
 
8566
@end table
 
8567
 
 
8568
@end defun
 
8569
 
 
8570
 
 
8571
@defun min-char-left-bearing font
 
8572
 
 
8573
@table @var
 
8574
@item font
 
8575
A @var{font} object.
 
8576
@end table
 
8577
 
 
8578
 
 
8579
Returns the minimum @var{char-left-bearing} for all characters in
 
8580
@emph{font}.
 
8581
@table @var
 
8582
@item left-bearing
 
8583
Type @var{int16}.
 
8584
@end table
 
8585
 
 
8586
@end defun
 
8587
 
 
8588
 
 
8589
@defun min-char-right-bearing font
 
8590
 
 
8591
@table @var
 
8592
@item font
 
8593
A @var{font} object.
 
8594
@end table
 
8595
 
 
8596
 
 
8597
Returns the minimum @var{char-right-bearing} for all characters
 
8598
in @emph{font}.
 
8599
@table @var
 
8600
@item right-bearing
 
8601
Type @var{int16}.
 
8602
@end table
 
8603
 
 
8604
@end defun
 
8605
 
 
8606
 
 
8607
@defun min-char-width font
 
8608
 
 
8609
@table @var
 
8610
@item font
 
8611
A @var{font} object.
 
8612
@end table
 
8613
 
 
8614
 
 
8615
Returns the minimum @var{char-width} for all characters in
 
8616
@emph{font}.
 
8617
@table @var
 
8618
@item width
 
8619
Type @var{int16}.
 
8620
@end table
 
8621
 
 
8622
@end defun
 
8623
 
 
8624
 
 
8625
@node Chracter Attributes, Querying Text Size, Font Attributes, Font and Characters
 
8626
@section Chracter Attributes
 
8627
 
 
8628
 
 
8629
The following paragraphs describe the CLX functions used to access the
 
8630
attributes of individual font glyphs.
 
8631
 
 
8632
@defun char-ascent font index
 
8633
 
 
8634
@table @var
 
8635
@item font
 
8636
A @var{font} object.
 
8637
@item index
 
8638
An @var{int16} font index.
 
8639
@end table
 
8640
 
 
8641
 
 
8642
Returns the vertical distance in pixels from the baseline to the top
 
8643
of the given font glyph. Returns @var{nil} if the index is invalid
 
8644
or specifies an empty glyph, or if the @emph{font} is a pseudo-font.
 
8645
@table @var
 
8646
@item ascent
 
8647
Type @var{int16} or @var{null}.
 
8648
@end table
 
8649
 
 
8650
@end defun
 
8651
 
 
8652
 
 
8653
@defun char-attributes font index
 
8654
 
 
8655
@table @var
 
8656
@item font
 
8657
A @var{font} object.
 
8658
@item index
 
8659
An @var{int16} font index.
 
8660
@end table
 
8661
 
 
8662
 
 
8663
Returns font-specific @emph{attributes} of the given glyph. The
 
8664
interpretation of such attributes is server-dependent. Returns
 
8665
@var{nil} if the @emph{index} is invalid or specifies an empty
 
8666
glyph, or if the @emph{font} is a pseudo-font.
 
8667
@table @var
 
8668
@item attributes
 
8669
Type @var{int16} or @var{null}.
 
8670
@end table
 
8671
 
 
8672
@end defun
 
8673
 
 
8674
 
 
8675
@defun char-descent font index
 
8676
 
 
8677
@table @var
 
8678
@item font
 
8679
A @var{font} object.
 
8680
@item index
 
8681
An @var{int16} font index.
 
8682
@end table
 
8683
 
 
8684
 
 
8685
Returns the vertical distance in pixels from the baseline to the
 
8686
bottom of the given font glyph. Returns @var{nil} if the
 
8687
@emph{index} is invalid or specifies an empty glyph, or if the
 
8688
@emph{font} is a pseudo-font.
 
8689
@table @var
 
8690
@item descent
 
8691
Type @var{int16} or @var{null}.
 
8692
@end table
 
8693
 
 
8694
@end defun
 
8695
 
 
8696
 
 
8697
@defun char-left-bearing font index
 
8698
 
 
8699
@table @var
 
8700
@item font
 
8701
A @var{font} object.
 
8702
@item index
 
8703
An @var{int16} font index.
 
8704
@end table
 
8705
 
 
8706
 
 
8707
Returns the left side bearing of the given font glyph. If
 
8708
@var{draw-glyph} is called with horizontal position @emph{x},
 
8709
the leftmost pixel of the glyph is drawn at the position
 
8710
(+ @emph{x left-bearing}). Returns @var{nil} if the
 
8711
@emph{index} is invalid or specifies an empty glyph, or if the
 
8712
@emph{font} is a pseudo-font.
 
8713
@table @var
 
8714
@item left-bearing
 
8715
Type @var{int16} or @var{null}.
 
8716
@end table
 
8717
 
 
8718
@end defun
 
8719
 
 
8720
 
 
8721
@defun char-right-bearing font index
 
8722
 
 
8723
@table @var
 
8724
@item font
 
8725
A @emph{font} object.
 
8726
@item index
 
8727
An @var{int16} font index.
 
8728
@end table
 
8729
 
 
8730
 
 
8731
Returns the right side bearing of the given font glyph. If
 
8732
n@var{draw-glyph} is called with horizontal position @emph{x},
 
8733
the rightmost pixel of the glyph is drawn at the position (+
 
8734
@emph{x rightbearing}). Returns @var{nil} if the
 
8735
@emph{index} is invalid or specifies an empty glyph, or if the
 
8736
@emph{font} is a pseudo-font.
 
8737
 
 
8738
@table @var
 
8739
@item right-bearing
 
8740
Type @var{int16} or @var{null}.
 
8741
@end table
 
8742
 
 
8743
@end defun
 
8744
 
 
8745
 
 
8746
@defun char-width font index
 
8747
 
 
8748
@table @var
 
8749
@item font
 
8750
A @var{font} object.
 
8751
@item index
 
8752
An @var{int16} font index.
 
8753
@end table
 
8754
 
 
8755
Returns the @emph{width} of the given font glyph. The @emph{width}
 
8756
is defined to be equal to (- @emph{rightbearing
 
8757
left-bearing}). Returns @var{nil} if the @emph{index} is invalid
 
8758
or specifies an empty glyph, or if the @emph{font} is a pseudo-font.
 
8759
 
 
8760
@table @var
 
8761
@item width
 
8762
Type @var{int16} or @var{null}.
 
8763
@end table
 
8764
 
 
8765
@end defun
 
8766
 
 
8767
 
 
8768
@node Querying Text Size,  , Chracter Attributes, Font and Characters
 
8769
@section Querying Text Size
 
8770
 
 
8771
 
 
8772
CLX defines functions to return the size of text drawn in a specified
 
8773
font. @xref{Drawing Text}, for a description of the
 
8774
@var{:translate} function used by the functions in the following
 
8775
paragraphs.
 
8776
 
 
8777
@defun text-extents font sequence &key (:start 0) :end :translate
 
8778
@anchor{text-extents}
 
8779
 
 
8780
@table @var
 
8781
@item font
 
8782
The font (or @var{gcontext}) used for measuring characters.
 
8783
@item sequence
 
8784
A sequence of characters or other objects to be translated into font indexes.
 
8785
@item :start
 
8786
@itemx :end
 
8787
Start and end indexes defining the elements to draw.
 
8788
@item :translate
 
8789
A function to translate text to font indexes. Default is
 
8790
@var{#'translate-default}.
 
8791
@end table
 
8792
 
 
8793
Returns the complete geometry of the given @emph{sequence} when
 
8794
drawn in the given @emph{fon}t. The @emph{font} can be a
 
8795
@var{gcontext}, in which case the font attribute of the given
 
8796
graphics context is used. @var{:start} and @var{:end} define the
 
8797
elements of the @emph{sequence} which are used.
 
8798
 
 
8799
The returned @emph{width} is the total pixel width of the
 
8800
translated character sequence. The returned @emph{ascent} and
 
8801
@emph{descent} give the vertical ascent and descent for characters
 
8802
in the translated @emph{sequence}. The returned @emph{left} gives
 
8803
the left bearing of the leftmost character. The returned
 
8804
@emph{right} gives the right bearing of the rightmost
 
8805
character. The returned @emph{font-ascent} and @emph{font-descent}
 
8806
give the maximum vertical ascent and descent for all characters in
 
8807
the @emph{fon}t. If @var{:translate} causes font changes, then
 
8808
@emph{font-ascent} and @emph{font-descent} will be the maximums
 
8809
over all fonts used. The @emph{direction} returns the preferred
 
8810
draw direction for the font. If @var{:translate} causes font
 
8811
changes, then the @emph{direction} will be @var{nil}. The
 
8812
@emph{first-not-done} value returned is @var{nil} if all elements
 
8813
of the @emph{sequence} were successfully translated; otherwise the
 
8814
index of the first untranslated element is returned.
 
8815
 
 
8816
@table @var
 
8817
@item width
 
8818
Type @var{int32}.
 
8819
@item ascent
 
8820
Type @var{int16}.
 
8821
@item descent
 
8822
Type @var{int16}.
 
8823
@item left
 
8824
Type @var{int32}.
 
8825
@item right
 
8826
Type @var{int32}.
 
8827
@item font-ascent
 
8828
Type @var{int16}.
 
8829
@item direction
 
8830
Type @var{draw-direction}.
 
8831
@item first-not-done
 
8832
Type @var{array-index} or @var{null}.
 
8833
@end table
 
8834
 
 
8835
@end defun
 
8836
 
 
8837
 
 
8838
@defun text-width font sequence &key (:start 0) :end :translate
 
8839
 
 
8840
@table @var
 
8841
@item font
 
8842
The font (or @var{gcontext}) used for measuring characters.
 
8843
@item sequence
 
8844
A sequence of characters or other objects to be translated into font indexes.
 
8845
@item :start
 
8846
@item :end
 
8847
Start and end indexes defining the elements to draw.
 
8848
@item :translate
 
8849
A function to translate text to font indexes. Default is
 
8850
@var{#'translate-default}.
 
8851
@end table
 
8852
 
 
8853
 
 
8854
Returns the total pixel width of the given @emph{sequence} when
 
8855
drawn in the given @emph{font}. The @emph{font} can be a
 
8856
@var{gcontext}, in which case the font attribute of the given
 
8857
graphics context is used. @var{:start} and @var{:end} define the
 
8858
elements of the @emph{sequence} which are used. The second value
 
8859
returned is @var{nil} if all elements of the @emph{sequence} were
 
8860
successfully translated; otherwise the index of the first
 
8861
untranslated element is returned.
 
8862
@table @var
 
8863
@item width
 
8864
Type @var{int32}.
 
8865
@item first-not-done
 
8866
Type @var{array-index} or @var{null}.
 
8867
@end table
 
8868
 
 
8869
@end defun
 
8870
 
 
8871
 
 
8872
@node Colors, Cursors, Font and Characters, Top
 
8873
@chapter Colors
 
8874
 
 
8875
@menu
 
8876
* Colormaps and Colors::
 
8877
* Color Functions::
 
8878
* Colormap Functions::
 
8879
@end menu
 
8880
 
 
8881
@node Colormaps and Colors, Color Functions, Colors, Colors
 
8882
@section Colormaps and Colors
 
8883
 
 
8884
 
 
8885
In X, a @emph{color} is defined by a set of three numeric values,
 
8886
representing intensities of red, green, and blue. Red, green, and blue
 
8887
are referred to as the @emph{primary} hues. A @emph{colormap} is a list
 
8888
of colors, each indexed by an integer @emph{pixel} value. Each entry in
 
8889
a colormap is called a color @emph{cell}. Raster graphics displays store
 
8890
pixel values in a special screen hardware memory. As the screen hardware
 
8891
scans this memory, it reads each pixel value, looks up the color in the
 
8892
corresponding cell of a colormap, and displays the color on its screen.
 
8893
 
 
8894
The colormap abstraction applies to all classes of visual types
 
8895
supported by X, including those for screens which are actually
 
8896
monochrome. For example, @var{:gray-scale} screens use colormaps in
 
8897
which colors actually specify the monochrome intensity. A typical
 
8898
black-and-white monochrome display has a @var{:static-gray} screen with
 
8899
a two-cell colormap.
 
8900
 
 
8901
The following list describes how pixel values and colormaps are handled
 
8902
for each visual class.
 
8903
 
 
8904
@table @var
 
8905
@item :direct-color
 
8906
A pixel value is decomposed into separate red, green, and blue
 
8907
subfields. Each subfield indexes a separate colormap. Entries in all colormaps can
 
8908
be changed.
 
8909
@item :gray-scale
 
8910
A pixel value indexes a single colormap that contains monochrome
 
8911
intensities. Colormap entries can be changed.
 
8912
@item :pseudo-color
 
8913
A pixel value indexes a single colormap that contains color
 
8914
intensities. Colormap entries can be changed.
 
8915
@item :static-color
 
8916
Same as @var{:pseudo-color}, except that the colormap entries are
 
8917
predefined by the hardware and cannot be changed.
 
8918
@item :static-gray
 
8919
Same as @var{:gray-scale}, except that the colormap entries are
 
8920
predefined by the hardware and cannot be changed.
 
8921
@item :true-color
 
8922
Same as @var{:direct-color}, except that the colormap entries are
 
8923
predefined by the hardware and cannot be changed. Typically, each of
 
8924
the red, green, and blue colormaps provides a (near) linear ramp of
 
8925
intensity.
 
8926
@end table
 
8927
 
 
8928
CLX provides functions to create colormaps, access and modify colors and
 
8929
color cells, and install colormaps in screen hardware.
 
8930
 
 
8931
@node Color Functions, Colormap Functions, Colormaps and Colors, Colors
 
8932
@section Color Functions
 
8933
 
 
8934
 
 
8935
A color is represented by a CLX color object, in which each of the red,
 
8936
green, and blue values is specified by an @var{rgb-val} -- a floating
 
8937
point number between 0.0 and 1.0.  (@pxref{Data Types}). The
 
8938
value 0.0 represents the minimum intensity, while 1.0 represents the
 
8939
maximum intensity. CLX automatically converts @var{rgb-val} values into
 
8940
16-bit integers when sending colors to an X server. The X server, in
 
8941
turn, scales 16-bit color values to match the actual intensity range
 
8942
supported by the screen.
 
8943
 
 
8944
Colors used on @var{:gray-scale} screens must have the same value for
 
8945
each of red, green, and blue. Only one of these values is used by screen
 
8946
hardware to determine intensity; however, CLX does not define which of
 
8947
red, green, or blue is actually used.
 
8948
 
 
8949
The following paragraphs describe the CLX functions used to create,
 
8950
access, and modify colors.
 
8951
 
 
8952
@defun make-color &key (:blue 1.0) (:green 1.0) (:red 1.0) &allow-other-keys
 
8953
 
 
8954
@table @var
 
8955
@item :blue
 
8956
@itemx :green
 
8957
@itemx :red
 
8958
@var{rgb-val} values that specify the saturation for each primary.
 
8959
@end table
 
8960
 
 
8961
 
 
8962
Creates, initializes, and returns a new @var{color} object with the
 
8963
specified values for red, green, and blue.
 
8964
@table @var
 
8965
@item color
 
8966
Type @var{color}.
 
8967
@end table
 
8968
 
 
8969
@end defun
 
8970
 
 
8971
 
 
8972
@defun color-blue color
 
8973
 
 
8974
@table @var
 
8975
@item color
 
8976
A @var{color} object.
 
8977
@end table
 
8978
 
 
8979
 
 
8980
Returns and (with @code{setf}) sets the value for blue in the
 
8981
@emph{color}.
 
8982
@table @var
 
8983
@item blue-intensity
 
8984
Type @var{rgb-val}.
 
8985
@end table
 
8986
 
 
8987
@end defun
 
8988
 
 
8989
 
 
8990
@defun color-green color
 
8991
 
 
8992
@table @var
 
8993
@item color
 
8994
A @var{color} object.
 
8995
@end table
 
8996
 
 
8997
 
 
8998
Returns and (with @code{setf}) sets the value for green in the
 
8999
@emph{color}.
 
9000
@table @var
 
9001
@item green-intensity
 
9002
Type @var{rgb-val}.
 
9003
@end table
 
9004
 
 
9005
@end defun
 
9006
 
 
9007
 
 
9008
@defun color-p color
 
9009
 
 
9010
Returns non-@var{nil} if the argument is a @var{color} object and
 
9011
@var{nil} otherwise.
 
9012
 
 
9013
@table @var
 
9014
@item color-p
 
9015
Type @var{boolean}.
 
9016
@end table
 
9017
 
 
9018
@end defun
 
9019
 
 
9020
@defun color-red color
 
9021
 
 
9022
@table @var
 
9023
@item color
 
9024
A @var{color} object.
 
9025
@end table
 
9026
 
 
9027
 
 
9028
Returns and (with @code{setf}) sets the value for red in the
 
9029
@emph{color}.
 
9030
@table @var
 
9031
@item red-intensity
 
9032
Type @var{rgb-val}.
 
9033
@end table
 
9034
 
 
9035
@end defun
 
9036
 
 
9037
 
 
9038
@defun color-rgb color
 
9039
 
 
9040
@table @var
 
9041
@item color
 
9042
A @var{color} object.
 
9043
@end table
 
9044
 
 
9045
 
 
9046
Returns the values for red, green, and blue in the @emph{color}.
 
9047
@table @var
 
9048
@item red
 
9049
@itemx green
 
9050
@itemx blue
 
9051
Type @var{rgb-val}.
 
9052
@end table
 
9053
 
 
9054
@end defun
 
9055
 
 
9056
 
 
9057
@node Colormap Functions,  , Color Functions, Colors
 
9058
@section Colormap Functions
 
9059
 
 
9060
 
 
9061
A colormap is represented in CLX by a @var{colormap} object. A CLX
 
9062
program can create and manipulate several @var{colormap}
 
9063
objects. However, the colors contained in a @var{colormap} are made
 
9064
visible only when the @var{colormap} is @emph{installed}. Each window
 
9065
is associated with a @var{colormap} that is used to translate window
 
9066
pixels into colors (see @var{window-colormap}). However, a window will
 
9067
appear in its true colors only if its associated @var{colormap} is
 
9068
installed.
 
9069
 
 
9070
The total number of colormaps that can be installed depends on the
 
9071
screen hardware.  Most hardware devices allow exactly one
 
9072
@var{colormap} to be installed at any time. That is,
 
9073
@var{screen-min-installed-maps} and @var{screen-max-installed-maps}
 
9074
are both equal to 1.  Installing a new @var{colormap} can cause a
 
9075
previously installed @var{colormap} to be uninstalled. It is important
 
9076
to remember that the set of installed @var{colormaps} is a hardware
 
9077
resource shared cooperatively among all client programs connected to an
 
9078
X server.
 
9079
 
 
9080
A CLX program can control the contents of @var{colormaps} by allocating
 
9081
color cells in one of two ways: read-only or read-write. Allocating a
 
9082
read-only color cell establishes a color value for a specified pixel
 
9083
value that cannot be changed. However, read-only color cells can be
 
9084
shared among all client programs. Read-only allocation is the best
 
9085
strategy for making use of limited @var{colormap} hardware in a
 
9086
multi-client environment.
 
9087
 
 
9088
Alternatively, allocating a read-write color cell allows a client the
 
9089
exclusive right to set the color value stored in the cell. A cell
 
9090
allocated read-write by one client cannot be allocated by another
 
9091
client, not even as a read-only cell. Note that read-write allocation is
 
9092
not allowed for screens whose visual type belongs to one of the
 
9093
@var{:static-gray}, @var{:static-color}, or @var{:true-color}
 
9094
classes. For screens of these classes, @var{colormap} cells cannot be
 
9095
modified.
 
9096
 
 
9097
Two entries of the default colormap, typically containing the colors
 
9098
black and white, are automatically allocated read-only. The pixel values
 
9099
for these entries can be returned by the functions
 
9100
@var{screen-black-pixel} and @var{screen-white-pixel}. Applications
 
9101
that need only two colors and also need to operate on both monochrome
 
9102
and color screens should always use these pixel values. The names
 
9103
@emph{black} and @emph{white} are intended to reflect relative intensity
 
9104
levels and need not reflect the actual colors displayed for these pixel
 
9105
values.
 
9106
 
 
9107
Each screen has a default @var{colormap}, which is initially
 
9108
installed. By conventions, clients should allocate only read-only cells
 
9109
from the default @var{colormap}.
 
9110
 
 
9111
@menu
 
9112
* Creating Colormaps::
 
9113
* Installing Colormaps::
 
9114
* Allocating Colors::
 
9115
* Finding Colors::
 
9116
* Changing Colors::
 
9117
* Colormap Attributes::
 
9118
@end menu
 
9119
 
 
9120
@node Creating Colormaps, Installing Colormaps, Colormap Functions, Colormap Functions
 
9121
@subsection Creating Colormaps
 
9122
 
 
9123
 
 
9124
CLX provides functions for creating and freeing new @var{colormap}
 
9125
objects.
 
9126
 
 
9127
@defun create-colormap visual window &optional alloc-p
 
9128
 
 
9129
@table @var
 
9130
@item visual
 
9131
A @var{visual} type ID.
 
9132
@item window
 
9133
A @var{window}.
 
9134
@item alloc-p
 
9135
Specifies whether @var{colormap} cells are permanently allocated read-write.
 
9136
@end table
 
9137
 
 
9138
 
 
9139
Creates and returns a @emph{colormap} of the specified
 
9140
@emph{visual} type for the screen containing the
 
9141
@emph{window}. The @emph{visual} type must be one of those
 
9142
supported by the screen.
 
9143
 
 
9144
Initial color cell values are undefined for visual types belonging
 
9145
to the @var{:gray-scale}, @var{:pseudo-color}, and
 
9146
@var{:direct-color} classes. Color cell values for visual types
 
9147
belonging to the @var{:static-gray}, @var{:static-color}, and
 
9148
@var{:true-color} classes have initial values defined by the
 
9149
visual type. However, X does not define the set of possible visual
 
9150
types or their initial color cell values.
 
9151
 
 
9152
If @emph{alloc-p} is true, all colormap cells are permanently
 
9153
allocated read-write and cannot be freed by @var{free-colors}. It
 
9154
is an error for @emph{alloc-p} to be true when the visual type
 
9155
belongs to the @var{:static-gray}, @var{:static-color}, or
 
9156
@var{:true-color} classes.
 
9157
 
 
9158
@table @var
 
9159
@item colormap
 
9160
Type @var{colormap}.
 
9161
@end table
 
9162
 
 
9163
@end defun
 
9164
 
 
9165
 
 
9166
@defun copy-colormap-and-free colormap
 
9167
 
 
9168
@table @var
 
9169
@item colormap
 
9170
A @var{colormap}.
 
9171
@end table
 
9172
 
 
9173
Creates and returns a new @var{colormap} by copying, then
 
9174
freeing, allocated cells from the specified @emph{colormap}.
 
9175
 
 
9176
All color cells allocated read-only or read-write in the original
 
9177
@var{colormap} have the same color values and the same allocation
 
9178
status in the @emph{new-colormap}. The values of unallocated color
 
9179
cells in the @emph{new-colormap} are undefined. After copying, all
 
9180
allocated color cells in the original @var{colormap} are freed,
 
9181
as if @var{free-colors} was called. The unallocated cells of the
 
9182
original @var{colormap} are not affected.
 
9183
 
 
9184
If @emph{alloc-p} was true when the original @var{colormap} was
 
9185
created, then all color cells of the @emph{new-colormap} are
 
9186
permanently allocated read-write, and all the color cells of the
 
9187
original @var{colormap} are freed.
 
9188
 
 
9189
@table @var
 
9190
@item new-colormap
 
9191
Type @var{colormap}.
 
9192
@end table
 
9193
 
 
9194
@end defun
 
9195
 
 
9196
 
 
9197
@defun free-colormap colormap
 
9198
 
 
9199
@table @var
 
9200
@item colormap
 
9201
A @var{colormap}.
 
9202
@end table
 
9203
 
 
9204
Destroys the @emph{colormap} and frees its server resource. If the
 
9205
@emph{colormap} is installed, it is uninstalled. For any window
 
9206
associated with the @emph{colormap}, the window is assigned a
 
9207
@var{nil} @var{colormap}, and a @var{:colormap-notify} event is
 
9208
generated. The colors displayed for a window with a @var{nil
 
9209
colormap} are undefined.
 
9210
 
 
9211
However, this function has no effect if the @emph{colormap} is a
 
9212
screen default @var{colormap}.
 
9213
 
 
9214
@end defun
 
9215
 
 
9216
 
 
9217
@node Installing Colormaps, Allocating Colors, Creating Colormaps, Colormap Functions
 
9218
@subsection Installing Colormaps
 
9219
 
 
9220
 
 
9221
The following paragraphs describe the CLX functions to install and
 
9222
uninstall colormaps and to return the set of installed colormaps.
 
9223
 
 
9224
Initially, the default @var{colormap} for a screen is installed (but is
 
9225
not in the required list).
 
9226
 
 
9227
@defun install-colormap colormap
 
9228
@anchor{install-colormap}
 
9229
 
 
9230
@table @var
 
9231
@item colormap
 
9232
A @var{colormap}.
 
9233
@end table
 
9234
 
 
9235
Installs the @emph{colormap.} All windows associated with this
 
9236
@emph{colormap} immediately display with true colors. As a
 
9237
side-effect, additional colormaps might be implicitly uninstalled by
 
9238
the server.
 
9239
 
 
9240
If the specified @emph{colormap} is not already installed, a
 
9241
@var{:colormap-notify} event is generated on every window
 
9242
associated with this @emph{colormap}. In addition, for every other
 
9243
colormap that is implicitly uninstalled, a @var{:colormap-notify}
 
9244
event is generated on every associated window.
 
9245
 
 
9246
 
 
9247
@end defun
 
9248
 
 
9249
 
 
9250
@defun installed-colormaps window &key (:result-type 'list)
 
9251
 
 
9252
@table @var
 
9253
@item window
 
9254
A @var{window}.
 
9255
@item :result-type
 
9256
A sub-type of @var{sequence} that indicates the type of sequence to return.
 
9257
@end table
 
9258
 
 
9259
 
 
9260
Returns a sequence containing the installed @var{colormaps} for the
 
9261
screen of the specified @emph{window}. The order of the colormaps is
 
9262
not significant.
 
9263
@table @var
 
9264
@item colormap
 
9265
Type @var{sequence} of @var{colormap}.
 
9266
@end table
 
9267
 
 
9268
@end defun
 
9269
 
 
9270
 
 
9271
@defun uninstall-colormap colormap
 
9272
 
 
9273
@table @var
 
9274
@item colormap
 
9275
A @var{colormap}.
 
9276
@end table
 
9277
 
 
9278
Uninstalls the @emph{colormap}. However, the @emph{colormap} is not
 
9279
actually uninstalled if this would reduce the set of installed
 
9280
colormaps below the value of @var{screen-min-installed-maps}. If
 
9281
the @emph{colormap} is actually uninstalled, a
 
9282
@var{:colormap-notify} event is generated on every associated
 
9283
window.
 
9284
 
 
9285
 
 
9286
@end defun
 
9287
 
 
9288
 
 
9289
@node Allocating Colors, Finding Colors, Installing Colormaps, Colormap Functions
 
9290
@subsection Allocating Colors
 
9291
 
 
9292
 
 
9293
The following paragraphs describe the functions for allocating read-only
 
9294
and read-write color cells, allocating color planes, and freeing color
 
9295
cells.
 
9296
 
 
9297
@defun alloc-color colormap color
 
9298
 
 
9299
@table @var
 
9300
@item colormap
 
9301
A @var{colormap}.
 
9302
@item color
 
9303
A @var{color} object or a @var{stringable} containing a color name.
 
9304
@end table
 
9305
 
 
9306
 
 
9307
Returns a @emph{pixel} for a read-only color cell in the
 
9308
@emph{colormap}. The color in the allocated cell is the closest
 
9309
approximation to the requested @emph{color} possible for the screen
 
9310
hardware. The other values returned give both the approximate color
 
9311
stored in the cell and the exact color requested.
 
9312
 
 
9313
The requested @emph{color} can be either a @var{color} object or a
 
9314
@var{stringable} containing a color name.  If a color name is
 
9315
given, a corresponding color value is looked up (see
 
9316
@var{lookup-color}) and used. Color name strings must contain only
 
9317
ISO Latin-1 characters; case is not significant.
 
9318
 
 
9319
@table @var
 
9320
@item pixel
 
9321
Type @var{pixel}.
 
9322
@item screen-color
 
9323
@itemx exact-color
 
9324
Type @var{color}.
 
9325
@end table
 
9326
 
 
9327
@end defun
 
9328
 
 
9329
 
 
9330
@defun alloc-color-cells colormap colors &key (:planes 0) :contiguous-p (:result-type 'list)
 
9331
 
 
9332
@table @var
 
9333
@item colormap
 
9334
A @var{colormap}.
 
9335
@item colors
 
9336
A positive number defining the length of the pixels sequence returned.
 
9337
@item :planes
 
9338
A non-negative number defining the length of the masks sequence returned.
 
9339
@item :contiguous-p
 
9340
If true, the masks form contiguous sets of bits.
 
9341
@item :result-type
 
9342
A subtype of @var{sequence} that indicates the type of sequences returned.
 
9343
@end table
 
9344
 
 
9345
 
 
9346
Returns a @var{sequence} of @emph{pixels} for read-write color
 
9347
cells in the @emph{colormap}. The allocated cells contain undefined
 
9348
color values. The visual type class of the @var{colormap} must be
 
9349
either @var{:gray-scale}, @var{:pseudo-color}, or
 
9350
@var{:direct-color}.
 
9351
 
 
9352
The @emph{colors} argument and the @var{:planes} argument define
 
9353
the number of pixels and the number of masks returned,
 
9354
respectively. The number of colors must be positive, and the number
 
9355
of planes must be non-negative. A total of (* @emph{colors}
 
9356
(@var{expt} 2 @emph{planes})) color cells are allocated. The pixel
 
9357
values for the allocated cells can be computed by combining the
 
9358
returned pixels and masks.
 
9359
 
 
9360
The length of the returned masks sequence is equal to
 
9361
@var{:planes}. Each mask of the returned masks sequence defines a
 
9362
single bitplane. None of the masks have any 1 bits in common. Thus,
 
9363
by selectively combining masks with @var{logior}, (@var{expt} 2
 
9364
@emph{planes}) distinct combined plane masks can be computed.
 
9365
 
 
9366
The length of the returned @emph{pixels} sequence is equal to
 
9367
@emph{colors}. None of the pixels have any 1 bits in common with
 
9368
each other or with any of the returned masks. By combining pixels
 
9369
and plane masks with @var{logior}, (* @emph{colors} (@var{expt} 2
 
9370
@emph{planes})) distinct pixel values can be produced.
 
9371
 
 
9372
If the @emph{colormap} class is @var{:gray-scale} or
 
9373
@var{:pseudo-color}, each @emph{mask} will have exactly one bit
 
9374
set. If the @var{colormap} class is @var{:direct-color}, each
 
9375
@emph{mask} will have exactly three bits set.  If
 
9376
@var{:contiguous-p} is true, combining all masks with @var{logior}
 
9377
produces a plane mask with either one set of contiguous bits (for
 
9378
@var{:gray-scale} and @var{:pseudo-color}) or three sets of
 
9379
contiguous bits (for @var{:direct-color}).
 
9380
 
 
9381
@table @var
 
9382
@item pixels
 
9383
@itemx mask
 
9384
Type @var{sequence} of @var{pixels}.
 
9385
@end table
 
9386
 
 
9387
@end defun
 
9388
 
 
9389
 
 
9390
@defun alloc-color-planes colormap colors &key (:reds 0) (:greens 0) (:blues 0) :contiguous-p (:result-type 'list)
 
9391
 
 
9392
@table @var
 
9393
@item colormap
 
9394
A @var{colormap}.
 
9395
@item colors
 
9396
A positive number defining the length of the pixels sequence returned.
 
9397
@item :planes
 
9398
A non-negative number defining the length of the masks sequence returned.
 
9399
@item :contiguous-p
 
9400
If true, then the masks form contiguous sets of bits.
 
9401
@item :result-type
 
9402
A subtype of @var{sequence} that indicates the type of sequences returned.
 
9403
@end table
 
9404
 
 
9405
 
 
9406
Returns a @var{sequence} of @emph{pixels} for read-write color
 
9407
cells in the @emph{colormap}. The allocated cells contain undefined
 
9408
color values. The visual type class of the @emph{colormap} must be
 
9409
either @var{:gray-scale}, @var{:pseudo-color}, or
 
9410
@var{:direct-color}.
 
9411
 
 
9412
The @emph{colors} argument defines the number of pixels
 
9413
returned. The @var{:reds}, @var{:greens}, and @var{:blues}
 
9414
arguments define the number of bits set in the returned red, green,
 
9415
and blue masks, respectively. The number of colors must be positive,
 
9416
and the number of bits for each mask must be non-negative. A total
 
9417
of (* @emph{colors} (@var{expt} 2 (+ @emph{reds greens}
 
9418
@emph{blues}))) color cells are allocated. The pixel values for the
 
9419
allocated cells can be computed by combining the returned
 
9420
@emph{pixels} and masks.
 
9421
 
 
9422
Each mask of the returned masks defines a pixel subfield for the
 
9423
corresponding primary.  None of the masks have any 1 bits in
 
9424
common. By selectively combining subsets of the red, green, and blue
 
9425
masks with @var{logior}, (@var{expt} 2 (+ @emph{reds greens
 
9426
blues}) distinct combined plane masks can be computed.
 
9427
 
 
9428
The length of the returned @emph{pixels} @var{sequence} is equal to
 
9429
@emph{colors}. None of the pixels have any 1 bits in common with
 
9430
each other or with any of the returned masks. By combining pixels
 
9431
and plane masks with @var{logior}, (* @emph{colors} (@var{expt} 2
 
9432
(+ @emph{reds greens blues})) distinct pixel values can be produced.
 
9433
 
 
9434
If @var{:contiguous-p} is true, each of returned masks consists of
 
9435
a set of contiguous bits. If the @var{colormap} class is
 
9436
@var{:direct-color}, each returned mask lies within the pixel
 
9437
subfield for its primary.
 
9438
 
 
9439
@table @var
 
9440
@item pixels
 
9441
Type @var{sequence} of @var{pixel}.
 
9442
@item red-mask
 
9443
@itemx green-mask
 
9444
@itemx blue-mask
 
9445
Type @var{pixel}.
 
9446
@end table
 
9447
 
 
9448
@end defun
 
9449
 
 
9450
 
 
9451
@defun free-colors colormap pixels &optional (plane-mask 0)
 
9452
 
 
9453
@table @var
 
9454
@item colormap
 
9455
A @var{colormap}.
 
9456
@item pixels
 
9457
A @var{sequence} of pixel values.
 
9458
@item plane-mask
 
9459
A pixel value with no bits in common with any of the @emph{pixels}.
 
9460
@end table
 
9461
 
 
9462
Frees a set of allocated color cells from the @emph{colormap}. The
 
9463
pixel values for the freed cells are computed by combining the given
 
9464
@emph{pixels} sequence and @var{:plane-mask}. The total number of
 
9465
cells freed is:
 
9466
 
 
9467
@lisp
 
9468
(* (@var{length} @emph{pixels}) (@var{expt} 2 (@var{logcount} @emph{plane-mask})))
 
9469
@end lisp
 
9470
 
 
9471
The @var{:plane-mask} must not have any bits in common with any of
 
9472
the given @emph{pixels}. The pixel values for the freed cells are
 
9473
produced by using @var{logior} to combine each of the given pixels
 
9474
with all subsets of the @var{:plane-mask}.
 
9475
 
 
9476
Note that freeing an individual pixel allocated by
 
9477
@var{alloc-color-planes} may not allow it to be reused until all
 
9478
related pixels computed from the same plane mask are also freed.
 
9479
 
 
9480
A single error is generated if any computed pixel is invalid or if
 
9481
its color cell is not allocated by the client. Even if an error is
 
9482
generated, all valid pixel values are freed.
 
9483
 
 
9484
 
 
9485
@end defun
 
9486
 
 
9487
 
 
9488
@node Finding Colors, Changing Colors, Allocating Colors, Colormap Functions
 
9489
@subsection Finding Colors
 
9490
 
 
9491
 
 
9492
A CLX program can ask the X server to return the colors stored in
 
9493
allocated color cells. The server also maintains a dictionary of color
 
9494
names and their associated color values. CLX provides a function to look
 
9495
up the values for common colors by names such as "red", "purple", and so
 
9496
forth. The following paragraphs describe the CLX functions for returning
 
9497
the color values associated with color cells or with color names.
 
9498
 
 
9499
@defun lookup-color colormap name
 
9500
 
 
9501
@table @var
 
9502
@item colormap
 
9503
A @var{colormap}.
 
9504
@item name
 
9505
A @var{stringable} color name.
 
9506
@end table
 
9507
 
 
9508
 
 
9509
Returns the color associated by the X server with the given color
 
9510
@emph{name}. The @emph{name} must contain only ISO Latin-1
 
9511
characters; case is not significant. The first value returned is the
 
9512
closest approximation to the requested color possible on the screen
 
9513
hardware. The second value returned is the true color value for the
 
9514
requested color.
 
9515
 
 
9516
@table @var
 
9517
@item screen-color
 
9518
@itemx exact-color
 
9519
Type @var{color}.
 
9520
@end table
 
9521
 
 
9522
@end defun
 
9523
 
 
9524
 
 
9525
@defun query-colors colormap pixels &key (:result-type 'list)
 
9526
 
 
9527
@table @var
 
9528
@item colormap
 
9529
A @var{colormap}.
 
9530
@item pixels
 
9531
A @var{sequence} of @var{pixel} values.
 
9532
@item :result-type
 
9533
A subtype of @var{sequence} that indicates the type of sequences returned.
 
9534
@end table
 
9535
 
 
9536
 
 
9537
Returns a @var{sequence} of the colors contained in the allocated
 
9538
cells of the @emph{colormap} specified by the given
 
9539
@emph{pixels}. The values returned for unallocated cells are
 
9540
undefined.
 
9541
@table @var
 
9542
@item colors
 
9543
Type @var{sequence} of @var{color}.
 
9544
@end table
 
9545
 
 
9546
@end defun
 
9547
 
 
9548
 
 
9549
@node Changing Colors, Colormap Attributes, Finding Colors, Colormap Functions
 
9550
@subsection Changing Colors
 
9551
 
 
9552
 
 
9553
The following paragraphs describe the CLX functions to change the colors
 
9554
in colormap cells.
 
9555
 
 
9556
@defun store-color colormap pixel color &key (:red-p t) (:green-p t) (:blue-p t)
 
9557
 
 
9558
@table @var
 
9559
@item colormap
 
9560
A @var{colormap}.
 
9561
@item pixel
 
9562
A @var{pixel}.
 
9563
@item color
 
9564
A color @var{object} or a @var{stringable} containing a color name.
 
9565
@item :red-p
 
9566
@itemx :green-p
 
9567
@itemx :blue-p
 
9568
@var{boolean} values indicating which color components to
 
9569
store.
 
9570
@end table
 
9571
 
 
9572
Changes the contents of the @emph{colormap} cell indexed by the
 
9573
@emph{pixel}. Components of the given @emph{color} are stored in the
 
9574
cell. The @var{:red-p}, @var{:green-p}, and @var{:blue-p}
 
9575
arguments indicate which components of the given @emph{color} are
 
9576
stored.
 
9577
 
 
9578
The @emph{color} can be either a @var{color} object or a
 
9579
@var{stringable} containing a color name. If a color name is given,
 
9580
a corresponding color value is looked up (see @var{lookup-color})
 
9581
and used.  Color name strings must contain only ISO Latin-1
 
9582
characters; case is not significant.
 
9583
 
 
9584
 
 
9585
@end defun
 
9586
 
 
9587
 
 
9588
@defun store-colors colormap pixel-colors &key (:red-p t) (:green-p t) (:blue-p t)
 
9589
 
 
9590
@table @var
 
9591
@item colormap
 
9592
A @var{colormap}.
 
9593
@item pixel-colors
 
9594
A list of the form (@{@emph{pixel color}@}*).
 
9595
@item :red-p
 
9596
@itemx :green-p
 
9597
@itemx :blue-p
 
9598
@var{boolean} values indicating which color components to
 
9599
store.
 
9600
@end table
 
9601
 
 
9602
Changes the contents of multiple @emph{colormap}
 
9603
cells. @emph{pixel-colors} is a list of the form (@{ @emph{pixel
 
9604
color}@}*), indicating a set of pixel values and the colors to store
 
9605
in the corresponding cells. The @var{:red-p}, @var{:green-p}, and
 
9606
@var{:blue-p} arguments indicate which components of the given colors
 
9607
are stored.
 
9608
 
 
9609
Each color can be either a @var{color} object or a
 
9610
@var{stringable} containing a color name. If a color name is given,
 
9611
a corresponding color value is looked up (see @var{lookup-color})
 
9612
and used.  Color name strings must contain only ISO Latin-1
 
9613
characters; case is not significant.
 
9614
 
 
9615
 
 
9616
@end defun
 
9617
 
 
9618
 
 
9619
@node Colormap Attributes,  , Changing Colors, Colormap Functions
 
9620
@subsection Colormap Attributes
 
9621
 
 
9622
 
 
9623
The complete set of colormap attributes is discussed in the following
 
9624
paragraphs.
 
9625
 
 
9626
@defun colormap-display colormap
 
9627
 
 
9628
@table @var
 
9629
@item colormap
 
9630
A @var{colormap}.
 
9631
@end table
 
9632
 
 
9633
 
 
9634
Returns the @var{display} object associated with the specified
 
9635
@emph{colormap}.
 
9636
@table @var
 
9637
@item display
 
9638
Type @var{display}.
 
9639
@end table
 
9640
 
 
9641
@end defun
 
9642
 
 
9643
 
 
9644
@defun colormap-equal colormap-1 colormap-2
 
9645
 
 
9646
@table @var
 
9647
@item colormap-1
 
9648
@itemx colormap-2
 
9649
A @var{colormap}.
 
9650
@end table
 
9651
 
 
9652
Returns true if the two arguments refer to the same server resource
 
9653
and @var{nil} if they do not.
 
9654
 
 
9655
 
 
9656
@end defun
 
9657
 
 
9658
 
 
9659
@defun colormap-id colormap
 
9660
 
 
9661
@table @var
 
9662
@item colormap
 
9663
A @var{colormap}.
 
9664
@end table
 
9665
 
 
9666
Returns the unique ID assigned to the specified @emph{colormap}.
 
9667
 
 
9668
@table @var
 
9669
@item id
 
9670
Type @var{resource-id}.
 
9671
@end table
 
9672
 
 
9673
@end defun
 
9674
 
 
9675
 
 
9676
@defun colormap-p colormap
 
9677
 
 
9678
Returns non-@var{nil} if the argument is a @var{colormap} and
 
9679
@var{nil} otherwise.
 
9680
 
 
9681
@table @var
 
9682
@item map-p
 
9683
Type @var{boolean}.
 
9684
@end table
 
9685
 
 
9686
@end defun
 
9687
 
 
9688
@defun colormap-plist colormap
 
9689
 
 
9690
@table @var
 
9691
@item colormap
 
9692
A @var{colormap}.
 
9693
@end table
 
9694
 
 
9695
 
 
9696
 
 
9697
 
 
9698
Returns and (with @code{setf}) sets the property list for the
 
9699
specified @emph{colormap}. This function provides a hook where
 
9700
extensions can add data.
 
9701
 
 
9702
@table @var
 
9703
@item colormap-p
 
9704
Type @var{boolean}.
 
9705
@end table
 
9706
 
 
9707
@end defun
 
9708
 
 
9709
 
 
9710
@node Cursors, Atoms, Colors, Top
 
9711
@chapter Cursors
 
9712
 
 
9713
A @emph{cursor} is a visible shape that appears at the current position
 
9714
of the pointer device. The cursor shape moves with the pointer to
 
9715
provide continuous feedback to the user about the current location of
 
9716
the pointer. Each window can have a cursor attribute that defines the
 
9717
appearance of the pointer cursor when the pointer position lies within
 
9718
the window. See @var{window-cursor}.
 
9719
 
 
9720
A cursor image is composed of a source bitmap, a mask bitmap, a @emph{hot
 
9721
spot}, a foreground color, and a background color. Either 1-bit
 
9722
pixmaps or font glyphs can be used to specify source and mask
 
9723
bitmaps. The source bitmap identifies the foreground and background
 
9724
pixels of the cursor image; the mask bitmap identifies which source
 
9725
pixels are actually drawn. The mask bitmap thus allows a cursor to
 
9726
assume any shape. The hot spot defines the position within the cursor
 
9727
image that is displayed at the pointer position.
 
9728
 
 
9729
In CLX, a cursor is represented by a @var{cursor} object. This section
 
9730
describes the CLX functions to:
 
9731
 
 
9732
@itemize @bullet
 
9733
@item  Create and free cursor objects
 
9734
 
 
9735
@item  Change cursor colors
 
9736
 
 
9737
@item  Inquire the best cursor size
 
9738
 
 
9739
@item  Access cursor attributes
 
9740
@end itemize
 
9741
 
 
9742
@menu
 
9743
* Creating Cursors::
 
9744
* Cursor Functions::
 
9745
* Cursor Attributes::
 
9746
@end menu
 
9747
 
 
9748
@node Creating Cursors, Cursor Functions, Cursors, Cursors
 
9749
@section Creating Cursors
 
9750
 
 
9751
 
 
9752
The following paragraphs describe the CLX functions used to create and
 
9753
free @var{cursor} objects.
 
9754
 
 
9755
@defun create-cursor &key :source :mask :x :y :foreground :background
 
9756
 
 
9757
@table @var
 
9758
@item :source
 
9759
The source pixmap. This argument is required.
 
9760
@item :mask
 
9761
The mask pixmap.
 
9762
@item :x
 
9763
@itemx :y
 
9764
The hot spot position in the @var{:source}. This argument is required.
 
9765
@item :foreground
 
9766
A @var{color} object specifying the foreground color. This argument is required.
 
9767
@item :background
 
9768
A @var{color} object specifying the background color. This argument is required.
 
9769
@end table
 
9770
 
 
9771
 
 
9772
Creates and returns a cursor. @var{:x} and @var{:y} define the
 
9773
position of the hot spot relative to the origin of the
 
9774
@var{:source. :foreground} and @var{:background} colors must be
 
9775
specified, even if the server only has a @var{:static-gray} or
 
9776
@var{:gray-scale} screen. The @var{:source}, @var{:x}, and
 
9777
@var{:y} arguments must also be specified.
 
9778
 
 
9779
The cursor image is drawn by drawing a pixel from the @var{:source}
 
9780
bitmap at every position where the corresponding bit in the
 
9781
@var{:mask} bitmap is 1. If the corresponding @var{:source} bit is
 
9782
1, a pixel is drawn in the @var{:foreground} color; otherwise, a
 
9783
pixel is drawn in the @var{:back-ground} color. If the @var{:mask}
 
9784
is omitted, all @var{:source} pixels are drawn. If given, the
 
9785
@var{:mask} must be the same size as the @var{:source}.
 
9786
 
 
9787
An X server may not be able to support every cursor size. A server
 
9788
is free to modify any component of the cursor to satisfy hardware or
 
9789
software limitations.
 
9790
 
 
9791
The @var{:source} and @var{:mask} can be freed immediately after
 
9792
the cursor is created. Subsequent drawing in the @var{:source} or
 
9793
@var{:mask} pixmap has an undefined effect on the cursor.
 
9794
 
 
9795
@table @var
 
9796
@item cursor
 
9797
Type @var{cursor}.
 
9798
@end table
 
9799
 
 
9800
@end defun
 
9801
 
 
9802
 
 
9803
@defun create-glyph-cursor &key :source-font :source-char :mask-font (:mask-char 0) :foreground :background
 
9804
 
 
9805
@table @var
 
9806
@item :source-font
 
9807
The source font. This is a required argument.
 
9808
@item :source-char
 
9809
An index specifying a glyph in the source font. This is a required argument.
 
9810
@item :mask-font
 
9811
The mask font.
 
9812
@item :mask-char
 
9813
An index specifying a glyph in the mask font.
 
9814
@item :foreground
 
9815
A @var{color} object specifying the foreground color. This is a required argument.
 
9816
@item :background
 
9817
A @var{color} object specifying the background color. This is a required argument.
 
9818
@end table
 
9819
 
 
9820
 
 
9821
Creates and returns a cursor defined by font glyphs. The source
 
9822
bitmap is defined by the @var{:source-font} and
 
9823
@var{:source-char}. The mask bitmap is defined by the
 
9824
@var{:mask-font} and @var{:mask-char}. It is an error if the
 
9825
@var{:source-char} and @var{:mask-char} are not valid indexes for
 
9826
the @var{:source-font} and @var{:mask-font}, respectively. The hot
 
9827
spot position is defined by the "character origin" of the source
 
9828
glyph, that is, the position [- @emph{char-left-bearing},
 
9829
@emph{char-ascent}] relative to the upper left corner of the source
 
9830
glyph bitmap.
 
9831
 
 
9832
Source and mask bits are compared after aligning the character
 
9833
origins of the source and mask glyphs. The source and mask glyphs
 
9834
need not have the same size or character origin position. If the
 
9835
@var{:mask-font} is omitted, all source pixels are drawn.
 
9836
 
 
9837
An X server may not be able to support every cursor size. A server
 
9838
is free to modify any component of the cursor to satisfy hardware or
 
9839
software limitations.
 
9840
 
 
9841
Either of the @var{:source-font} or @var{:mask-font} can be closed
 
9842
after the cursor is created.
 
9843
 
 
9844
@table @var
 
9845
@item cursor
 
9846
Type @var{cursor}.
 
9847
@end table
 
9848
 
 
9849
@end defun
 
9850
 
 
9851
 
 
9852
@defun free-cursor cursor
 
9853
 
 
9854
@table @var
 
9855
@item cursor
 
9856
A @var{cursor} object.
 
9857
@end table
 
9858
 
 
9859
Destroys the @var{cursor} object. Cursor server resources are freed
 
9860
when no other references remain.
 
9861
 
 
9862
 
 
9863
@end defun
 
9864
 
 
9865
 
 
9866
@node Cursor Functions, Cursor Attributes, Creating Cursors, Cursors
 
9867
@section Cursor Functions
 
9868
 
 
9869
 
 
9870
The following paragraphs describe the CLX functions used to operate on
 
9871
@var{cursor} objects.
 
9872
 
 
9873
@defun query-best-cursor width height display
 
9874
 
 
9875
@table @var
 
9876
@item display
 
9877
A @var{display} object.
 
9878
@item width
 
9879
@itemx height
 
9880
The requested cursor size.
 
9881
@end table
 
9882
 
 
9883
Returns the cursor size closest to the requested @emph{width} and
 
9884
@emph{height} that is best suited to the display. The @emph{width}
 
9885
and @emph{height} returned define the largest cursor size supported
 
9886
by the X server. Clients should always be prepared to limit cursor
 
9887
sizes to those supported by the server.
 
9888
 
 
9889
@table @var
 
9890
@item width
 
9891
@itemx height
 
9892
Type @var{card16}.
 
9893
@end table
 
9894
 
 
9895
@end defun
 
9896
 
 
9897
 
 
9898
@defun recolor-cursor cursor foreground background
 
9899
 
 
9900
@table @var
 
9901
@item cursor
 
9902
A @var{cursor} object.
 
9903
@item foreground
 
9904
A @var{color} object specifying the new foreground color.
 
9905
@item background
 
9906
A @var{color} object specifying the new background color.
 
9907
@end table
 
9908
 
 
9909
Changes the color of the specified @emph{cursor}. If the cursor is
 
9910
displayed on a screen, the change is visible immediately.
 
9911
 
 
9912
 
 
9913
@end defun
 
9914
 
 
9915
 
 
9916
@node Cursor Attributes,  , Cursor Functions, Cursors
 
9917
@section Cursor Attributes
 
9918
 
 
9919
 
 
9920
The complete set of cursor attributes is discussed in the following
 
9921
paragraphs.
 
9922
 
 
9923
@defun cursor-display cursor
 
9924
 
 
9925
@table @var
 
9926
@item cursor
 
9927
A @var{cursor} object.
 
9928
@end table
 
9929
 
 
9930
 
 
9931
Returns the @var{display} object associated with the specified
 
9932
@emph{cursor}.
 
9933
 
 
9934
@table @var
 
9935
@item display
 
9936
Type @var{display}.
 
9937
@end table
 
9938
 
 
9939
@end defun
 
9940
 
 
9941
 
 
9942
@defun cursor-equal cursor-1 cursor-2
 
9943
 
 
9944
@table @var
 
9945
@item cursor-1
 
9946
@itemx cursor-2
 
9947
@var{cursor} objects.
 
9948
@end table
 
9949
 
 
9950
Returns true if the two arguments refer to the same server resource
 
9951
and @var{nil} if they do not.
 
9952
 
 
9953
 
 
9954
@end defun
 
9955
 
 
9956
 
 
9957
@defun cursor-id cursor
 
9958
 
 
9959
@table @var
 
9960
@item cursor
 
9961
A @var{cursor} object.
 
9962
@end table
 
9963
 
 
9964
 
 
9965
Returns the unique resource ID that has been assigned to the
 
9966
specified @emph{cursor}.
 
9967
 
 
9968
@table @var
 
9969
@item id
 
9970
Type @var{resource-id.}
 
9971
@end table
 
9972
 
 
9973
@end defun
 
9974
 
 
9975
 
 
9976
@defun cursor-p cursor
 
9977
 
 
9978
@table @var
 
9979
@item cursor-p
 
9980
Type @var{boolean}.
 
9981
@end table
 
9982
 
 
9983
Returns true if the argument is a @var{cursor} object and
 
9984
@var{nil} otherwise.
 
9985
 
 
9986
@end defun
 
9987
 
 
9988
@defun cursor-plist cursor
 
9989
 
 
9990
@table @var
 
9991
@item cursor
 
9992
A @var{cursor} object.
 
9993
@end table
 
9994
 
 
9995
 
 
9996
Returns and (with @code{setf}) sets the property list for the
 
9997
specified @emph{cursor}. This function provides a hook where
 
9998
extensions can add data.
 
9999
 
 
10000
@table @var
 
10001
@item plist
 
10002
A property list.
 
10003
@end table
 
10004
 
 
10005
@end defun
 
10006
 
 
10007
 
 
10008
@node Atoms, Events and Input, Cursors, Top
 
10009
@chapter Atoms, Properties and Selections
 
10010
 
 
10011
@menu
 
10012
* Atoms (Atoms)::
 
10013
* Properties::
 
10014
* Selections::
 
10015
@end menu
 
10016
 
 
10017
@node Atoms (Atoms), Properties, Atoms, Atoms
 
10018
@section Atoms
 
10019
 
 
10020
 
 
10021
In X, an @emph{atom} is a unique ID used as the name for certain server
 
10022
resources -- properties and selections.
 
10023
 
 
10024
In CLX, an atom is represented by a keyword symbol. For convenience, CLX
 
10025
functions also allow atoms to be specified by strings and non-keyword
 
10026
symbols. @var{xatom} is a CLX data type that permits either string or
 
10027
symbol values. A string is equivalent to the @var{xatom} given by
 
10028
(@var{intern} @emph{string} @var{'keyword}). A symbol is equivalent to
 
10029
the @var{xatom} given by ( @var{intern} (@var{symbol-name}
 
10030
@emph{symbol}) @var{'keyword}). The symbol name string of an
 
10031
@var{xatom} must consist only of ISO Latin characters. Note that the
 
10032
case of @var{xatom} strings is important; the @var{xatom} "Atom" is
 
10033
not the same as the @var{xatom} "ATOM".
 
10034
 
 
10035
Certain atoms are already predefined by every X server. Predefined atoms
 
10036
are designed to represent common names that are likely to be useful for
 
10037
many client applications.  Note that these atoms are predefined only in
 
10038
the sense of having @var{xatom} and @var{card29} values, not in the
 
10039
sense of having required semantics. No interpretation is placed on the
 
10040
meaning or use of an atom by the server. The @var{xatom} objects
 
10041
predefined by CLX are listed below.
 
10042
 
 
10043
@multitable @columnfractions 0.3 0.3 0.3
 
10044
@item @var{:arc} @tab @var{:italic_angle} @tab @var{:string}
 
10045
@item @var{:atom} @tab @var{:max_space} @tab @var{:subscript_x}
 
10046
@item @var{:bitmap} @tab @var{:min_space} @tab @var{:subscript_y}
 
10047
@item @var{:cap_height} @tab @var{:norm_space} @tab @var{:superscript_x}
 
10048
@item @var{:cardinal} @tab @var{:notice} @tab @var{:superscript_y}
 
10049
@item @var{:colormap} @tab @var{:pixmap} @tab @var{:underline_position}
 
10050
@item @var{:copyright} @tab @var{:point} @tab @var{:underline_thickness}
 
10051
@item @var{:cursor} @tab @var{:point_size} @tab @var{:visualid}
 
10052
@item @var{:cut_buffer0} @tab @var{:primary} @tab @var{:weight}
 
10053
@item @var{:cut_buffer1} @tab @var{:quad_width} @tab @var{:window}
 
10054
@item @var{:cut_buffer2} @tab @var{:rectangle} @tab @var{:wm_class}
 
10055
@item @var{:cut_buffer3} @tab @var{:resolution} @tab @var{:wm_client_machine}
 
10056
@item @var{:cut_buffer4} @tab @var{:resource_manager} @tab @var{:wm_command}
 
10057
@item @var{:cut_buffer5} @tab @var{:rgb_best_map} @tab @var{:wm_hints}
 
10058
@item @var{:cut_buffer6} @tab @var{:rgb_blue_map} @tab @var{:wm_icon_name}
 
10059
@item @var{:cut_buffer7} @tab @var{:rgb_color_map}@tab @var{:wm_icon_size}
 
10060
@item @var{:drawable} @tab @var{:rgb_default_map} @tab @var{:wm_name}
 
10061
@item @var{:end_space} @tab @var{:rgb_gray_map} @tab @var{:wm_normal_hints}
 
10062
@item @var{:family_name} @tab @var{:rgb_green_map}@tab @var{:wm_size_hints}
 
10063
@item @var{:font} @tab @var{:rgb_red_map} @tab @var{:wm_transient_for}
 
10064
@item @var{:font_name} @tab @var{:secondary} @tab @var{:wm_zoom_hints}
 
10065
@item @var{:full_name} @tab @var{:strikeout_ascent} @tab @var{:x_height}
 
10066
@item @var{:integer} @tab @var{:strikeout_descent} @tab
 
10067
@end multitable
 
10068
 
 
10069
 
 
10070
When creating a new atom, the following conventions should be obeyed in
 
10071
order to minimize the conflict between atom names:
 
10072
 
 
10073
@itemize @bullet
 
10074
@item
 
10075
Symbol names beginning with an underscore should be used for atoms
 
10076
that are private to a particular vendor or organization. An additional
 
10077
prefix should identify the organization.
 
10078
 
 
10079
@item
 
10080
Symbol names beginning with two underscores should be used for atoms
 
10081
that are private to a single application or end user.
 
10082
@end itemize
 
10083
 
 
10084
 
 
10085
CLX provides functions to convert between an @var{xatom} and its
 
10086
corresponding ID integer.  The data type of an atom ID is
 
10087
@var{card29}. The @var{xatom} representation is usually sufficient for
 
10088
most CLX programs. However, it is occasionally useful to be able to
 
10089
convert an atom ID returned in events or properties into its
 
10090
corresponding @var{xatom}.
 
10091
 
 
10092
@defun atom-name display atom-id
 
10093
 
 
10094
@table @var
 
10095
@item display
 
10096
A @var{display} object.
 
10097
@item atom-id
 
10098
A @var{card29}.
 
10099
@end table
 
10100
 
 
10101
Returns the atom keyword for the @emph{atom-id} on the given
 
10102
@emph{display} server.
 
10103
 
 
10104
@table @var
 
10105
@item atom-name
 
10106
Type @var{keyword}.
 
10107
@end table
 
10108
 
 
10109
@end defun
 
10110
 
 
10111
 
 
10112
@defun find-atom display atom-name
 
10113
 
 
10114
@table @var
 
10115
@item display
 
10116
A @var{display} object.
 
10117
@item atom-name
 
10118
An @var{xatom}.
 
10119
@end table
 
10120
 
 
10121
Returns the atom ID for the given @emph{atom-name}, if it exists. If
 
10122
no atom of that name exists for the display server, @var{nil} is
 
10123
returned.
 
10124
 
 
10125
@table @var
 
10126
@item atom-id
 
10127
Type @var{card29} or @var{null}.
 
10128
@end table
 
10129
 
 
10130
@end defun
 
10131
 
 
10132
 
 
10133
@defun intern-atom display atom-name
 
10134
 
 
10135
@table @var
 
10136
@item display
 
10137
A @var{display} object.
 
10138
@item atom-name
 
10139
An @var{xatom}.
 
10140
@end table
 
10141
 
 
10142
Creates an atom with the given name and returns its atom ID. The
 
10143
atom can survive the interning client; it exists until the last
 
10144
server connection has been closed and the server resets itself.
 
10145
 
 
10146
@table @var
 
10147
@item atom-id
 
10148
Type @var{card29} or @var{null}.
 
10149
@end table
 
10150
 
 
10151
@end defun
 
10152
 
 
10153
 
 
10154
@node Properties, Selections, Atoms (Atoms), Atoms
 
10155
@section Properties
 
10156
 
 
10157
 
 
10158
For each window, an X server can record a set of
 
10159
@emph{properties}. Properties are a general mechanism for clients to
 
10160
associate arbitrary data with a window, and for clients to communicate
 
10161
window data to each other via the server. No interpretation is placed on
 
10162
property data by the server itself.
 
10163
 
 
10164
A property consists of a name, a type, a data format, and data. The name
 
10165
of a property is given by an atom. The property type is another atom
 
10166
used to denote the intended interpretation of the property data. The
 
10167
property formats specifies whether the property data should be treated
 
10168
as a set of 8-, 16-, or 32-bit elements. The property format must be
 
10169
specified so that the X server can communicate property data with the
 
10170
correct byte order.
 
10171
 
 
10172
CLX provides functions to:
 
10173
 
 
10174
@itemize @bullet
 
10175
@item  Create or change a property
 
10176
 
 
10177
@item  Return property data
 
10178
 
 
10179
@item  List window properties
 
10180
 
 
10181
@item  Delete a property
 
10182
@end itemize
 
10183
 
 
10184
 
 
10185
@defun change-property window property data type format &key (:mode :replace) (:start 0) :end :transform
 
10186
 
 
10187
@table @var
 
10188
@item window
 
10189
A @var{window}.
 
10190
@item property
 
10191
A property name @var{xatom}.
 
10192
@item data
 
10193
A sequence of property data elements.
 
10194
@item type
 
10195
The property type @var{xatom}.
 
10196
@item format
 
10197
One of 8, 16, or 32.
 
10198
@item :mode
 
10199
One of @var{:replace}, @var{:append}, or @var{:prepend}.
 
10200
@item :start
 
10201
@itemx :end
 
10202
Specify the subsequence of previous data replaced when @var{:mode} is @var{:replace}.
 
10203
@item :transform
 
10204
A function that transforms each data element into a data value to store.
 
10205
@end table
 
10206
 
 
10207
Creates a new window property or changes an existing property. A
 
10208
@var{:property-notify} event is generated for the @emph{window}.
 
10209
 
 
10210
If the @var{:mode} is @var{:replace}, the new @emph{data},
 
10211
@emph{type}, and @emph{format} replace any previous values.  The
 
10212
subsequence of previous data elements that are replaced is defined
 
10213
by the @var{:start} and @var{:end} indexes.
 
10214
 
 
10215
If the @var{:mode} is @var{:prepend} or @var{:append}, no
 
10216
previous data is changed, but the new @emph{data} is added at the
 
10217
beginning or the end, respectively. For these modes, if the
 
10218
@emph{property} already exists, the new @emph{type} and
 
10219
@emph{format} must match the previous values.
 
10220
 
 
10221
The @var{:transform}, if given, is a function used to compute the
 
10222
actual property data stored.  The @var{:transform}, which must
 
10223
accept a single data element and return a single transformed data
 
10224
element, is called for each data element. If the @emph{data} is a
 
10225
string, the default @var{:transform} function transforms each
 
10226
character into its ASCII code; otherwise, the default is to store
 
10227
the @emph{data} unchanged.
 
10228
 
 
10229
 
 
10230
@end defun
 
10231
 
 
10232
 
 
10233
@defun delete-property window property
 
10234
 
 
10235
@table @var
 
10236
@item window
 
10237
A @var{window}.
 
10238
@item property
 
10239
A property name @var{xatom}.
 
10240
@end table
 
10241
 
 
10242
Deletes the @emph{window property}. If the @emph{property} already
 
10243
exists, a @var{:property-notify} event is generated for the
 
10244
@emph{window}.
 
10245
 
 
10246
 
 
10247
@end defun
 
10248
 
 
10249
 
 
10250
@defun get-property window property &key :type (:start 0) :end :delete-p (:result-type 'list) :transform
 
10251
@anchor{get-property}
 
10252
 
 
10253
@table @var
 
10254
@item window
 
10255
A @var{window}.
 
10256
@item property
 
10257
A property name @var{xatom}.
 
10258
@item :type
 
10259
The requested type @var{xatom} or @var{nil}.
 
10260
@item :start
 
10261
@itemx :end
 
10262
Specify the subsequence of property @emph{data} returned.
 
10263
@item :transform
 
10264
A function that transforms each data element into a data value to return.
 
10265
@item :delete-p
 
10266
If true, the existing @emph{property} can be deleted.
 
10267
@item :result-type
 
10268
The t@emph{ype} of data sequence to return. Default is @var{'list}.
 
10269
@end table
 
10270
 
 
10271
Returns a subsequence of the data for the window property. The
 
10272
@var{:start} and @var{:end} indexes specify the property
 
10273
@emph{data} elements returned. The @var{:transform} function is
 
10274
called for elements of the specified subsequence to compute the
 
10275
@emph{data} sequence returned. The property @emph{type} and
 
10276
@emph{format} are also returned. The final return value gives the
 
10277
actual number of data bytes (not elements) following the last data
 
10278
element returned.
 
10279
 
 
10280
If the @emph{property} does not exist, the returned @emph{data} and
 
10281
@emph{type} are @var{nil} and the returned @emph{format} and
 
10282
@emph{bytes-after} are zero.
 
10283
 
 
10284
If the given @var{:type} is non-@var{nil} but does not match the
 
10285
actual property type, then the @emph{data} returned is @var{nil},
 
10286
the @emph{type} and @emph{format} returned give the actual property
 
10287
values, and the @emph{bytes-after} returned gives the total number
 
10288
of bytes (not elements) in the property data.
 
10289
 
 
10290
If the given @var{:type} is @var{nil} or if it matches the actual
 
10291
property type, then:
 
10292
 
 
10293
@itemize @bullet
 
10294
@item
 
10295
The @emph{data} returned is the transformed subsequence of the
 
10296
property data.
 
10297
 
 
10298
@item
 
10299
The @emph{type} and @emph{format} returned give the actual
 
10300
property values.
 
10301
 
 
10302
@item
 
10303
The @emph{bytes-after} returned gives the actual number of data
 
10304
bytes (not elements) following the last data element returned.
 
10305
@end itemize
 
10306
 
 
10307
 
 
10308
In this case, the @var{:delete-p} argument is also examined. If
 
10309
@var{:delete-p} is true and @emph{bytes-after} is zero, the
 
10310
property is deleted and a @var{:property-notify} event is generated
 
10311
for the @emph{window}.
 
10312
 
 
10313
@table @var
 
10314
@item data
 
10315
Type @var{sequence}.
 
10316
@item type
 
10317
Type @var{xatom}.
 
10318
@item format
 
10319
Type (@var{member 8 16 32}).
 
10320
@item bytes-after
 
10321
Type @var{card32}.
 
10322
@end table
 
10323
 
 
10324
@end defun
 
10325
 
 
10326
 
 
10327
@defun list-properties window &key (:result-type 'list)
 
10328
 
 
10329
@table @var
 
10330
@item window
 
10331
A @var{window}.
 
10332
@item :result-type
 
10333
The type of sequence to return. Default is @var{'list}.
 
10334
@end table
 
10335
 
 
10336
 
 
10337
Returns a sequence containing the names of all @emph{window
 
10338
properties}.
 
10339
@table @var
 
10340
@item properties
 
10341
Type @var{sequence} of @var{keyword}.
 
10342
@end table
 
10343
 
 
10344
@end defun
 
10345
 
 
10346
 
 
10347
@defun rotate-properties window properties &optional (delta 1)
 
10348
 
 
10349
@table @var
 
10350
@item window
 
10351
A @var{window}.
 
10352
@item properties
 
10353
A sequence of @var{xatom} values.
 
10354
@item delta
 
10355
The index interval between source and destination elements of @emph{properties}.
 
10356
@end table
 
10357
 
 
10358
Rotates the values of the given @emph{window properties}. The value
 
10359
of property @emph{i} in the given sequence is changed to the value
 
10360
of the property at index (@var{mod} (+ @emph{i delta})
 
10361
(@var{length} @emph{properties})). This function operates much like
 
10362
the @var{rotatef} macro in Common Lisp.
 
10363
 
 
10364
If (@var{mod} @emph{delta} (@var{length} @emph{properties})) is
 
10365
non-zero, a @var{:property-notify} event is generated on the window
 
10366
for each property, in the same order as they appear in the
 
10367
@emph{properties} sequence.
 
10368
 
 
10369
 
 
10370
@end defun
 
10371
 
 
10372
 
 
10373
@node Selections,  , Properties, Atoms
 
10374
@section Selections
 
10375
 
 
10376
 
 
10377
A selection is an atom used to identify data that can be shared among
 
10378
all client programs connected to an X server. Unlike properties, the
 
10379
data represented by a selection is stored by some client program, not by
 
10380
the server.
 
10381
 
 
10382
The data named by a selection is associated with a client window, which
 
10383
is referred to as the @emph{selection owner}. The server always knows
 
10384
which window is the owner of a selection.  Selections can be created
 
10385
freely by clients using @var{intern-atom} to create an atom. CLX
 
10386
provides functions to inquire or change the owner of a selection and to
 
10387
@emph{convert} a selection.
 
10388
 
 
10389
Conversion is the key to the use of selections for inter-client
 
10390
communication. Suppose Client A wants to paste the contents of the data
 
10391
named by selection @emph{S} into his window @emph{WA}. Client A calls
 
10392
@var{convert-selection} on selection atom @emph{S}, sending a
 
10393
conversion request to the server. The server, in turn, sends a
 
10394
@var{:selection-request} event to the current owner of @emph{S}, which
 
10395
is window @emph{WB} belonging to Client B. The @var{:selection-request}
 
10396
event contains the @emph{requestor} window (@emph{WA}), the selection
 
10397
atom (@emph{S}), an atom identifying a requested data type, and the name
 
10398
of a property of @emph{WA} into which the value of @emph{S} will be
 
10399
stored.
 
10400
 
 
10401
Since @emph{WB} is the owner of @emph{S}, it must be associated with the
 
10402
data defined by Client B as the value of @emph{S}. When @emph{WB} gets
 
10403
the @var{:selection-request} event, Client B is expected to convert the
 
10404
value of @emph{S} to the requested data type (if possible) and store the
 
10405
converted value in the given requestor property. Client B is then
 
10406
expected to send a @var{:selection-notify} event to the requestor
 
10407
window @emph{WA}, informing the requestor that the converted value for
 
10408
@emph{S} is ready. Upon receiving the @var{:selection-notify} event,
 
10409
Client A can call @var{get-property} to retrieve the converted value
 
10410
and to paste it into @emph{WA}.
 
10411
 
 
10412
@var{NOTE:} Clients using selections must always be prepared to handle
 
10413
@var{:selection-request} events and/or @var{:selection-notify}
 
10414
events. There is no way for a client to ask not to receive these types
 
10415
of events.
 
10416
 
 
10417
Type atoms used in selection conversion can represent arbitrary
 
10418
client-defined interpretations of the selection data. For example, if
 
10419
the value of selection @emph{S} is a text string, Client A might request
 
10420
its typeface by requesting conversion to the @var{:font} type. A type
 
10421
@var{atom} can also represent a request to the selection owner to
 
10422
perform some action as a side-effect of conversion (for example,
 
10423
@var{:delete}). Some of the predefined atoms of an X server are
 
10424
intended to be used as selection types (for example, @var{:colormap},
 
10425
@var{:bitmap}, @var{:string}, and so forth) However, X does not impose
 
10426
any requirements on the interpretation of type atoms.
 
10427
 
 
10428
When multiple clients negotiate for ownership of a selection, certain
 
10429
race conditions might be possible. For example, two clients might each
 
10430
receive a user command to assert ownership of the @var{:primary}
 
10431
selection, but the order in which the server processes these client
 
10432
requests is unpredictable. As a result, the ownership request initiated
 
10433
most recently by the user might be incorrectly overridden by the other
 
10434
earlier ownership request. To prevent such anomalies, the server records
 
10435
a @emph{last-changed} timestamp for each change of selection ownership.
 
10436
 
 
10437
Although inter-client communication via selections is rather complex, it
 
10438
offers important benefits. Since selection communication is mediated by
 
10439
an X server, clients can share data even though they are running on
 
10440
different hosts and using different networking protocols. Data storage
 
10441
and conversion is distributed among clients so that the server is not
 
10442
required to provide all possible data types or to store multiple forms
 
10443
of selection data.
 
10444
 
 
10445
Certain predefined atoms are used as standard selections, as described
 
10446
in the X11 Inter-client Communications Conventions Manual. Some of the
 
10447
standard selections covered by these conventions are:
 
10448
 
 
10449
@table @var
 
10450
@item :primary
 
10451
The @emph{primary selection}. The main vehicle for inter-client cut
 
10452
and paste operations.
 
10453
@item :secondary
 
10454
The @emph{secondary selection}. In some environments, clients can use
 
10455
this as an auxiliary to @var{:primary}.
 
10456
@item :clipboard
 
10457
Analogous to akill ring. Represents the most recently deleted data
 
10458
item.
 
10459
@end table
 
10460
 
 
10461
 
 
10462
@defun convert-selection selection type requestor &optional property time
 
10463
 
 
10464
@table @var
 
10465
@item selection
 
10466
The @var{xatom} for the selection name.
 
10467
@item type
 
10468
The @var{xatom} for the requested data type.
 
10469
@item requestor
 
10470
The @var{window} to receive the converted @emph{selection} value.
 
10471
@item property
 
10472
The @var{xatom} for the requestor property to receive the converted value.
 
10473
@item time
 
10474
A @var{timestamp}.
 
10475
@end table
 
10476
 
 
10477
Requests that the value of the @emph{selection} be converted to the
 
10478
specified @emph{type} and stored in the given @emph{property} of the
 
10479
@emph{requestor} window.
 
10480
 
 
10481
If the @emph{selection} has an owner, the X server sends a
 
10482
@var{:selection-request} event to the owner window. Otherwise, if
 
10483
no owner exists, the server generates on the requestor a
 
10484
@var{:selection-notify} event containing a @var{nil}
 
10485
@emph{property} atom.
 
10486
 
 
10487
The given @emph{property} specifies the requestor property that will
 
10488
receive the converted value. If the @emph{property} is omitted, the
 
10489
@emph{selection} owner will define a property to use. The
 
10490
@emph{time} furnishes a timestamp representing the time of the
 
10491
conversion request; by default, the current server time is used.
 
10492
 
 
10493
@var{NOTE:} Standard conventions for inter-client communication
 
10494
require that both the requestor property and the time must be
 
10495
specified. If possible, the time should be the time of a user event
 
10496
which initiated the conversion. Alternatively, a timestamp can be
 
10497
obtained by calling @var{change-property} to append zero-length
 
10498
data to some property; the timestamp in the resulting
 
10499
@var{:property-notify} event can then be used.
 
10500
 
 
10501
 
 
10502
@end defun
 
10503
 
 
10504
 
 
10505
@defun selection-owner display selection &optional time
 
10506
 
 
10507
@table @var
 
10508
@item display
 
10509
A @var{display}.
 
10510
@item selection
 
10511
The @var{xatom} for the selection name.
 
10512
@item time
 
10513
A @var{timestamp}.
 
10514
@end table
 
10515
 
 
10516
 
 
10517
Returns and (with @code{setf}) changes the owner and the
 
10518
last-changed @emph{time} for the @emph{selection}. If the owner is
 
10519
@var{nil}, no owner for the @emph{selection} exists. When the owner
 
10520
window for a @emph{selection} is destroyed, the @emph{selection}
 
10521
owner is set to @var{nil} without affecting the last-changed
 
10522
@emph{time}.
 
10523
 
 
10524
The @emph{time} argument is used only when changing the
 
10525
@emph{selection} owner. If the @emph{time} is @var{nil}, the
 
10526
current server time is used. If the @emph{time} is earlier than the
 
10527
current last-changed time of the @emph{selection} or if the
 
10528
@emph{time} is later than the current server time, the owner is not
 
10529
changed. Therefore, a client should always confirm successful change
 
10530
of ownership by immediately calling @var{selection-owner}. If the
 
10531
change in ownership is successful, the last-changed time of the
 
10532
@emph{selection} is set to the specified @emph{time}.
 
10533
 
 
10534
If the change in ownership is successful and the new owner is
 
10535
different from the previous owner, and if the previous owner is not
 
10536
@var{nil}, a @var{:selection-clear} event is generated for the
 
10537
previous owner window.
 
10538
 
 
10539
@var{NOTE:} Standard conventions for inter-client communication
 
10540
require that a non-nil time must be specified. If possible, the time
 
10541
should be the time of a user event which initiated the change of
 
10542
ownership. Alternatively, a timestamp can be obtained by calling
 
10543
change-property to append zero-length data to some property; the
 
10544
timestamp in the resulting @var{:property-notify} event can then be
 
10545
used.
 
10546
@table @var
 
10547
@item owner
 
10548
Type @var{window} or @var{null}.
 
10549
@end table
 
10550
 
 
10551
@end defun
 
10552
 
 
10553
 
 
10554
@node Events and Input, Resources, Atoms, Top
 
10555
@chapter Events and Input
 
10556
 
 
10557
A client application uses CLX functions to send @emph{requests} to an X
 
10558
server over a display connection returned by the @var{open-display}
 
10559
function. In return, the X server sends back @emph{replies} and
 
10560
@emph{events}. Replies are synchronized with specific requests and
 
10561
return requested server information. Events typically occur
 
10562
asynchronously. Device events are generated by user input from both the
 
10563
keyboard and pointer devices. Other events are side-effects of the
 
10564
requests sent by CLX functions. The types of events returned by an X
 
10565
server are summarized below.
 
10566
 
 
10567
Device Events
 
10568
 
 
10569
@table @asis
 
10570
@item Keyboard
 
10571
@var{:key-press} @var{:key-release}
 
10572
@item Pointer
 
10573
@var{:button-press}
 
10574
@var{:button-release}
 
10575
@var{:enter-notify}
 
10576
@var{:leave-notify}
 
10577
@var{:motion-notify}
 
10578
@end table
 
10579
 
 
10580
Side-Effect Events
 
10581
 
 
10582
@table @asis
 
10583
@item Client communication
 
10584
@var{:client-message}
 
10585
@var{:property-notify}
 
10586
@var{:selection-clear}
 
10587
@var{:selection-notify}
 
10588
@var{:selection-request}
 
10589
@item Color map state
 
10590
@var{:colormap-notify}
 
10591
 
 
10592
@item Exposure
 
10593
@var{:exposure}
 
10594
@var{:graphics-exposure}
 
10595
@var{:no-exposure}
 
10596
 
 
10597
@item Input focus
 
10598
@var{:focus-in}
 
10599
@var{:focus-out}
 
10600
 
 
10601
@item Keyboard and pointer state
 
10602
@var{:keymap-notify}
 
10603
@var{:mapping-notify}
 
10604
 
 
10605
@item Structure control
 
10606
@var{:circulate-request}
 
10607
@var{:configure-request}
 
10608
@var{:map-request}
 
10609
 
 
10610
@item Window state
 
10611
@var{:resize-request}
 
10612
@var{:circulate-notify}
 
10613
@var{:configure-notify}
 
10614
@var{:create-notify}
 
10615
@var{:destroy-notify}
 
10616
@var{:gravity-notify}
 
10617
@var{:map-notify}
 
10618
@var{:reparent-notify}
 
10619
@var{:unmap-notify}
 
10620
@var{:visibility-notify}
 
10621
@end table
 
10622
 
 
10623
Client programs can override the server's normal distribution of events
 
10624
by@emph{ grabbing} the pointer or the keyboard. Grabbing causes events
 
10625
from the pointer or keyboard device to be reported to a single specified
 
10626
window, rather than to their ordinary destinations. It can also cause
 
10627
the server to @emph{freeze} the grabbed device, sending queued events
 
10628
only when explicitly requested by the grabbing client. Two kinds of
 
10629
grabs are possible:
 
10630
@itemize @bullet
 
10631
 
 
10632
@item  Active -- Events are immediately grabbed.
 
10633
 
 
10634
@item  Passive -- Events are grabbed later, as soon as a specified device event occurs.
 
10635
@end itemize
 
10636
 
 
10637
Grabbing an input device is performed rarely and usually only by special
 
10638
clients, such as window managers.
 
10639
 
 
10640
This section describes the CLX functions used to:
 
10641
@itemize @bullet
 
10642
 
 
10643
@item  Select events (@pxref{Selecting Events})
 
10644
 
 
10645
@item  Process an event on the event queue (@pxref{Processing Events})
 
10646
 
 
10647
@item  Manage the event queue (@pxref{Managing the Event Queue})
 
10648
 
 
10649
@item  Send events to other applications (@pxref{Sending Events})
 
10650
 
 
10651
@item  Read and change the pointer position (@pxref{Pointer Position})
 
10652
 
 
10653
@item  Manage the keyboard input focus (@pxref{Managing Input Focus})
 
10654
 
 
10655
@item  Grab pointer and keyboard events (@pxref{Grabbing the Pointer})
 
10656
 
 
10657
@item  Release queued events (@pxref{Releasing Queued Events})
 
10658
@end itemize
 
10659
 
 
10660
This section also contains a detailed description of the content of each type of event.
 
10661
 
 
10662
@menu
 
10663
* Selecting Events::
 
10664
* Processing Events::
 
10665
* Managing the Event Queue::
 
10666
* Sending Events::
 
10667
* Pointer Position::
 
10668
* Managing Input Focus::
 
10669
* Grabbing the Pointer::
 
10670
* Grabbing a Button::
 
10671
* Grabbing the Keyboard::
 
10672
* Grabbing a Key::
 
10673
* Event Types::
 
10674
* Releasing Queued Events::
 
10675
@end menu
 
10676
 
 
10677
@node Selecting Events, Processing Events, Events and Input, Events and Input
 
10678
@section Selecting Events
 
10679
 
 
10680
 
 
10681
A client @emph{selects} which types of events it receives from a
 
10682
specific window. The window event-mask attribute, set by the client,
 
10683
determines which event types are selected (see @var{window-event-mask}
 
10684
in @ref{Window Attributes}). Most types of events are received
 
10685
by a client only if they are selected for some window.
 
10686
 
 
10687
In the X protocol, an event-mask is represented as a bit string. CLX
 
10688
also allows an event mask to be defined by a list of
 
10689
@var{event-mask-class} keywords. The functions @var{make-event-keys}
 
10690
and @var{make-event-mask} can be used to convert between these two
 
10691
forms of an event-mask. In general, including an @var{event-mask-class}
 
10692
keyword in an event-mask causes one or more related event types to be
 
10693
selected. The following table describes the event types selected by each
 
10694
@var{event-mask-class} keyword.
 
10695
 
 
10696
@multitable @columnfractions 0.5 0.5
 
10697
@item Event Mask Keyword @tab Event Types Selected
 
10698
@item @var{:button-1-motion}
 
10699
@tab @var{:motion-notify} when @var{:button-1} is down
 
10700
@item @var{:button-2-motion}
 
10701
@tab @var{:motion-notify} when @var{:button-2} is down
 
10702
@item @var{:button-3-motion}
 
10703
@tab @var{:motion-notify} when @var{:button-3} is down
 
10704
@item @var{:button-4-motion}
 
10705
@tab @var{:motion-notify} when @var{:button-4} is down
 
10706
@item @var{:button-5-motion}
 
10707
@tab @var{:motion-notify} when @var{:button-5} is down
 
10708
@item @var{:button-motion}
 
10709
@tab @var{:motion-notify} when any pointer button is down
 
10710
@item @var{:button-press}
 
10711
@tab @var{:button-press}
 
10712
@item @var{:button-release}
 
10713
@tab @var{:button-release}
 
10714
@item @var{:colormap-change}
 
10715
@tab @var{:colormap-notify}
 
10716
@item @var{:enter-window}
 
10717
@tab @var{:enter-notify}
 
10718
@item @var{:exposure}
 
10719
@tab @var{:exposure}
 
10720
@item @var{:focus-change}
 
10721
@tab @var{:focus-in} @var{:focus-out}
 
10722
@item @var{:key-press}
 
10723
@tab @var{:key-press}
 
10724
@item @var{:key-release}
 
10725
@tab @var{:key-release}
 
10726
@item @var{:keymap-state}
 
10727
@tab @var{:keymap-notify}
 
10728
@item @var{:leave-window}
 
10729
@tab @var{:leave-notify}
 
10730
@item @var{:owner-grab-button}
 
10731
@tab Pointer events while button is grabbed
 
10732
@item @var{:pointer-motion}
 
10733
@tab @var{:motion-notify}
 
10734
@item @var{:pointer-motion-hint}
 
10735
@tab Single @var{:motion-notify} only
 
10736
@item @var{:property-change}
 
10737
@tab @var{:property-notify}
 
10738
@item @var{:resize-redirect}
 
10739
@tab @var{:resize-request}
 
10740
@item @var{:structure-notify}
 
10741
@tab @var{:circulate-notify} @var{:configure-notify} @var{:destroy-notify} @var{:gravity-notify} @var{:map-notify} @var{:reparent-notify} @var{:unmap-notify}
 
10742
@item @var{:substructure-redirect}
 
10743
@tab @var{:circulate-request} @var{:configure-request} @var{:map-request}
 
10744
@item @var{:visibility-change}
 
10745
@tab @var{:visibility-notify}
 
10746
@end multitable
 
10747
 
 
10748
 
 
10749
Some types of events do not have to be selected to be received and
 
10750
therefore are not represented in an event-mask. For example, the
 
10751
@var{copy-plane} and @var{copy-area} functions cause
 
10752
@var{:graphics-exposure} and @var{:no-exposure} events to be reported,
 
10753
unless exposures are turned @var{:off} in the graphics context (see
 
10754
@var{copy-area} and @var{copy-plane} in @ref{Area and Plane Operations},
 
10755
and @var{gcontext-exposures} in paragraph 5.4.6, Exposures).  Also, @var{:selection-clear}, @var{:selection-request},
 
10756
@var{:selection-notify} and @var{:client-message} events can be
 
10757
received at any time, but they are generally sent only to clients using
 
10758
selections (@pxref{Client Communications Events}). @var{:mapping-notify} is always sent to clients when the
 
10759
keyboard mapping is changed.
 
10760
 
 
10761
Any client can select events for any window. A window maintains a
 
10762
separate event-mask for each interested client. In general, multiple
 
10763
clients can select for the same events on a window. After the X server
 
10764
generates an event, it sends it to all clients which selected
 
10765
it. However, the following restrictions apply to sharing window events
 
10766
among multiple clients. For a given window:
 
10767
@itemize @bullet
 
10768
 
 
10769
@item  Only one client at a time can include @var{:substructure-redirect} in its event-mask
 
10770
 
 
10771
@item  Only one client at a time can can include @var{:button-press} in its event-mask
 
10772
 
 
10773
@item  Only one client at a time can include @var{:resize-redirect} in its event-mask
 
10774
@end itemize
 
10775
 
 
10776
@node Processing Events, Managing the Event Queue, Selecting Events, Events and Input
 
10777
@section Processing Events
 
10778
 
 
10779
 
 
10780
Events received by a CLX client are stored in an @emph{event queue}
 
10781
until they are read and processed. Events are processed by @emph{handler
 
10782
functions}.
 
10783
 
 
10784
@defun handler-function &rest event-slots &key :display :event-key :send-event-p &allow-other-keys
 
10785
 
 
10786
@table @var
 
10787
@item :display
 
10788
A @var{display} for the connection that returned the event.
 
10789
@item :event-key
 
10790
An @var{event-key} keyword specifying the event type.
 
10791
@item :send-event-p
 
10792
If true, the event was sent from another application using the
 
10793
@var{send-event} function.
 
10794
@end table
 
10795
 
 
10796
 
 
10797
The arguments to a handler function are keyword-value pairs that
 
10798
describe the contents of an event. The actual @emph{event-slots}
 
10799
passed depend on the event type, except that @var{:display},
 
10800
@var{:event-key}, and @var{:send-event-p} are given for all event
 
10801
types. The keyword symbols used for each event type are event slot
 
10802
names defined by the @var{declare-event} macro and are described in
 
10803
@ref{Declaring Event Types}.
 
10804
 
 
10805
If a handler returns non-@var{nil}, the event is considered
 
10806
@emph{processed} and can be removed from the event queue. Otherwise,
 
10807
if a handler function returns @var{nil}, the event can remain in
 
10808
the event queue for later processing.
 
10809
@table @var
 
10810
@item handled-p
 
10811
Type @var{boolean}.
 
10812
@end table
 
10813
 
 
10814
@end defun
 
10815
 
 
10816
 
 
10817
@defun process-event display &key :handler :timeout :peek-p :discard-p (:force-output-p t)
 
10818
 
 
10819
@table @var
 
10820
@item display
 
10821
A @var{display}.
 
10822
@item :handler
 
10823
A handler function or a sequence of handler functions.
 
10824
@item :timeout
 
10825
Specifies the timeout delay in seconds.
 
10826
@item :peek-p
 
10827
If @var{nil}, events are removed from the event queue after processing.
 
10828
@item :discard-p
 
10829
If true, unprocessed events are discarded.
 
10830
@item :force-output-p
 
10831
If true, buffered output requests are sent.
 
10832
@end table
 
10833
 
 
10834
 
 
10835
Invokes @var{:handler} on each queued event until @var{:handler}
 
10836
returns non-@var{nil}. Then, the non-@var{nil :handler} value is
 
10837
returned by @var{process-event}. If @var{:handler} returns
 
10838
@var{nil} for each event in the event queue, @var{process-event}
 
10839
waits for another event to arrive. If timeout is non-@var{nil} and
 
10840
no event arrives within the specified timeout interval (given in
 
10841
seconds), @var{process-event} returns @var{nil}; if timeout is
 
10842
@var{nil}, @var{process-event} will not return until
 
10843
@var{:handler} returns non-@var{nil}. @var{process-event} may
 
10844
wait only once on network data, and therefore timeout prematurely.
 
10845
 
 
10846
If @var{:force-output-p} is true, @var{process-event} first
 
10847
invokes @var{display-force-output} to send any buffered
 
10848
requests. If @var{:peek-p} is true, a processed event is not
 
10849
removed from the queue. If @var{:discard-p} is true, unprocessed
 
10850
events are removed from the queue; otherwise, unprocessed events are
 
10851
left in place.
 
10852
 
 
10853
If @var{:handler} is a sequence, it is expected to contain handler
 
10854
functions for each event type.  The sequence index of the handler
 
10855
function for a particular event type is given by ( @var{position
 
10856
event-key *event-key-vector*}).
 
10857
@table @var
 
10858
@item handled-p
 
10859
Type @var{boolean}.
 
10860
@end table
 
10861
 
 
10862
@end defun
 
10863
 
 
10864
 
 
10865
@defmac event-case display &key :timeout :peek-p :discard-p (:force-output-p t) &body clauses
 
10866
@anchor{event-case}
 
10867
 
 
10868
@table @var
 
10869
@item display
 
10870
A @var{display}.
 
10871
@item :handler
 
10872
A handler function or a sequence of handler functions.
 
10873
@item :timeout
 
10874
Specifies the timeout delay, in seconds.
 
10875
@item :peek-p
 
10876
If @var{nil}, events are removed from the event queue after processing.
 
10877
@item :discard-p
 
10878
If true, unprocessed events are discarded.
 
10879
@item :force-output-p
 
10880
If true, buffered output requests are sent.
 
10881
@item clauses
 
10882
Code to process specified event types.
 
10883
@end table
 
10884
 
 
10885
Executes the matching clause for each queued event until a clause
 
10886
returns non-@var{nil}. The non-@var{nil} clause value is then
 
10887
returned. Each of the clauses is a list of the form
 
10888
(@emph{event-match} [@emph{event-slots}] &rest @emph{forms}),
 
10889
where:
 
10890
@itemize @bullet
 
10891
 
 
10892
@item
 
10893
@emph{event-match} -- Either an @var{event-key}, a list of
 
10894
@var{event-keys}, otherwise, or @var{t}. It is an error for the
 
10895
same key to appear in more than one clause.
 
10896
 
 
10897
@item
 
10898
@emph{event-slots} -- If given, a list of (non-keyword) event slot
 
10899
symbols defined for the specified event type(s). @xref{Declaring Event Types}.
 
10900
 
 
10901
@item
 
10902
@emph{forms} -- A list of forms that process the specified event
 
10903
type(s). The value of the last form is the value returned by the
 
10904
clause.
 
10905
@end itemize
 
10906
 
 
10907
A clause matches an event if the @var{event-key} is equal to or a
 
10908
member of the @emph{event-match}, or if the @emph{event-match} is
 
10909
@var{t} or @var{otherwise}. If no @var{t} or @var{otherwise}
 
10910
clause appears, it is equivalent to having a final clause that
 
10911
returns @var{nil}. If @emph{event-slots} is given, these symbols
 
10912
are bound to the value of the corresponding event slot in the clause
 
10913
forms. Each element of @emph{event-slots} can also be a list of the
 
10914
form (@emph{event-slot-keyword variable}), in which case the
 
10915
@emph{variable} symbol is bound to the value of the event slot
 
10916
specified by the @emph{event-slot-keyword}.
 
10917
 
 
10918
If every clause returns @var{nil} for each event in the event
 
10919
queue, @var{event-case} waits for another event to arrive. If
 
10920
@var{:timeout} is non-@var{nil} and no event arrives within the
 
10921
specified timeout interval (given in seconds), @var{event-case}
 
10922
returns @var{nil}; if @var{:timeout} is @var{nil},
 
10923
@var{event-case} will not return until a clause returns
 
10924
non-@var{nil}. @var{event-case} may wait only once on network data
 
10925
and therefore timeout prematurely.
 
10926
 
 
10927
If @var{:force-output-p} is true, @var{event-case} first invokes
 
10928
@var{display-force-output} to send any buffered requests. If
 
10929
@var{:peek-p} is true, a processed event is not removed from the
 
10930
queue. If @var{:discard-p} is true, unprocessed events are removed
 
10931
from the queue; otherwise, unprocessed events are left in place.
 
10932
 
 
10933
@table @var
 
10934
@item handled-p
 
10935
Type @var{boolean}.
 
10936
@end table
 
10937
 
 
10938
@end defmac
 
10939
 
 
10940
 
 
10941
 
 
10942
@defmac event-cond display &key :timeout :peek-p :discard-p (:force-output-p t) &body clauses
 
10943
 
 
10944
@table @var
 
10945
@item handled-p
 
10946
Type @var{boolean}.
 
10947
@end table
 
10948
 
 
10949
 
 
10950
Similar to @var{event-case} except that each of the clauses is a
 
10951
list of the form (@emph{event-match} [@emph{event-slots}]
 
10952
@emph{test-form} &rest @emph{forms}). Executes the
 
10953
@emph{test-form} of the clause that matches each queued event until
 
10954
a @emph{test-form} returns non-@var{nil}. The body @emph{forms} of
 
10955
the clause are then executed. The values returned by the last clause
 
10956
body form are then returned by @var{event-cond}.
 
10957
 
 
10958
When a @emph{test-form} returns true and @var{:peek-p} is
 
10959
@var{nil}, or when a @emph{test-form} returns @var{nil} and
 
10960
@var{:discard-p} is true, the matching event is removed from the
 
10961
event queue before the body @emph{forms} are executed.
 
10962
@table @var
 
10963
@item display
 
10964
A @var{display}.
 
10965
@item :handler
 
10966
A handler function or a sequence of handler functions.
 
10967
@item :timeout
 
10968
Specifies the timeout delay in seconds.
 
10969
@item :peek-p
 
10970
If @var{nil}, events are removed from the event queue after processing.
 
10971
@item :discard-p
 
10972
If true, unprocessed events are discarded.
 
10973
@item :force-output-p
 
10974
If true, buffered output requests are sent.
 
10975
@item clauses
 
10976
Code to process specified event types.
 
10977
@end table
 
10978
 
 
10979
@end defmac
 
10980
 
 
10981
 
 
10982
 
 
10983
@node Managing the Event Queue, Sending Events, Processing Events, Events and Input
 
10984
@section Managing the Event Queue
 
10985
 
 
10986
 
 
10987
The following paragraphs describe CLX functions and macros used to:
 
10988
@itemize @bullet
 
10989
 
 
10990
@item  Put a new event on the event queue
 
10991
 
 
10992
@item  Discard the current event
 
10993
 
 
10994
@item  Return the current length of the event queue
 
10995
 
 
10996
@item  Gain exclusive access to the event queue for a client process
 
10997
@end itemize
 
10998
 
 
10999
@defun queue-event display event-key &rest event-slots &key :append-p &allow-other-keys
 
11000
 
 
11001
@table @var
 
11002
@item display
 
11003
A @var{display}.
 
11004
@item event-key
 
11005
Specifies the type of event placed in the queue.
 
11006
@item event-slots
 
11007
Keyword-value pairs that describe the contents of an event.
 
11008
@item :append-p
 
11009
If true, the event is placed at the tail of the queue; otherwise, the event is
 
11010
placed at the head of the queue.
 
11011
@end table
 
11012
 
 
11013
Places an event of the type given by @emph{event-key} into the event
 
11014
queue. When @var{:append-p} is true, the event is placed at the
 
11015
tail of the queue; otherwise, the event is placed at the head of the
 
11016
queue. The actual @emph{event-slots} passed depend on the event
 
11017
type. The keyword symbols used for each event type are event slot
 
11018
names defined by the @var{declare-event} macro and are described in
 
11019
@ref{Declaring Event Types}.
 
11020
 
 
11021
 
 
11022
 
 
11023
@end defun
 
11024
 
 
11025
 
 
11026
@defun discard-current-event display
 
11027
 
 
11028
@table @var
 
11029
@item display
 
11030
A @var{display}.
 
11031
@end table
 
11032
 
 
11033
 
 
11034
Discards the current event for the @emph{display}. Returns
 
11035
@var{nil} when the event queue is empty; otherwise, returns
 
11036
@var{t}. This function provides extra flexibility for discarding
 
11037
events, but it should be used carefully; use @var{event-cond}
 
11038
instead, if possible. Typically, @var{discard-current-event} is
 
11039
called inside a handler function or a clause of an @var{event-case}
 
11040
form and is followed by another call to @var{process-event},
 
11041
@var{event-case}, or @var{event-cond}.
 
11042
@table @var
 
11043
@item discarded-p
 
11044
Type @var{boolean}.
 
11045
@end table
 
11046
 
 
11047
@end defun
 
11048
 
 
11049
 
 
11050
@defun event-listen display &optional (timeout 0)
 
11051
 
 
11052
@table @var
 
11053
@item display
 
11054
A @var{display}.
 
11055
@item timeout
 
11056
The number of seconds to wait for events.
 
11057
@end table
 
11058
 
 
11059
 
 
11060
Returns the number of events queued locally. If the event queue is
 
11061
empty, @var{event-listen} waits for an event to arrive. If timeout
 
11062
is non-@var{nil} and no event arrives within the specified timeout
 
11063
interval (given in seconds), @var{event-listen} returns @var{nil};
 
11064
if timeout is @var{nil}, @var{event-listen} will not return until
 
11065
an event arrives.
 
11066
@table @var
 
11067
@item event-count
 
11068
Type @code{(or null integer)}.
 
11069
@end table
 
11070
 
 
11071
@end defun
 
11072
 
 
11073
@defmac with-event-queue display &body body
 
11074
@anchor{with-event-queue}
 
11075
 
 
11076
@table @var
 
11077
@item display
 
11078
A @var{display}.
 
11079
@item body
 
11080
Forms to execute.
 
11081
@end table
 
11082
 
 
11083
Executes the @emph{body} in a critical region in which the executing
 
11084
client process has exclusive access to the event queue.
 
11085
 
 
11086
@end defmac
 
11087
 
 
11088
 
 
11089
 
 
11090
@node Sending Events, Pointer Position, Managing the Event Queue, Events and Input
 
11091
@section Sending Events
 
11092
 
 
11093
 
 
11094
A client can send an event to a window. Clients selecting this window
 
11095
event will receive it just like any other event sent by the X server.
 
11096
 
 
11097
@defun send-event window event-key event-mask &rest event-slots &key :propagate-p :display &allow-other-keys
 
11098
 
 
11099
@table @var
 
11100
@item window
 
11101
The destination @var{window} for the event.
 
11102
@item event-key
 
11103
An @var{event-key} defining the type of event to send.
 
11104
@item event-mask
 
11105
Specifies the event types that receiving clients must select.
 
11106
@item event-slots
 
11107
Keyword-value pairs that describe the contents of an event.
 
11108
@item :propagate-p
 
11109
If true, the event can be propagated to ancestors of the destination window.
 
11110
@item :display
 
11111
A @var{display}.
 
11112
@end table
 
11113
 
 
11114
Sends an event specified by the @emph{event-key} and
 
11115
@emph{event-slots} to the given destination @emph{window}. Any
 
11116
active grabs are ignored. The @emph{event-slots} passed depend on
 
11117
the event type. The keyword symbols used for each event type are
 
11118
event slot names defined by the @var{declare-event} macro and are
 
11119
described in @ref{Declaring Event Types}.
 
11120
 
 
11121
If the @emph{window} is @var{:pointer-window}, the destination
 
11122
@emph{window} is replaced with the window containing the
 
11123
pointer. If the @emph{window} is @var{:input-focus}, the
 
11124
destination @emph{window} is replaced with the descendant of the
 
11125
focus window that contains the pointer or (if no such descendant
 
11126
exists) the focus window. The @var{:display} keyword is only
 
11127
required if the @emph{window} is @var{:pointer-window} or
 
11128
@var{:input-focus}.
 
11129
 
 
11130
The @emph{event-key} must be one of the core events, or one of the
 
11131
events defined by an extension, so the server can send the event
 
11132
with the correct byte-order. The contents of the event are
 
11133
otherwise unaltered and unchecked by the server, except that the
 
11134
@var{send-event-p} event slot is set to true.
 
11135
 
 
11136
If the @emph{event-mask} is @var{nil}, the event is sent to the
 
11137
client that created the destination @emph{window} with an
 
11138
@emph{event-mask} of 0; if that client no longer exists, no event
 
11139
is sent. Otherwise, the event is sent to every client selecting
 
11140
any of the event types specified by @emph{event-mask} on the
 
11141
destination @emph{window}.
 
11142
 
 
11143
If @var{:propagate-p} is true and no clients have selected any of
 
11144
the event types in @emph{event-mask} on the destination
 
11145
@emph{window}, the destination is replaced with the closest
 
11146
ancestor of @emph{window} for which some client has selected a
 
11147
type in @emph{event-mask} and no intervening window has that type
 
11148
in its do-not-propagate mask. If no such window exists, or if the
 
11149
@emph{window} is an ancestor of the focus window and
 
11150
@var{:input-focus} was originally specified as the destination,
 
11151
the event is not sent to any clients. Otherwise, the event is
 
11152
reported to every client selecting on the final destination any of
 
11153
the types specified in @emph{event-mask}.
 
11154
 
 
11155
 
 
11156
@end defun
 
11157
 
 
11158
 
 
11159
@node Pointer Position, Managing Input Focus, Sending Events, Events and Input
 
11160
@section Pointer Position
 
11161
 
 
11162
 
 
11163
The CLX functions affecting pointer position are discussed in the
 
11164
following paragraphs.
 
11165
 
 
11166
@defun query-pointer window
 
11167
 
 
11168
@table @var
 
11169
@item window
 
11170
A @var{window} specifying the coordinate system for the returned position.
 
11171
@end table
 
11172
 
 
11173
 
 
11174
Returns the current pointer coordinates relative to the given
 
11175
@emph{window}. If @var{query-pointer} returns @var{nil} for
 
11176
@emph{same-screen-p}, the pointer is not on the same screen as the
 
11177
@emph{window}. In this case, @var{query-pointer} returns a value
 
11178
of @var{nil} for @emph{child} and a value of zero for @emph{x}
 
11179
and @emph{y}. If @var{query-pointer} returns true for
 
11180
@emph{same-screen-p}, the returned @emph{x} and @emph{y} are
 
11181
relative to the origin of window. The @emph{child} is the child of
 
11182
the window containing the pointer, if any. The @emph{state-mask}
 
11183
returned gives the current state of the modifier keys and pointer
 
11184
buttons. The returned @emph{root} is the root window currently
 
11185
containing the pointer. The returned @emph{root-x} and
 
11186
@emph{root-y} specify the pointer coordinates relative to
 
11187
@emph{root}.
 
11188
@table @var
 
11189
@item x
 
11190
Type @var{int16}.
 
11191
@item y
 
11192
Type @var{int16}.
 
11193
@item same-screen-p
 
11194
Type @var{boolean}.
 
11195
@item child
 
11196
Type @var{window} or @var{null}.
 
11197
@item state-mask
 
11198
Type @var{card16}.
 
11199
@item root-x
 
11200
Type @var{int16}.
 
11201
@item root-y
 
11202
Type @var{int16}.
 
11203
@item root
 
11204
Type @var{window}.
 
11205
@end table
 
11206
 
 
11207
@end defun
 
11208
 
 
11209
 
 
11210
@defun global-pointer-position display
 
11211
 
 
11212
@table @var
 
11213
@item display
 
11214
A @var{display}.
 
11215
@end table
 
11216
 
 
11217
 
 
11218
Returns the @emph{root} window currently containing the @emph{display} pointer and the current
 
11219
position of the pointer relative to the @emph{root}.
 
11220
@table @var
 
11221
@item root-x
 
11222
Type @var{int16}.
 
11223
@item root-y
 
11224
Type @var{int16}.
 
11225
@item root
 
11226
Type @var{window}.
 
11227
@end table
 
11228
 
 
11229
@end defun
 
11230
 
 
11231
 
 
11232
@defun pointer-position window
 
11233
 
 
11234
@table @var
 
11235
@item window
 
11236
A @var{window} specifying the coordinate system for the returned position.
 
11237
@end table
 
11238
 
 
11239
 
 
11240
Returns the current pointer coordinates relative to the given
 
11241
@emph{window}. If @var{pointer-position} returns @var{nil} for
 
11242
@emph{same-screen-p}, the pointer is not on the same screen as the
 
11243
@emph{window}.  In this case, @var{pointer-position} returns a
 
11244
value of @var{nil} for @emph{child} and a value of zero for
 
11245
@emph{x} and @emph{y}. If @var{pointer-position} returns true for
 
11246
@emph{same-screen-p}, the returned @emph{x} and @emph{y} are
 
11247
relative to the origin of @emph{window}.
 
11248
@table @var
 
11249
@item x
 
11250
Type @var{int16}.
 
11251
@item y
 
11252
Type @var{int16}.
 
11253
@item same-screen-p
 
11254
Type @var{boolean}.
 
11255
@item child
 
11256
Type @var{window} or @var{null}.
 
11257
@end table
 
11258
 
 
11259
@end defun
 
11260
 
 
11261
 
 
11262
@defun motion-events window &key :start :stop (:result-type 'list)
 
11263
 
 
11264
@table @var
 
11265
@item window
 
11266
The @var{window} containing the returned motion events.
 
11267
@item :start
 
11268
@itemx :stop
 
11269
@var{timestamp} values for the time interval for returned motion events.
 
11270
@item :result-type
 
11271
The form of the returned motion events.
 
11272
@end table
 
11273
 
 
11274
 
 
11275
Many X server implementations maintain a more precise history of
 
11276
pointer motion between event notifications. The pointer position
 
11277
at each pointer hardware interrupt can be stored into a buffer for
 
11278
later retrieval.This is called the @emph{motion history buffer}. A
 
11279
paint program, for example, may want to have a precise history of
 
11280
where the pointer traveled, even though for most other
 
11281
applications this amount of detail is grossly excessive.
 
11282
 
 
11283
The @var{motion-events} function returns all events in the motion
 
11284
history buffer that fall between the specified @var{:start} and
 
11285
@var{:stop} timestamps (inclusive) and have coordinates that lie
 
11286
within the specified @emph{window} (including borders) at its
 
11287
present placement. If the @var{:start} time is later than the
 
11288
@var{:stop} time or if the @var{:start} time is in the future,
 
11289
no events are returned.
 
11290
@table @var
 
11291
@item motion-events
 
11292
Type @code{(repeat-seq (int16 x) (int16 y) (timestamp time))}.
 
11293
@end table
 
11294
 
 
11295
@end defun
 
11296
 
 
11297
 
 
11298
@defun warp-pointer destination destination-x destination-y
 
11299
 
 
11300
@table @var
 
11301
@item destination
 
11302
The @var{window} into which the pointer is moved.
 
11303
@item destination-x
 
11304
@itemx destination-y
 
11305
The new position of the pointer relative to the destination.
 
11306
@end table
 
11307
 
 
11308
Moves the pointer to the given coordinates relative to the
 
11309
@emph{destination} window.  @var{warp-pointer} should be rarely be
 
11310
used since the user should normally be in control of the pointer
 
11311
position. @var{warp-pointer} generates events just as if the user
 
11312
had instantaneously moved the pointer from one position to another.
 
11313
 
 
11314
@var{warp-pointer} cannot move the pointer outside the confine-to
 
11315
window of an active pointer grab; an attempt to do so only moves the
 
11316
pointer as far as the closest edge of the confine-to window.
 
11317
 
 
11318
 
 
11319
@end defun
 
11320
 
 
11321
 
 
11322
@defun warp-pointer-relative display x-offset y-offset
 
11323
 
 
11324
@table @var
 
11325
@item display
 
11326
A @var{display}.
 
11327
@item x-offset
 
11328
@itemx y-offset
 
11329
The offsets used to adjust the pointer position.
 
11330
@end table
 
11331
 
 
11332
Moves the pointer by the given offsets. This function should rarely
 
11333
be used since the user should normally be in control of the pointer
 
11334
position. @var{warp-pointer-relative} generates events just as if
 
11335
the user had instantaneously moved the pointer from one position to
 
11336
another.
 
11337
 
 
11338
@var{warp-pointer-relative} cannot move the pointer outside the
 
11339
confine-to window of an active pointer grab; an attempt to do so
 
11340
only moves the pointer as far as the closest edge of the confine-to
 
11341
window.
 
11342
 
 
11343
 
 
11344
@end defun
 
11345
 
 
11346
 
 
11347
@defun warp-pointer-if-inside destination destination-x destination-y source source-x source-y &optional (source-width 0) (source-height 0)
 
11348
 
 
11349
@table @var
 
11350
@item destination
 
11351
The @var{window} into which the pointer is moved.
 
11352
@item destination-x
 
11353
@itemx destination-y
 
11354
The new position of the pointer relative to the @emph{destination}.
 
11355
@item source
 
11356
The @var{window} that must currently contain the pointer.
 
11357
@item source-x
 
11358
@itemx source-y
 
11359
@itemx source-width
 
11360
@itemx source-height
 
11361
The source rectangle that must currently contain the pointer.
 
11362
@end table
 
11363
 
 
11364
Moves the pointer to the given position relative to the
 
11365
@emph{destination} window. However, the move can only take place if
 
11366
the pointer is currently contained in a visible portion of the
 
11367
specified rectangle of the @emph{source} window. If
 
11368
@emph{source-height} is zero, it is replaced with the current height
 
11369
of @emph{source} window minus @emph{source-y}. If
 
11370
@emph{source-width} is zero, it is replaced with the current width
 
11371
of @emph{source} window minus @emph{source-x}.
 
11372
 
 
11373
@var{warp-pointer-if-inside} generates events just as if the user
 
11374
had instantaneously moved the pointer from one position to
 
11375
another. @var{warp-pointer-if-inside} cannot move the pointer
 
11376
outside the confine-to window of an active pointer grab; an attempt
 
11377
to do so only moves the pointer as far as the closest edge of the
 
11378
confine-to window.
 
11379
 
 
11380
 
 
11381
@end defun
 
11382
 
 
11383
@defun warp-pointer-relative-if-inside x-offset y-offset source source-x source-y &optional (source-width 0) (source-height 0)
 
11384
 
 
11385
@table @var
 
11386
@item x-offset
 
11387
@itemx y-offset
 
11388
The offsets used to adjust the pointer position.
 
11389
@item source
 
11390
The @var{window} that must currently contain the pointer.
 
11391
@item source-x
 
11392
@itemx source-y
 
11393
@itemx source-width
 
11394
@itemx source-height
 
11395
The source rectangle that must currently contain the pointer.
 
11396
@end table
 
11397
 
 
11398
Moves the pointer by the given offsets. However, the move can only
 
11399
take place if the pointer is currently contained in a visible
 
11400
portion of the specified rectangle of the @emph{source} window. If
 
11401
@emph{source-height} is zero, it is replaced with the current height
 
11402
of @emph{source-window} minus @emph{source-y}. If
 
11403
@emph{source-width} is zero, it is replaced with the current width
 
11404
of @emph{source-window} minus @emph{source-x}.
 
11405
 
 
11406
@var{warp-pointer-relative-if-inside} generates events just as if
 
11407
the user had instantaneously moved the pointer from one position to
 
11408
another. @var{warp-pointer-relative-if-inside} cannot move the
 
11409
pointer outside the confine-to window of an active pointer grab; an
 
11410
attempt to do so only moves the pointer as far as the closest edge
 
11411
of the confine-to window.
 
11412
 
 
11413
 
 
11414
 
 
11415
@end defun
 
11416
 
 
11417
 
 
11418
@node Managing Input Focus, Grabbing the Pointer, Pointer Position, Events and Input
 
11419
@section Managing Input Focus
 
11420
 
 
11421
 
 
11422
CLX provides the @var{set-focus-input} and @var{focus-input} functions
 
11423
to set and get the keyboard input focus window.
 
11424
 
 
11425
@defun set-input-focus display focus revert-to &optional time
 
11426
 
 
11427
@table @var
 
11428
@item display
 
11429
A @var{display}.
 
11430
@item focus
 
11431
The new input focus @var{window}.
 
11432
@item revert-to
 
11433
The focus @var{window} when focus is no longer viewable.
 
11434
@item time
 
11435
A @var{timestamp}.
 
11436
@end table
 
11437
 
 
11438
Changes the keyboard input focus and the last-focus-change
 
11439
time. The function has no effect if the specified @emph{time} is
 
11440
earlier than the current last-focus-change time or is later than
 
11441
the current server time; otherwise, the last-focus-change time is
 
11442
set to the specified @emph{time}. The @var{set-input-focus}
 
11443
function causes the X server to generate @var{:focus-in} and
 
11444
@var{:focus-out} events.
 
11445
 
 
11446
If @var{:none} is specified as the @emph{focus}, all keyboard
 
11447
events are discarded until a new focus window is set. In this
 
11448
case, the @emph{revert-to} argument is ignored.
 
11449
 
 
11450
If a window is specified as the @emph{focus} argument, it becomes
 
11451
the keyboard's focus window.  If a generated keyboard event would
 
11452
normally be reported to this window or one of its inferiors, the
 
11453
event is reported normally; otherwise, the event is reported with
 
11454
respect to the focus window.
 
11455
 
 
11456
If @var{:pointer-root} is specified as the @emph{focus} argument,
 
11457
the input focus window is set to the root window of the screen
 
11458
containing the pointer when each keyboard event occurs. In this
 
11459
case, the @emph{revert-to} argument is ignored.
 
11460
 
 
11461
The specified @emph{focus} window must be viewable at the time of
 
11462
the request. If the @emph{focus} window later becomes not
 
11463
viewable, the new focus window depends on the @emph{revert-to}
 
11464
argument. If @emph{revert-to} is specified as @var{:parent}, the
 
11465
@emph{focus} reverts to the parent (or the closest viewable
 
11466
ancestor) and the new @emph{revert-to} value is take to be
 
11467
@var{:none}. If @emph{revert-to} is @var{:pointer-root} or
 
11468
@var{:none}, the @emph{focus} reverts to that value. When the
 
11469
@emph{focus} reverts, @var{:focus-in} and @var{:focus-out}
 
11470
events are generated, but the last-focus-change time is not
 
11471
affected.
 
11472
 
 
11473
 
 
11474
@end defun
 
11475
 
 
11476
 
 
11477
@defun input-focus display
 
11478
 
 
11479
@table @var
 
11480
@item display
 
11481
A @var{display}.
 
11482
@end table
 
11483
 
 
11484
 
 
11485
Returns the @emph{focus} window, @var{:pointer-root}, or
 
11486
@var{:none}, depending on the current state of the focus
 
11487
window. @emph{revert-to} returns the current focus revert-to
 
11488
state.
 
11489
@table @var
 
11490
@item focus
 
11491
Type (@var{or window} (@var{member :none :pointer-root})).
 
11492
@item revert-to
 
11493
Type (@var{or window} (@var{member :none :pointer-root :parent})).
 
11494
@end table
 
11495
 
 
11496
@end defun
 
11497
 
 
11498
 
 
11499
@node Grabbing the Pointer, Grabbing a Button, Managing Input Focus, Events and Input
 
11500
@section Grabbing the Pointer
 
11501
 
 
11502
 
 
11503
CLX provides the @var{grab-pointer} and @var{ungrab-pointer} functions
 
11504
for grabbing and releasing pointer control.
 
11505
 
 
11506
@defun grab-pointer window event-mask &key :owner-p :sync-pointer-p :sync-keyboard-p :confine-to :cursor :time
 
11507
 
 
11508
@table @var
 
11509
@item window
 
11510
The @var{window} grabbing the pointer.
 
11511
@item event-mask
 
11512
A @var{pointer-event-mask}.
 
11513
@item :owner-p
 
11514
If true, all client windows receive pointer events normally.
 
11515
@item :sync-pointer-p
 
11516
Indicates whether the pointer is in synchronous or asynchronous mode.
 
11517
@item :sync-keyboard-p
 
11518
Indicates whether the keyboard is in synchronous or asynchronous mode.
 
11519
@item :confine-to
 
11520
A @var{window} to which the pointer is confined.
 
11521
@item :cursor
 
11522
A @var{cursor}.
 
11523
@item :time
 
11524
A @var{timestamp}. A @var{nil} value means the current server time is used.
 
11525
@end table
 
11526
 
 
11527
 
 
11528
Actively grabs control of the pointer. Further pointer events are
 
11529
only reported to the grabbing client. The request overrides any
 
11530
active pointer grab by this client.
 
11531
 
 
11532
If @var{:owner-p} is @var{nil}, all generated pointer events are
 
11533
reported with respect to @emph{window}, and are only reported if
 
11534
selected by @emph{event-mask}. If @var{:owner-p} is true, and if a
 
11535
generated pointer event would normally be reported to this client,
 
11536
it is reported normally; otherwise the event is reported with
 
11537
respect to the @emph{window}, and is only reported if selected by
 
11538
@emph{event-mask}. For either value of @var{:owner-p}, unreported
 
11539
events are simply discarded.
 
11540
 
 
11541
If @var{:sync-pointer-p} is @var{nil}, pointer event processing
 
11542
continues normally (asynchronously); if the pointer is currently
 
11543
frozen by this client, then processing of pointer events is
 
11544
resumed. If @var{:sync-pointer-p} is true (indicating a synchronous
 
11545
action), the pointer (as seen via the protocol) appears to freeze,
 
11546
and no further pointer events are generated by the server until the
 
11547
grabbing client issues a releasing @var{allow-events} request.
 
11548
Actual pointer changes are not lost while the pointer is frozen;
 
11549
they are simply queued for later processing.
 
11550
 
 
11551
If @var{:sync-keyboard-p} is @var{nil}, keyboard event processing
 
11552
is unaffected by activation of the grab. If @var{:sync-keyboard-p}
 
11553
is true, the keyboard (as seen via the protocol) appears to freeze,
 
11554
and no further keyboard events are generated by the server until the
 
11555
grabbing client issues a releasing @var{allow-events}
 
11556
request. Actual keyboard changes are not lost while the keyboard is
 
11557
frozen; they are simply queued for later processing.
 
11558
 
 
11559
If @var{:cursor} is specified, it is displayed regardless of what
 
11560
window the pointer is in.  Otherwise, the normal cursor for the
 
11561
@emph{window} is displayed.
 
11562
 
 
11563
If a @var{:confine-to} window is specified, the pointer is
 
11564
restricted to stay within that window.  The @var{:confine-to}
 
11565
window does not need to have any relationship to the
 
11566
@emph{window}. If the pointer is not initially in the
 
11567
@var{:confine-to} window, it is warped automatically to the closest
 
11568
edge (with @var{:enter}/@var{:leave-events} generated normally)
 
11569
just before the grab activates.  If the @var{:confine-to} window is
 
11570
subsequently reconfigured, the pointer is warped automatically as
 
11571
necessary to keep it contained in the window.
 
11572
 
 
11573
@var{grab-pointer} generates @var{:enter-notify} and
 
11574
@var{:leave-notify} events. @var{grab-pointer} can fail with a
 
11575
status of:
 
11576
@itemize @bullet
 
11577
 
 
11578
@item
 
11579
@var{:already-grabbed} if the pointer is actively grabbed by some
 
11580
other client
 
11581
 
 
11582
@item
 
11583
@var{:frozen} if the pointer is frozen by an active grab of
 
11584
another client
 
11585
 
 
11586
@item
 
11587
@var{:not-viewable} if the @emph{window} or the
 
11588
@var{:confine-to} window is not viewable, or if the
 
11589
@var{:confine-to} window lies completely outside the boundaries
 
11590
of the root window.
 
11591
 
 
11592
@item
 
11593
@var{:invalid-time} if the specified time is earlier than the
 
11594
last-pointer-grab time or later than the current server
 
11595
time. Otherwise, the last-pointer-grab time is set to the
 
11596
specified time, with current-time replaced by the current server
 
11597
time, and a value of @var{:success} is returned by
 
11598
@var{grab-pointer}.
 
11599
@end itemize
 
11600
@table @var
 
11601
@item grab-status
 
11602
One of @var{:already-grabbed}, @var{:frozen}, @var{:invalid-time},
 
11603
@var{:not-viewable}, or @var{:success}.
 
11604
@end table
 
11605
 
 
11606
@end defun
 
11607
 
 
11608
 
 
11609
@defun ungrab-pointer display &key :time
 
11610
 
 
11611
@table @var
 
11612
@item display
 
11613
A @var{display}.
 
11614
@item :time
 
11615
A @var{timestamp}.
 
11616
@end table
 
11617
 
 
11618
Releases the pointer if this client has it actively grabbed (from
 
11619
either @var{grab-pointer}, @var{grab-button}, or from a normal
 
11620
button press), and releases any queued events. The request has no
 
11621
effect if the specified @var{:time} is earlier than the
 
11622
last-pointer-grab time or is later than the current server time. An
 
11623
@var{ungrabpointer} is performed automatically if the event window
 
11624
or @var{:confine-to} window for an active pointer grab becomes not
 
11625
viewable.
 
11626
 
 
11627
This request generates @var{:enter-notify} and @var{:leave-notify}
 
11628
events.
 
11629
 
 
11630
 
 
11631
@end defun
 
11632
 
 
11633
 
 
11634
@defun change-active-pointer-grab display event-mask &optional cursor time
 
11635
 
 
11636
@table @var
 
11637
@item display
 
11638
A @var{display}.
 
11639
@item event-mask
 
11640
A @var{pointer-event-mask}.
 
11641
@item cursor
 
11642
A @var{cursor} or @var{nil}.
 
11643
@item time
 
11644
A @var{timestamp}.
 
11645
@end table
 
11646
 
 
11647
Changes the specified dynamic parameters if the pointer is actively
 
11648
grabbed by the client and the specified @emph{time} is no earlier
 
11649
than the last-pointer-grab time and no later than the current server
 
11650
time. The interpretation of @emph{event-mask} and @emph{cursor} are
 
11651
as in @var{grab-pointer}.  @var{change-active-pointer-grab} has no
 
11652
effect on the passive parameters of a @var{grab-button}.
 
11653
 
 
11654
 
 
11655
@end defun
 
11656
 
 
11657
 
 
11658
@node Grabbing a Button, Grabbing the Keyboard, Grabbing the Pointer, Events and Input
 
11659
@section Grabbing a Button
 
11660
 
 
11661
 
 
11662
CLX provides the @var{grab-button} and @var{ungrab-button} functions
 
11663
for passively grabbing and releasing pointer control.
 
11664
 
 
11665
@defun grab-button window button event-mask &key (:modifiers 0) :owner-p :sync-pointer-p :sync-keyboard-p :confine-to :cursor
 
11666
 
 
11667
@table @var
 
11668
@item window
 
11669
A @var{window}.
 
11670
@item button
 
11671
The button (type @var{card8}) pressed or @var{:any}.
 
11672
@item event-mask
 
11673
A @var{pointer-event-mask}.
 
11674
@item :modifiers
 
11675
A @var{modifier-mask}.
 
11676
@item :owner-p
 
11677
If true, all client windows receive pointer events normally.
 
11678
@item :sync-pointer-p
 
11679
Indicates whether the pointer is handled in a synchronous or asynchronous fashion.
 
11680
@item :sync-keyboard-p
 
11681
Indicates whether the keyboard is in synchronous or asynchronous mode.
 
11682
@item :confine-to
 
11683
A @var{window} to which the pointer is confined.
 
11684
@item :cursor
 
11685
A @var{cursor}.
 
11686
@end table
 
11687
 
 
11688
This request establishes a passive grab. If the specified
 
11689
@emph{button} is pressed when the specified modifier keys are down
 
11690
(and no other buttons or modifier keys are down), and:
 
11691
@itemize @bullet
 
11692
 
 
11693
@item  @emph{window} contains the pointer
 
11694
 
 
11695
@item  The @var{:confine-to} window (if any) is viewable
 
11696
 
 
11697
@item  These constraints are not satisfied for any ancestor of @emph{window}
 
11698
@end itemize
 
11699
 
 
11700
then:
 
11701
@itemize @bullet
 
11702
 
 
11703
@item
 
11704
The pointer is actively grabbed as described with
 
11705
@var{grab-pointer}
 
11706
 
 
11707
@item
 
11708
The last-pointer-grab time is set to the time that the button was
 
11709
pressed (as transmitted in the @var{:button-press} event)
 
11710
 
 
11711
@item
 
11712
The @var{:button-press} event is reported
 
11713
@end itemize
 
11714
 
 
11715
The interpretation of the remaining arguments is the same as with
 
11716
@var{grab-pointer}. The active grab is terminated automatically
 
11717
when all buttons are released (independent of the state of modifier
 
11718
keys).
 
11719
 
 
11720
A zero @emph{modifier} mask is equivalent to issuing the request for
 
11721
all possible modifier-key combinations (including the combination of
 
11722
no modifiers). It is not required that all specified modifiers have
 
11723
currently assigned keycodes. A @emph{button} of @var{:any} is
 
11724
equivalent to issuing the request for all possible
 
11725
buttons. Otherwise, it is not required that the specified
 
11726
@emph{button} currently be assigned to a physical button.
 
11727
 
 
11728
 
 
11729
@end defun
 
11730
 
 
11731
 
 
11732
@defun ungrab-button window button &key (:modifiers 0)
 
11733
 
 
11734
@table @var
 
11735
@item window
 
11736
A @var{window}.
 
11737
@item button
 
11738
The button (type @var{card8}) that is released or @var{:any}.
 
11739
@item :modifiers
 
11740
A @var{modifier-mask}.
 
11741
@end table
 
11742
 
 
11743
Releases the passive button/key combination on the specified
 
11744
@emph{window} if it was grabbed by this client. A zero
 
11745
@emph{modifier} mask is equivalent to issuing the request for all
 
11746
possible modifier combinations including the combination of no
 
11747
modifiers. A @emph{button} of @var{:any} is equivalent to issuing
 
11748
the request for all possible buttons. This has no effect on an
 
11749
active grab.
 
11750
 
 
11751
 
 
11752
@end defun
 
11753
 
 
11754
 
 
11755
@node Grabbing the Keyboard, Grabbing a Key, Grabbing a Button, Events and Input
 
11756
@section Grabbing the Keyboard
 
11757
 
 
11758
 
 
11759
CLX provides the @var{grab-keyboard} and @var{ungrab-keyboard}
 
11760
functions for actively grabbing and releasing control of the keyboard.
 
11761
 
 
11762
@defun grab-keyboard window &key :owner-p :sync-pointer-p :sync-keyboard-p :time
 
11763
 
 
11764
@table @var
 
11765
@item window
 
11766
A @var{window}.
 
11767
@item :owner-p
 
11768
If true, all client windows receive keyboard input normally.
 
11769
@item :sync-pointer-p
 
11770
Indicates whether the pointer is in synchronous or asynchronous mode.
 
11771
@item :sync-keyboard-p
 
11772
Indicates whether the keyboard is in synchronous or asynchronous mode.
 
11773
@item :time
 
11774
A @var{timestamp}.
 
11775
@end table
 
11776
 
 
11777
 
 
11778
Actively grabs control of the keyboard. Further key events are
 
11779
reported only to the grabbing client. The request overrides any
 
11780
active keyboard grab by this client.  @var{grab-keyboard} generates
 
11781
@var{:focus-in} and @var{:focus-out} events.
 
11782
 
 
11783
If @var{:owner-p} is @var{nil}, all generated key events are
 
11784
reported with respect to @emph{window}. If @var{:owner-p} is true,
 
11785
then a generated key event that would normally be reported to this
 
11786
client is reported normally; otherwise the event is reported with
 
11787
respect to the @emph{window}.  Both @var{:key-press} and
 
11788
@var{:key-release} events are always reported, independent of any
 
11789
event selection made by the client.
 
11790
 
 
11791
If @var{:sync-keyboard-p} is @var{nil}, keyboard event processing
 
11792
continues normally (asynchronously); if the keyboard is currently
 
11793
frozen by this client, then processing of keyboard events is
 
11794
resumed. If @var{:sync-keyboard-p} is true, the keyboard (as seen
 
11795
via the protocol) appears to freeze, and no further keyboard events
 
11796
are generated by the server until the grabbing client issues a
 
11797
releasing @var{allow-events} request. Actual keyboard changes are
 
11798
not lost while the keyboard is frozen; they are simply queued for
 
11799
later processing.
 
11800
 
 
11801
If @var{:sync-pointer-p} is @var{nil}, pointer event processing is
 
11802
unaffected by activation of the grab. If @var{:sync-pointer-p} is
 
11803
true, the pointer (as seen via the protocol) appears to freeze, and
 
11804
no further pointer events are generated by the server until the
 
11805
grabbing client issues a releasing @var{allow-events}
 
11806
request. Actual pointer changes are not lost while the pointer is
 
11807
frozen; they are simply queued for later processing.
 
11808
 
 
11809
The grab can fail with a status of:
 
11810
@itemize @bullet
 
11811
 
 
11812
@item
 
11813
@var{:already-grabbed} if the keyboard is actively grabbed by
 
11814
some other client
 
11815
 
 
11816
@item
 
11817
@var{:frozen} if the keyboard is frozen by an active grab from
 
11818
another client
 
11819
 
 
11820
@item
 
11821
@var{:not-viewable} if @emph{window} is not viewable
 
11822
 
 
11823
@item
 
11824
@var{:invalid-time} if the specified time is earlier than the
 
11825
last-keyboard-grab time or later than the current server
 
11826
time. Otherwise, @var{grab-keyboard} returns a status of
 
11827
@var{:success} and last-keyboard-grab time is set to the
 
11828
specified time, with current-time replaced by current server time.
 
11829
@end itemize
 
11830
@table @var
 
11831
@item grab-status
 
11832
One of @var{:already-grabbed}, @var{:frozen}, @var{:invalid-time},
 
11833
@var{:not-viewable}, or @var{:success}.
 
11834
@end table
 
11835
 
 
11836
@end defun
 
11837
 
 
11838
 
 
11839
@defun ungrab-keyboard display &key :time
 
11840
 
 
11841
@table @var
 
11842
@item display
 
11843
A @var{display}.
 
11844
@item :time
 
11845
A @var{timestamp}.
 
11846
@end table
 
11847
 
 
11848
Releases the keyboard if this client has it actively grabbed (from
 
11849
either @var{grab-keyboard} or @var{grab-key}), and releases any
 
11850
queued events. The request has no effect if the specified time is
 
11851
earlier than the last-keyboard-grab time or is later than the
 
11852
current server time.  An @var{ungrab-keyboard} is performed
 
11853
automatically if the event window for an active keyboard grab
 
11854
becomes not viewable.
 
11855
 
 
11856
 
 
11857
@end defun
 
11858
 
 
11859
 
 
11860
@node Grabbing a Key, Event Types, Grabbing the Keyboard, Events and Input
 
11861
@section Grabbing a Key
 
11862
 
 
11863
 
 
11864
The following paragraphs describe the functions used for passively
 
11865
grabbing and releasing the keyboard.
 
11866
 
 
11867
@defun grab-key window key &key (:modifiers 0) :owner-p :sync-pointer-p :sync-keyboard-p :time
 
11868
 
 
11869
@table @var
 
11870
@item window
 
11871
A @var{window}.
 
11872
@item key
 
11873
The key (type @var{card8}) to be grabbed or @var{:any}.
 
11874
@item :modifiers
 
11875
A @var{modifier-mask}.
 
11876
@item :owner-p
 
11877
If true, all client windows receive keyboard input normally.
 
11878
@item :sync-pointer-p
 
11879
Indicates whether the pointer is in synchronous or asynchronous mode.
 
11880
@item :sync-keyboard-p
 
11881
Indicates whether the keyboard is in synchronous or asynchronous mode.
 
11882
@item :time
 
11883
A @var{timestamp}.
 
11884
@end table
 
11885
 
 
11886
This request establishes a passive grab on the keyboard. If the
 
11887
specified @emph{key} (which can also be a modifier key) is pressed
 
11888
(whether or not any specified modifier keys are down), and either of
 
11889
the following is true:
 
11890
@itemize @bullet
 
11891
 
 
11892
@item
 
11893
@emph{window} is an ancestor of (or is) the focus window
 
11894
 
 
11895
@item
 
11896
@emph{window} is a descendant of the focus window and contains the
 
11897
pointer
 
11898
 
 
11899
@item
 
11900
These constraints are not satisfied for any ancestor of
 
11901
@emph{window}, then the following occurs:
 
11902
@itemize @bullet
 
11903
 
 
11904
@item
 
11905
The keyboard is actively grabbed as described in
 
11906
@var{grab-keyboard}
 
11907
 
 
11908
@item
 
11909
The last-keyboard-grab time is set to the time that the
 
11910
@emph{key} was pressed (as transmitted in the
 
11911
@var{:key-press} event)
 
11912
 
 
11913
@item
 
11914
The @var{:key-press} event is reported
 
11915
@end itemize
 
11916
@end itemize
 
11917
The interpretation of the remaining arguments is as for
 
11918
@var{grab-keyboard}. The active grab is terminated automatically when
 
11919
the specified @emph{key} has been released, independent of the state
 
11920
of the modifier keys.
 
11921
 
 
11922
A zero modifier mask is equivalent to issuing the request for all
 
11923
possible modifier combinations (including the combination of no
 
11924
modifiers). It is not required that all specified modifiers have
 
11925
currently assigned keycodes. A @emph{key} of @var{:any} is
 
11926
equivalent to issuing the request for all possible
 
11927
keycodes. Otherwise, the @emph{key} must be in the range specified
 
11928
by @var{display-min-keycode} and @var{display-max-keycode} in the
 
11929
connection setup.
 
11930
 
 
11931
 
 
11932
@end defun
 
11933
 
 
11934
 
 
11935
@defun ungrab-key window key &key (:modifiers 0)
 
11936
 
 
11937
@table @var
 
11938
@item window
 
11939
A @var{window}.
 
11940
@item key
 
11941
The key (type @var{card8}) to be released or @var{:any}.
 
11942
@item :modifiers
 
11943
A @var{modifier-mask}.
 
11944
@end table
 
11945
 
 
11946
Releases the @emph{key} combination on the specified @emph{window}
 
11947
if it was grabbed by this client. A zero modifier mask of
 
11948
@var{:any} is equivalent to issuing the request for all possible
 
11949
modifier combinations (including the combination of no modifiers). A
 
11950
@emph{key} of @var{:any} is equivalent to issuing the request for
 
11951
all possible keycodes. @var{ungrab-key} has no effect on an active
 
11952
grab.
 
11953
 
 
11954
 
 
11955
@end defun
 
11956
 
 
11957
 
 
11958
@node Event Types, Releasing Queued Events, Grabbing a Key, Events and Input
 
11959
@section Event Types
 
11960
 
 
11961
 
 
11962
The following paragraphs contain detailed descriptions of the contents
 
11963
of each event type. In CLX, events are not actually represented by
 
11964
structures, but rather by lists of keyword values passed to handler
 
11965
functions or by values bound to symbols within the clauses of
 
11966
@var{event-case} and @var{event-cond} forms. Nevertheless, it is
 
11967
convenient to describe event contents in terms of slots and to
 
11968
identify the components of events with slot name symbols. In fact, CLX
 
11969
uses the @var{declare-event} macro to define event slot symbols and to
 
11970
map these symbols to specific event data items returned by the X
 
11971
server (@pxref{Declaring Event Types}).
 
11972
 
 
11973
The following paragraphs describe each event type, listing its
 
11974
@var{event-key} keyword symbol and its slot name symbols. An event
 
11975
keyword symbol identifies a specific event type.  An event keyword
 
11976
symbol can be given as an argument to @var{send-event} or to an event
 
11977
handler function; it can also appear in the @emph{event-match} form of
 
11978
an @var{event-case} clause. An event slot name symbol identifies a
 
11979
specific event data item. Event slot names appear as keywords with
 
11980
associated values among the arguments passed to @var{send-event} or to
 
11981
an event handler function; as non-keyword symbols, they can also be in
 
11982
the @emph{event-slots} form of an @var{event-case} clause.
 
11983
 
 
11984
In certain cases, more than one name symbol is defined for the same
 
11985
event slot. For example, in @var{:key-press} events, the symbols
 
11986
@emph{window} and @emph{event-window} both refer to the same event data
 
11987
item.
 
11988
 
 
11989
@menu
 
11990
* Keyboard and Pointer Events::
 
11991
* Input Focus Events::
 
11992
* Keyboard and Pointer State Events::
 
11993
* Exposure Events::
 
11994
* Window State Events::
 
11995
* Structure Control Events::
 
11996
* Client Communications Events::
 
11997
* Declaring Event Types::
 
11998
@end menu
 
11999
 
 
12000
@node Keyboard and Pointer Events, Input Focus Events, Event Types, Event Types
 
12001
@subsection Keyboard and Pointer Events
 
12002
 
 
12003
 
 
12004
The keyboard and pointer events are: @var{:key-press} @var{:key-release},
 
12005
@var{:button-press}, @var{:button-release}, @var{:motion-notify},
 
12006
@var{:enter-notify}, and @var{:leave-notify}.
 
12007
 
 
12008
@deftp {Event Type} :key-press
 
12009
@deftpx {Event Type} :key-release
 
12010
@deftpx {Event Type} :button-press
 
12011
@deftpx {Event Type} :button-release
 
12012
 
 
12013
Selected by @var{:key-press}, @var{:key-release}, @var{:button-press},
 
12014
or @var{:button-release}.
 
12015
 
 
12016
@var{:key-press}, and @var{:key-release} events are generated when
 
12017
a key or pointer button changes state. Note that @var{:key-press}
 
12018
and @var{:key-release} are generated for all keys, even those
 
12019
mapped to modifiers. All of these event types have the same
 
12020
slots. The window containing the pointer at the time of the event is
 
12021
referred to as the @emph{source} window. The @emph{event}
 
12022
@emph{window} is the window to which the event is actually
 
12023
reported. The event window is found by starting with the source
 
12024
window and looking up the hierarchy for the first window on which
 
12025
any client has selected interest in the event (provided no
 
12026
intervening window prohibits event generation by including the event
 
12027
type in its do-not-propagate-mask). The actual window used for
 
12028
reporting can be modified by active grabs and, in the case of
 
12029
keyboard events, can be modified by the focus window.
 
12030
 
 
12031
A @var{:button-press} event has the effect of a temporary
 
12032
@var{grab-button}. When a pointer button is pressed and no active
 
12033
pointer grab is in progress, the ancestors of the source window are
 
12034
searched from the @emph{root} down, looking for a passive grab to
 
12035
activate. If no matching passive grab on the button exists, then an
 
12036
active grab is started automatically for the client receiving the
 
12037
@var{:button-press} event, and the last-pointer-grab time is set to
 
12038
the current server time. The effect is essentially equivalent to
 
12039
calling @var{grab-button} with the following arguments:
 
12040
 
 
12041
@table @var
 
12042
@item @emph{window}
 
12043
The event window.
 
12044
@item @emph{button}
 
12045
The button that was pressed.
 
12046
@item @emph{event-mask}
 
12047
The client's selected pointer events on the event window.
 
12048
@item @var{:modifiers}
 
12049
0
 
12050
@item @var{:owner-p}
 
12051
@var{t} if the client has @var{:owner-grab-button} selected on the event window; otherwise @var{nil}.
 
12052
@item @var{:sync-pointer-p}
 
12053
@var{nil}
 
12054
@item @var{:sync-keyboard-p}
 
12055
@var{nil}
 
12056
@item @var{:confine-to}
 
12057
@var{nil}
 
12058
@item @var{:cursor}
 
12059
@var{nil}
 
12060
@end table
 
12061
 
 
12062
 
 
12063
The @var{:button-press} grab is terminated automatically when all
 
12064
buttons are released. The functions @var{ungrab-pointer} and
 
12065
@var{change-active-pointer-grab} can both be used to modify the
 
12066
@var{:button-press} grab.
 
12067
 
 
12068
@table @var
 
12069
@item window
 
12070
@item event-window
 
12071
Type @var{window}.
 
12072
 
 
12073
The window receiving the event.
 
12074
 
 
12075
@item code
 
12076
Type @var{card8}.
 
12077
 
 
12078
The @emph{code} argument varies with the event type. For @var{:key-press} and
 
12079
@var{:key-release}, @emph{code} is the keycode (@pxref{Keyboard Encodings}). For
 
12080
@var{:button-press} and @var{:button-release}, @emph{code} is the pointer button number.
 
12081
 
 
12082
@item x
 
12083
Type @var{int16}.
 
12084
 
 
12085
If @emph{event-window} is on the same screen as root, then @emph{x} and @emph{y} are the pointer
 
12086
coordinates relative to the @emph{event-window}; otherwise @emph{x} and @emph{y} are zero.
 
12087
 
 
12088
@item y
 
12089
Type @var{int16}.
 
12090
 
 
12091
If @emph{event-window} is on the same screen as root, then @emph{x} and @emph{y} are the pointer
 
12092
coordinates relative to the @emph{event-window}; otherwise @emph{x} and @emph{y} are zero.
 
12093
 
 
12094
@item state
 
12095
Type @var{card16}.
 
12096
 
 
12097
A mask that gives the state of the buttons and modifier keys just before the
 
12098
event.
 
12099
 
 
12100
@item time
 
12101
Type @var{card32}.
 
12102
 
 
12103
A timestamp for the moment when the event occurred.
 
12104
 
 
12105
@item root
 
12106
Type @var{window}.
 
12107
 
 
12108
The root window of the source window.
 
12109
 
 
12110
@item root-x
 
12111
Type @var{int16}.
 
12112
 
 
12113
The x coordinate of the pointer position relative to root at the time of the event.
 
12114
 
 
12115
@item root-y
 
12116
Type @var{int16}.
 
12117
 
 
12118
The y coordinate of the pointer position relative to root at the time of the event@emph{.}
 
12119
 
 
12120
@item child
 
12121
Type (@var{or null window}).
 
12122
 
 
12123
If the source window is an inferior of the @emph{event-window}, @emph{child} is set to the child
 
12124
of @emph{event-window} that is an ancestor of (or is) the source window; otherwise, it is
 
12125
set to @var{nil}@emph{.}
 
12126
 
 
12127
@item same-screen-p
 
12128
Type @var{boolean}.
 
12129
 
 
12130
True if @emph{event-window} and root are on the same screen.
 
12131
@end table
 
12132
 
 
12133
@end deftp
 
12134
 
 
12135
 
 
12136
@deftp {Event Type} :motion-notify
 
12137
 
 
12138
Selected by: @var{:button-1-motion}, @var{:button-2-motion},
 
12139
@var{:button-3-motion}, @var{:button-4-motion},
 
12140
@var{:button-5-motion}, @var{:button-motion}, or
 
12141
@var{:pointer-motion}.
 
12142
 
 
12143
 
 
12144
The @var{:motion-notify} event is generated when the pointer
 
12145
moves. A @var{:motion-notify} event has the same slots as
 
12146
@var{:button-press} @var{:button-release}, @var{:key-press}, and
 
12147
@var{:key-release} events, with the exception that the @emph{code}
 
12148
slot is replaced by the @emph{hint-p} slot. As with these other
 
12149
events, the event window for @var{:motion-notify} is found by
 
12150
starting with the source window and looking up the hierarchy for the
 
12151
first window on which any client has selected interest in the event
 
12152
(provided no intervening window prohibits event generation by
 
12153
including @var{:motion-notify} in its do-not-propagate-mask).The
 
12154
actual window used for reporting can be modified by active grabs.
 
12155
 
 
12156
@var{:motion-notify} events are generated only when the motion
 
12157
begins and ends in the window. The granularity of motion events is
 
12158
not guaranteed, but a client selecting for motion events is
 
12159
guaranteed to get at least one event when the pointer moves and
 
12160
comes to rest. Selecting @var{:pointer-motion} generates
 
12161
@var{:motion-notify} events regardless of the state of the pointer
 
12162
buttons. By selecting some subset of @var{:button[1-5]-motion}
 
12163
instead, @var{:motion-notify} events are only received when one or
 
12164
more of the specified buttons are pressed. By selecting
 
12165
@var{:button-motion}, @var{:motion-notify} events are only
 
12166
received when at least one button is pressed. If
 
12167
@var{:pointer-motion-hint} is also selected, the server is free to
 
12168
send only one @var{:motion-notify}, until either the key or button
 
12169
state changes, the pointer leaves the event window, or the client
 
12170
calls @var{query-pointer} or @var{motion-events}.
 
12171
 
 
12172
@table @var
 
12173
@item hint-p
 
12174
Type @var{boolean}.
 
12175
 
 
12176
True if the event is a hint generated by selecting @var{:pointer-motion-hint}.
 
12177
@end table
 
12178
 
 
12179
@end deftp
 
12180
 
 
12181
 
 
12182
 
 
12183
@deftp {Event Type} :enter-notify
 
12184
@deftpx {Event Type} :leave-notify
 
12185
@anchor{:enter-notify}
 
12186
 
 
12187
Selected by: @var{:enter-window} or @var{:leave-window}.
 
12188
 
 
12189
If pointer motion or a window hierarchy change causes the pointer to
 
12190
be in a different window than before, @var{:enter-notify} and
 
12191
@var{:leave-notify} events are generated instead of a
 
12192
@var{:motion-notify} event. All @var{:enter-notify} and
 
12193
@var{:leave-notify} events caused by a hierarchy change are
 
12194
generated after any hierarchy event (@var{:unmap-notify},
 
12195
@var{:map-notify}, @var{:configure-notify},
 
12196
@var{:gravity-notify}, or @var{:circulate-notify}) caused by that
 
12197
change, but the ordering of @var{:enter-notify} and
 
12198
@var{:leave-notify} events with respect to @var{:focus-out},
 
12199
@var{:visibility-notify}, and @var{:exposure} events is not
 
12200
constrained by the X protocol. An @var{:enter-notify} or
 
12201
@var{:leave-notify} event can also be generated when a client
 
12202
application calls @var{change-active-pointer-grab},
 
12203
@var{grab-pointer}, or @var{ungrab-pointer}.
 
12204
 
 
12205
@table @var
 
12206
@item window
 
12207
@itemx event-window
 
12208
Type @var{window}.
 
12209
 
 
12210
The window receiving the event.
 
12211
 
 
12212
@item x
 
12213
Type @var{int16}.
 
12214
 
 
12215
The final pointer position. If @emph{event-window} is on the same screen as root, then @emph{x}
 
12216
and @emph{y} are the pointer coordinates relative to the @emph{event-window}; otherwise @emph{x} and
 
12217
@emph{y} are zero.
 
12218
 
 
12219
@item y
 
12220
Type @var{int16}.
 
12221
 
 
12222
The final pointer position. If @emph{event-window} is on the same screen as root, then @emph{x}
 
12223
and @emph{y} are the pointer coordinates relative to the @emph{event-window}; otherwise @emph{x} and
 
12224
@emph{y} are zero.
 
12225
 
 
12226
@item mode
 
12227
Type (@var{member :normal :grab :ungrab}).
 
12228
 
 
12229
Events caused when the pointer is actively grabbed have mode @var{:grab}. Events
 
12230
caused when an active pointer grab deactivates have mode @var{:ungrab}. In all
 
12231
other cases, mode is @var{:normal}.
 
12232
 
 
12233
@item kind
 
12234
Type (@var{member :ancestor :virtual :inferior :nonlinear} @var{:nonlinear-virtual}).
 
12235
 
 
12236
When the pointer moves from window A to window B, and A is an inferior of
 
12237
B:
 
12238
@itemize @bullet
 
12239
 
 
12240
@item
 
12241
@var{:leave-notify} with @emph{kind} @var{:ancestor} is generated on A
 
12242
 
 
12243
@item
 
12244
@var{:leave-notify} with @emph{kind} @var{:virtual} is generated on each window between A
 
12245
and B exclusive (in that order)
 
12246
 
 
12247
@item
 
12248
@var{:enter-notify} with @emph{kind} @var{:inferior} is generated on B
 
12249
@end itemize
 
12250
 
 
12251
When the pointer moves from window A to window B, and
 
12252
B is an inferior of A:
 
12253
@itemize @bullet
 
12254
 
 
12255
@item
 
12256
@var{:leave-notify} with @emph{kind} @var{:inferior} is generated on A
 
12257
 
 
12258
@item
 
12259
@var{:enter-notify} with @emph{kind}
 
12260
@var{:virtual} is generated on each window between
 
12261
A and B exclusive (in that order)
 
12262
 
 
12263
@item
 
12264
@var{:enter-notify} with @emph{kind} @var{:ancestor} is generated on B
 
12265
@end itemize
 
12266
 
 
12267
When the pointer moves from window A to window B, with
 
12268
window C being their least common ancestor:
 
12269
@itemize @bullet
 
12270
 
 
12271
@item
 
12272
@var{:leave-notify} with @emph{kind} @var{:nonlinear} is generated on A
 
12273
 
 
12274
@item
 
12275
@var{:leave-notify} with @emph{kind}
 
12276
@var{:nonlinear-virtual} is generated on each
 
12277
window between A and C exclusive (in that order)
 
12278
 
 
12279
@item
 
12280
@var{:enter-notify} with @emph{kind}
 
12281
@var{:nonlinear-virtual} is generated on each
 
12282
window between C and B exclusive (in that order)
 
12283
 
 
12284
@item
 
12285
@var{:enter-notify} with @emph{kind}
 
12286
@var{:nonlinear} is generated on B
 
12287
@end itemize
 
12288
 
 
12289
When the pointer moves from window A to window B, on different screens:
 
12290
@itemize @bullet
 
12291
 
 
12292
@item
 
12293
@var{:leave-notify} with @emph{kind} @var{:nonlinear} is generated on A
 
12294
 
 
12295
@item
 
12296
If A is not a root window, @var{:leave-notify} with @emph{kind} @var{:nonlinear-virtual} is
 
12297
generated on each window above A up to and including its root (in order)
 
12298
 
 
12299
@item
 
12300
If B is not a root window, @var{:enter-notify} with
 
12301
@emph{kind} @var{:nonlinear-virtual} is generated
 
12302
on each window from B's root down to but not
 
12303
including B (in order)
 
12304
 
 
12305
@item
 
12306
@var{:enter-notify} with @emph{kind} @var{:nonlinear} is generated on B
 
12307
@end itemize
 
12308
 
 
12309
When a pointer grab activates (but after any initial warp into a
 
12310
confine-to window, and before generating any actual
 
12311
@var{:button-press} event that activates the grab), with
 
12312
@emph{G} the @var{grab-window} for the grab and @emph{P} the
 
12313
window the pointer is in, then @var{:enter-notify} and
 
12314
@var{:leave-notify} events with mode @var{:grab} are generated
 
12315
(as for @var{:normal} above) as if the pointer were to suddenly
 
12316
warp from its current position in @emph{P} to some position in
 
12317
@emph{G}. However, the pointer does not warp, and the pointer
 
12318
position is used as both the @emph{initial} and @emph{final}
 
12319
positions for the events.
 
12320
 
 
12321
When a pointer grab deactivates (but after generating any actual
 
12322
@var{:button-release} event that deactivates the grab), with
 
12323
@emph{G} the @var{grab-window} for the grab and @emph{P} the
 
12324
window the pointer is in, then @var{:enter-notify} and
 
12325
@var{:leave-notify} events with mode @var{:ungrab} are
 
12326
generated (as for @var{:normal} above) as if the pointer were
 
12327
to suddenly warp from from some position in @emph{G} to its
 
12328
current position in @emph{P}.  However, the pointer does not
 
12329
warp, and the current pointer position is used as both the
 
12330
@emph{initial} and @emph{final} positions for the events.
 
12331
 
 
12332
@item focus-p
 
12333
Type @var{boolean}.
 
12334
 
 
12335
If @emph{event-window} is the focus window or an inferior of the focus window, then
 
12336
@emph{focus-p} is @var{t}; otherwise, @emph{focus-p} is @var{nil}.
 
12337
 
 
12338
@item state
 
12339
Type @var{card16}.
 
12340
 
 
12341
A mask that gives the state of the buttons and modifier keys just before the
 
12342
event.
 
12343
 
 
12344
@item time
 
12345
Type @var{card32}.
 
12346
 
 
12347
A timestamp for the moment when the event occurred.
 
12348
 
 
12349
@item root
 
12350
Type @var{window}.
 
12351
 
 
12352
The root window containing the final pointer position.
 
12353
 
 
12354
@item root-x
 
12355
Type @var{int16}.
 
12356
 
 
12357
The x coordinate of the pointer position relative to root at the time of the event.
 
12358
 
 
12359
@item root-y
 
12360
Type @var{int16}.
 
12361
 
 
12362
The y coordinate of the pointer position relative to root at the time of the event.
 
12363
 
 
12364
@item child
 
12365
Type (@var{or null window}).
 
12366
 
 
12367
In a @var{:leave-notify} event, if a child of the @emph{event-window} contains the initial
 
12368
position of the pointer, the @emph{child} slot is set to that child; otherwise, the @emph{child} slot is
 
12369
@var{nil}. For an @var{:enter-notify} event, if a child of the @emph{event-window} contains the final
 
12370
pointer position, the @emph{child} slot is set to that child; otherwise, the @emph{child} slot is @var{nil}.
 
12371
 
 
12372
@item same-screen-p
 
12373
Type @var{boolean}.
 
12374
 
 
12375
True if @emph{event-window} and root are on the same screen.
 
12376
@end table
 
12377
 
 
12378
@end deftp
 
12379
 
 
12380
 
 
12381
@node Input Focus Events, Keyboard and Pointer State Events, Keyboard and Pointer Events, Event Types
 
12382
@subsection Input Focus Events
 
12383
 
 
12384
 
 
12385
The input focus events are @var{:focus-in} and @var{:focus-out}.
 
12386
 
 
12387
@deftp {Event Type} :focus-in
 
12388
@deftpx {Event Type} :focus-out
 
12389
 
 
12390
Selected by: @var{:focus-change}.
 
12391
 
 
12392
@var{:focus-in} and @var{:focus-out} events are generated when the
 
12393
input focus changes. All @var{:focus-out} events caused by a window
 
12394
@var{:unmap} are generated after any @var{:unmap-notify} event,
 
12395
but the ordering of @var{:focus-out} with respect to generated
 
12396
@var{:enter-notify}, @var{:leave-notify},
 
12397
@var{:visibility-notify}, and @var{:expose} events is not
 
12398
constrained.
 
12399
 
 
12400
@table @var
 
12401
@item window
 
12402
@itemx event-window
 
12403
Type @var{window}.
 
12404
 
 
12405
For @var{:focus-in}, the new input focus window. For @var{:focus-out}, the previous input
 
12406
focus window.
 
12407
 
 
12408
@item mode
 
12409
Type @code{(member :normal :while-grabbed :grab :ungrab)}.
 
12410
 
 
12411
Events generated by @var{set-input-focus} when the keyboard is not grabbed have
 
12412
mode @var{:normal}. Events generated by @var{set-input-focus} when the keyboard is
 
12413
grabbed have mode @var{:while-grabbed}. Events generated when a keyboard grab
 
12414
activates have mode @var{:grab}, and events generated when a keyboard grab
 
12415
deactivates have mode @var{:ungrab}.
 
12416
 
 
12417
@item kind
 
12418
Type (@var{member :ancestor :virtual :inferior :nonlinear :nonlinear-virtual :pointer :pointer-root :none}).
 
12419
 
 
12420
When the focus moves from window A to window B, and A is an inferior of B,
 
12421
with the pointer in window P:
 
12422
@itemize @bullet
 
12423
 
 
12424
@item
 
12425
@var{:focus-out} with @emph{kind} @var{:ancestor} is
 
12426
generated on A
 
12427
 
 
12428
@item
 
12429
@var{:focus-out} with @emph{kind} @var{:virtual} is
 
12430
generated on each window between A and B exclusive (in that
 
12431
order)
 
12432
 
 
12433
@item
 
12434
@var{:focus-in} with @emph{kind} @var{:inferior} is
 
12435
generated on B
 
12436
 
 
12437
@item
 
12438
If P is an inferior of B, but P is not A or an inferior of
 
12439
A or an ancestor of A, @var{:focus-in} with @emph{kind}
 
12440
@var{:pointer} is generated on each window below B down
 
12441
to and including P (in order)
 
12442
@end itemize
 
12443
 
 
12444
When the focus moves from window A to window B, and B is an inferior of A,
 
12445
with the pointer in window P:
 
12446
@itemize @bullet
 
12447
 
 
12448
@item
 
12449
If P is an inferior of A, but P is not A or an inferior of
 
12450
B or an ancestor of B, @var{:focus-out} with @emph{kind}
 
12451
@var{:pointer} is generated on each window from P up to
 
12452
but not including A (in order)
 
12453
 
 
12454
@item
 
12455
@var{:focus-out} with @emph{kind} @var{:inferior} is
 
12456
generated on A
 
12457
 
 
12458
@item
 
12459
@var{:focus-in} with @emph{kind} @var{:virtual} is
 
12460
generated on each window between A and B exclusive (in
 
12461
that order)
 
12462
 
 
12463
@item
 
12464
@var{:focus-in} with @emph{kind} @var{:ancestor} is
 
12465
generated on B
 
12466
@end itemize
 
12467
 
 
12468
When the focus moves from window A to window B, with window C being
 
12469
their least common ancestor, and with the pointer in window P:
 
12470
@itemize @bullet
 
12471
 
 
12472
@item
 
12473
If P is an inferior of A, @var{:focus-out} with
 
12474
@emph{kind} @var{:pointer} is generated on each window
 
12475
from P up to but not including A (in order)
 
12476
 
 
12477
@item
 
12478
@var{:focus-out} with @emph{kind} @var{:nonlinear} is
 
12479
generated on A
 
12480
 
 
12481
@item
 
12482
@var{:focus-out} with @emph{kind}
 
12483
@var{:nonlinear-virtual} is generated on each window
 
12484
between A and C exclusive (in that order)
 
12485
 
 
12486
@item
 
12487
@var{:focus-in} with @emph{kind}
 
12488
@var{:nonlinear-virtual} is generated on each window
 
12489
between C and B exclusive (in that order)
 
12490
 
 
12491
@item
 
12492
:focus-in with @emph{kind} @var{:nonlinear} is generated
 
12493
on B
 
12494
 
 
12495
@item
 
12496
If P is an inferior of B, @var{:focus-in} with
 
12497
@emph{kind} @var{:pointer} is generated on each window
 
12498
below B down to and including P (in order)
 
12499
@end itemize
 
12500
 
 
12501
When the focus moves from window A to window B, on different
 
12502
screens, with the pointer in window P:
 
12503
@itemize @bullet
 
12504
 
 
12505
@item
 
12506
If P is an inferior of A, @var{:focus-out} with
 
12507
@emph{kind} @var{:pointer} is generated on each window
 
12508
from P up to but not including A (in order)
 
12509
 
 
12510
@item
 
12511
@var{:focus-out} with @emph{kind} @var{:nonlinear} is
 
12512
generated on A
 
12513
 
 
12514
@item
 
12515
If A is not a root window, @var{:focus-out} with
 
12516
@emph{kind} @var{:nonlinear-virtual} is generated on each
 
12517
window above A up to and including its root (in order)
 
12518
 
 
12519
@item
 
12520
If B is not a root window, @var{:focus-in} with
 
12521
@emph{kind} @var{:nonlinear-virtual} is generated on each
 
12522
window from B's root down to but not including B (in
 
12523
order)
 
12524
 
 
12525
@item
 
12526
@var{:focus-in} with @emph{kind} @var{:nonlinear} is
 
12527
generated on B
 
12528
 
 
12529
@item
 
12530
If P is an inferior of B, @var{:focus-in} with
 
12531
@emph{kind} @var{:pointer} is generated on each window
 
12532
below B down to and including P (in order)
 
12533
@end itemize
 
12534
 
 
12535
When the focus moves from window A to @var{:pointer-root}
 
12536
(or @var{:none}), with the pointer in window P:
 
12537
@itemize @bullet
 
12538
 
 
12539
@item
 
12540
If P is an inferior of A, @var{:focus-out} with
 
12541
@emph{kind} @var{:pointer} is generated on each window
 
12542
from P up to but not including A (in order)
 
12543
 
 
12544
@item
 
12545
@var{:focus-out} with @emph{kind} @var{:nonlinear} is
 
12546
generated on A
 
12547
 
 
12548
@item
 
12549
If A is not a root window, @var{:focus-out} with
 
12550
@emph{kind} @var{:nonlinear-virtual} is generated on each
 
12551
window above A up to and including its root (in order)
 
12552
 
 
12553
@item
 
12554
@var{:focus-in} with @emph{kind} @var{:pointer-root} (or
 
12555
@var{:none}) is generated on all root windows
 
12556
 
 
12557
@item
 
12558
If the new focus is @var{:pointer-root}, @var{:focus-in}
 
12559
with @emph{kind} @var{:pointer} is generated on each
 
12560
window from P's root down to and including P (in order)
 
12561
@end itemize
 
12562
 
 
12563
When the focus moves from @var{:pointer-root} (or
 
12564
@var{:none}) to window A, with the pointer in window P:
 
12565
@itemize @bullet
 
12566
 
 
12567
@item
 
12568
If the old focus is @var{:pointer-root},
 
12569
@var{:focus-out} with @emph{kind} @var{:pointer} is
 
12570
generated on each window from P up to and including P's
 
12571
root (in order)
 
12572
 
 
12573
@item
 
12574
@var{:focus-out} with @emph{kind} @var{:pointer-root}
 
12575
(or @var{:none}) is generated on all root windows
 
12576
 
 
12577
@item
 
12578
If A is not a root window, @var{:focus-in} with
 
12579
@emph{kind} @var{:nonlinear-virtual} is generated on each
 
12580
window from A's root down to but not including A (in
 
12581
order)
 
12582
 
 
12583
@item
 
12584
@var{:focus-in} with @emph{kind} @var{:nonlinear} is
 
12585
generated on A
 
12586
 
 
12587
@item
 
12588
If P is an inferior of A, @var{:focus-in} with
 
12589
@emph{kind} @var{:pointer} is generated on each window
 
12590
below A down to and including P (in order)
 
12591
@end itemize
 
12592
 
 
12593
When the focus moves from @var{:pointer-root} to
 
12594
@var{:none} (or vice versa), with the pointer in window P:
 
12595
@itemize @bullet
 
12596
 
 
12597
@item
 
12598
If the old focus is @var{:pointer-root},
 
12599
@var{:focus-out} with @emph{kind} @var{:pointer} is
 
12600
generated on each window from P up to and including P's
 
12601
root (in order)
 
12602
 
 
12603
@item
 
12604
@var{:focus-out} with @emph{kind} @var{:pointer-root}
 
12605
(or @var{:none}) is generated on all root windows
 
12606
 
 
12607
@item
 
12608
@var{:focus-in} with @emph{kind} @var{:none} (or
 
12609
@var{:pointer-root}) is generated on all root windows
 
12610
 
 
12611
@item
 
12612
If the new focus is @var{:pointer-root}, @var{:focus-in}
 
12613
with @emph{kind} @var{:pointer} is generated on each
 
12614
window from P's root down to and including P (in order)
 
12615
@end itemize
 
12616
@end table
 
12617
 
 
12618
 
 
12619
When a keyboard grab activates (but before generating any actual
 
12620
@var{:key-press} event that activates the grab), with @emph{G}
 
12621
the @var{grab-window} for the grab and @emph{F} the current
 
12622
focus, then @var{:focus-in} and @var{:focus-out} events with
 
12623
mode @var{:grab} are generated (as for @var{:normal} above) as
 
12624
if the focus were to change from @emph{F} to @emph{G}.
 
12625
 
 
12626
When a keyboard grab deactivates (but after generating any
 
12627
actual @var{:key-release} event that deactivates the grab),
 
12628
with @emph{G} the @var{grab-window} for the grab and @emph{F}
 
12629
the current focus, then @var{:focus-in} and @var{:focus-out}
 
12630
events with mode @var{:ungrab} are generated (as for
 
12631
@var{:normal} above) as if the focus were to change from
 
12632
@emph{G} to @emph{F}.
 
12633
@end deftp
 
12634
 
 
12635
@node Keyboard and Pointer State Events, Exposure Events, Input Focus Events, Event Types
 
12636
@subsection Keyboard and Pointer State Events
 
12637
 
 
12638
 
 
12639
The keyboard and pointer state events are @var{:keymap-notify} and @var{:mapping-notify}.
 
12640
 
 
12641
@deftp {Event Type} :keymap-notify
 
12642
 
 
12643
 
 
12644
Selected by: @var{:keymap-state}.
 
12645
 
 
12646
The @var{:keymap-notify} event returns the current state of the
 
12647
keyboard. @var{:keymap-notify} is generated immediately after every
 
12648
@var{:enter-notify} and @var{:focus-in}.
 
12649
 
 
12650
@table @var
 
12651
@item window
 
12652
@itemx event-window
 
12653
Type @var{window}.
 
12654
 
 
12655
The window receiving an @var{:enter-notify} or @var{:focus-in} event.
 
12656
 
 
12657
@item keymap
 
12658
Type (@var{bit-vector 256}).
 
12659
 
 
12660
A bit-vector containing the logical state of the keyboard. Each bit set to 1
 
12661
indicates that the corresponding key is currently pressed. The vector is represented
 
12662
as 32 bytes. For @emph{n} from 0 to 7, byte @emph{n} (from 0) contains the bits for keys 8@emph{n} to
 
12663
8@emph{n}+7, with the least significant bit in the byte representing key 8@emph{n}.
 
12664
@end table
 
12665
 
 
12666
@end deftp
 
12667
 
 
12668
 
 
12669
@deftp {Event Type} :mapping-notify
 
12670
 
 
12671
The X server reports @var{:mapping-notify} events to all
 
12672
clients. There is no mechanism to express disinterest in this
 
12673
event. The X server generates this event type whenever a client
 
12674
application calls one of the following:
 
12675
@itemize @bullet
 
12676
 
 
12677
@item
 
12678
@var{set-modifier-mapping} to indicate which keycodes to use as
 
12679
modifiers (the status reply must be @var{:mapping-success})
 
12680
 
 
12681
@item
 
12682
@var{change-keyboard-mapping} to change the keyboard mapping
 
12683
 
 
12684
@item
 
12685
@var{set-pointer-mapping} to set the pointer mapping (the status
 
12686
reply must be @var{:mapping-success})
 
12687
@end itemize
 
12688
 
 
12689
@table @var
 
12690
@item request
 
12691
Type (@code{member :modifier :keyboard :pointer}).
 
12692
 
 
12693
Indicates the kind of change that occurred--@var{:modifier} for a successful
 
12694
@var{set-modifier-mapping}, @var{:keyboard} for a successful @var{change-keyboard-mapping},
 
12695
and @var{:pointer} for a successful @var{set-pointer-mapping}.
 
12696
 
 
12697
@item start
 
12698
Type @var{card8}.
 
12699
 
 
12700
If request is @var{:keyboard}, then @emph{start} and @emph{count} indicate the range of altered
 
12701
keycodes.
 
12702
 
 
12703
@item count
 
12704
Type @var{card8}.
 
12705
 
 
12706
If request is @var{:keyboard}, then @emph{start} and @emph{count} indicate the range of altered
 
12707
keycodes.
 
12708
@end table
 
12709
@end deftp
 
12710
 
 
12711
 
 
12712
@node Exposure Events, Window State Events, Keyboard and Pointer State Events, Event Types
 
12713
@subsection Exposure Events
 
12714
 
 
12715
 
 
12716
The X server cannot guarantee that a window's content is preserved when
 
12717
the window is obscured or reconfigured. X requires client applications
 
12718
to be capable of restoring the contents of a previously-invisible window
 
12719
region whenever it is exposed.  Therefore, the X server sends events
 
12720
describing the exposed window and its exposed region. For a simple
 
12721
window, a client can choose to redraw the entire content whenever any
 
12722
region is exposed. For a complex window, a client can redraw only the
 
12723
exposed region.
 
12724
 
 
12725
@deftp {Event Type} :exposure
 
12726
@anchor{:exposure}
 
12727
 
 
12728
Selected by: @var{:exposure}.
 
12729
 
 
12730
An @var{:exposure} event is sent when redisplay is needed for a
 
12731
window region whose content has been lost. Redisplay is needed
 
12732
when one of the following occurs:
 
12733
@itemize @bullet
 
12734
 
 
12735
@item
 
12736
A region is exposed for a window and the X server has no backing
 
12737
store for the region
 
12738
 
 
12739
@item
 
12740
A region of a viewable window is obscured and the X server
 
12741
begins to honor the window's backing-store attribute of
 
12742
@var{:always} or @var{:when-mapped}
 
12743
 
 
12744
@item
 
12745
The X server begins to honor an unviewable window's
 
12746
backing-store attribute of @var{:always} or
 
12747
@var{:when-mapped}.
 
12748
@end itemize
 
12749
 
 
12750
The regions needing redisplay are decomposed into an arbitrary set
 
12751
of rectangles, and an @var{:exposure} event is generated for each
 
12752
rectangle. For a given action causing @var{:exposure} events, the
 
12753
set of events for a given window are guaranteed to be reported
 
12754
contiguously.
 
12755
 
 
12756
@var{:exposure} events are never generated for @var{:input-only}
 
12757
windows.
 
12758
 
 
12759
All @var{:exposure} events caused by a hierarchy change are
 
12760
generated after any hierarchy event (@var{:unmap-notify},
 
12761
@var{:map-notify},
 
12762
@var{:configure-notify},@var{:gravity-notify}, or
 
12763
@var{:circulate-notify}) caused by that change. All
 
12764
@var{:exposure} events on a given window are generated after any
 
12765
@var{:visibility-notify} event on that window, but it is not
 
12766
required that all @var{:exposure} events on all windows be
 
12767
generated after all visibility events on all windows. The ordering
 
12768
of @var{:exposure} events with respect to @var{:focus-out},
 
12769
@var{:enter-notify}, and @var{:leave-notify} events is not
 
12770
constrained.
 
12771
 
 
12772
@table @var
 
12773
@item window
 
12774
@itemx event-window
 
12775
Type @var{window}.
 
12776
 
 
12777
The window needing redisplay.
 
12778
 
 
12779
@item x
 
12780
Type @var{card16}.
 
12781
 
 
12782
The position of the left edge of the region to redisplay, relative to the
 
12783
@emph{event-window}.
 
12784
 
 
12785
@item y
 
12786
Type @var{card16}.
 
12787
 
 
12788
The position of the top edge of the region to redisplay, relative to the
 
12789
@emph{event-window}.
 
12790
 
 
12791
@item width
 
12792
Type @var{card16}.
 
12793
 
 
12794
The width of the region to redisplay.
 
12795
 
 
12796
@item height
 
12797
Type @var{card16}.
 
12798
 
 
12799
The height of the region to redisplay.
 
12800
 
 
12801
@item count
 
12802
Type @var{card16}.
 
12803
 
 
12804
If count is zero, then no more @var{:exposure} events for this window follow. If
 
12805
count is nonzero, then at least that many more @var{:exposure} events for this
 
12806
window follow (and possibly more).
 
12807
@end table
 
12808
 
 
12809
@end deftp
 
12810
 
 
12811
 
 
12812
@deftp {Event Type} :graphics-exposure
 
12813
 
 
12814
A @var{:graphics-exposure} event is generated by a call to
 
12815
@var{copy-area} or @var{copy-plane} when the exposures attribute
 
12816
of the graphics context is @var{:on}. A @var{:graphics-exposure}
 
12817
event reports a destination region whose content cannot be computed
 
12818
because the content of the corresponding source region has been
 
12819
lost. For example, the missing source region may be obscured or may
 
12820
lie outside the current source drawable size. For a given action
 
12821
causing @var{:graphics-exposure} events, the set of events for a
 
12822
given destination are guaranteed to be reported contiguously.
 
12823
 
 
12824
@table @var
 
12825
@item drawable
 
12826
@itemx event-window
 
12827
Type @var{drawable}.
 
12828
 
 
12829
The destination drawable for the @var{copy-area} or @var{copy-plane} function.
 
12830
 
 
12831
@item x
 
12832
Type @var{card16}.
 
12833
 
 
12834
The position of the left edge of the destination region, relative to the @emph{drawable}.
 
12835
 
 
12836
@item y
 
12837
Type @var{card16}.
 
12838
 
 
12839
The position of the top edge of the destination region, relative to the @emph{drawable}.
 
12840
 
 
12841
@item width
 
12842
Type @var{card16}.
 
12843
 
 
12844
The width of the destination region.
 
12845
 
 
12846
@item height
 
12847
Type @var{card16}.
 
12848
 
 
12849
The height of the destination region.
 
12850
 
 
12851
@item count
 
12852
Type @var{card16}.
 
12853
 
 
12854
If count is zero then no more @var{:graphics-exposure} events for the @emph{drawable}
 
12855
follow. If count is nonzero then at least that many more @var{:graphics-exposure}
 
12856
events for the @emph{drawable} follow (and possibly more).
 
12857
 
 
12858
@item major
 
12859
Type @var{card8}.
 
12860
 
 
12861
The major opcode for the graphics request generating the event
 
12862
(62 for @var{copy-area}, 63 for @var{copy-plane}).
 
12863
 
 
12864
@item minor
 
12865
Type @var{card16}.
 
12866
 
 
12867
The minor opcode for the graphics request generating the event
 
12868
(0 for both @var{copy-area} and @var{copy-plane}).
 
12869
@end table
 
12870
 
 
12871
@end deftp
 
12872
 
 
12873
 
 
12874
@deftp {Event Type} :no-exposure
 
12875
 
 
12876
A @var{:no-exposure} event is generated by a call to
 
12877
@var{copy-area} or @var{copy-plane} when the exposures attribute
 
12878
of the graphics context is @var{:on}. If no
 
12879
@var{:graphics-exposure} events are generated, then a single
 
12880
@var{:no-exposure} event is sent.
 
12881
 
 
12882
@table @var
 
12883
@item drawable
 
12884
@itemx event-window
 
12885
Type @var{drawable}.
 
12886
 
 
12887
The destination drawable for the @var{copy-area} or @var{copy-plane} function.
 
12888
 
 
12889
@item major
 
12890
Type @var{card8}.
 
12891
 
 
12892
The major opcode for the graphics request generating the event
 
12893
(62 for @var{copy-area}, 63 for @var{copy-plane}).
 
12894
 
 
12895
@item minor
 
12896
Type @var{card16}.
 
12897
 
 
12898
The minor opcode for the graphics request generating the event
 
12899
(0 for both @var{copy-area} and @var{copy-plane}).
 
12900
@end table
 
12901
 
 
12902
@end deftp
 
12903
 
 
12904
 
 
12905
@node Window State Events, Structure Control Events, Exposure Events, Event Types
 
12906
@subsection Window State Events
 
12907
 
 
12908
 
 
12909
The following paragraphs describe the events that can be received when a
 
12910
window becomes:
 
12911
@itemize @bullet
 
12912
 
 
12913
@item  Created
 
12914
 
 
12915
@item  Destroyed
 
12916
 
 
12917
@item  Invisible
 
12918
 
 
12919
@item  Mapped
 
12920
 
 
12921
@item  Moved
 
12922
 
 
12923
@item  Reparented
 
12924
 
 
12925
@item  Resized
 
12926
 
 
12927
@item  Restacked
 
12928
 
 
12929
@item  Unmapped
 
12930
 
 
12931
@item  Visible
 
12932
@end itemize
 
12933
 
 
12934
@deftp {Event Type} :circulate-notify
 
12935
 
 
12936
Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.
 
12937
 
 
12938
A @var{:circulate-notify} event is generated whenever a window is
 
12939
actually restacked as a result of a client application calling
 
12940
@var{circulate-window-up} or @var{circulate-window-down}.
 
12941
 
 
12942
@table @var
 
12943
@item event-window
 
12944
Type @var{window}.
 
12945
 
 
12946
The window receiving the event.
 
12947
 
 
12948
@item window
 
12949
Type @var{window}.
 
12950
 
 
12951
The window that was restacked.
 
12952
 
 
12953
@item place
 
12954
Type (@var{member :top :bottom}).
 
12955
 
 
12956
If place is @var{:top}, the @emph{window} is now on top of all siblings. Otherwise, it is below
 
12957
all siblings.
 
12958
@end table
 
12959
 
 
12960
@end deftp
 
12961
 
 
12962
 
 
12963
@deftp {Event Type} :configure-notify
 
12964
 
 
12965
Selected by: @var{:structure-notify} on a window or
 
12966
@var{:substructure-notify} on its parent.
 
12967
 
 
12968
 
 
12969
The @var{:configure-notify} event is generated when the position or
 
12970
size of a window actually changes as a result of a client
 
12971
application setting its @emph{x}, @emph{y}, @emph{width},
 
12972
@emph{height}, or @emph{border-width} attributes.
 
12973
 
 
12974
@table @var
 
12975
@item event-window
 
12976
Type @var{window}.
 
12977
 
 
12978
The window receiving the event.
 
12979
 
 
12980
@item window
 
12981
Type @var{window}.
 
12982
 
 
12983
The window that was moved or resized.
 
12984
 
 
12985
@item x
 
12986
Type @var{int16}.
 
12987
 
 
12988
@emph{x} and @emph{y} specify the new upper-left corner position of the @emph{window} relative to its
 
12989
parent.
 
12990
 
 
12991
@item y
 
12992
Type @var{int16}.
 
12993
 
 
12994
@emph{x} and @emph{y} specify the new upper-left corner position of the @emph{window} relative to its
 
12995
parent.
 
12996
 
 
12997
@item width
 
12998
Type @var{card16}.
 
12999
 
 
13000
@emph{width} and @emph{height} specify the new size of the @emph{window} interior.
 
13001
 
 
13002
@item height
 
13003
Type @var{card16}.
 
13004
 
 
13005
@emph{width} and @emph{height} specify the new size of the @emph{window} interior.
 
13006
 
 
13007
@item border-width
 
13008
Type @var{card16}.
 
13009
 
 
13010
The new @emph{window} border width.
 
13011
 
 
13012
@item above-sibling
 
13013
Type (@var{or null window}).
 
13014
 
 
13015
The sibling immediately below the @emph{window}. If above-sibling is @var{nil}, then the
 
13016
@emph{window} is below all of its siblings.
 
13017
 
 
13018
@item override-redirect-p
 
13019
Type @var{boolean}.
 
13020
 
 
13021
@emph{override-redirect-p} is true if the override-redirect attribute of the @emph{window} is
 
13022
@var{:on}; otherwise, it is @var{nil}. See @var{window-override-redirect} in @ref{Window Attributes}.
 
13023
@end table
 
13024
 
 
13025
 
 
13026
The X server can report @var{:create-notify} events to clients
 
13027
wanting information about creation of windows. The X server
 
13028
generates this event whenever a client application creates a window
 
13029
by calling @var{create-window}.
 
13030
 
 
13031
To receive this event type in a client application, you @code{setf}
 
13032
the @var{:substructure-notify} as the event-mask in the parent
 
13033
window's event-mask slot.
 
13034
 
 
13035
@end deftp
 
13036
 
 
13037
 
 
13038
@deftp {Event Type} :create-notify
 
13039
 
 
13040
Selected by: @var{:substructure-notify}.
 
13041
 
 
13042
 
 
13043
The @var{:create-notify} event is generated when a @emph{window} is
 
13044
created and is sent to the @emph{parent} window.
 
13045
 
 
13046
@table @var
 
13047
@item parent
 
13048
@itemx event-window
 
13049
Type @var{window}.
 
13050
 
 
13051
The parent window receiving the event.
 
13052
 
 
13053
@item window
 
13054
Type @var{window}.
 
13055
 
 
13056
The new window created.
 
13057
 
 
13058
@item x
 
13059
Type @var{int16}.
 
13060
 
 
13061
@emph{x} and @emph{y} specify the initial upper-left corner position of the @emph{window} relative to
 
13062
the parent.
 
13063
 
 
13064
@item y
 
13065
Type @var{int16}.
 
13066
 
 
13067
@emph{x} and @emph{y} specify the initial upper-left corner position of the @emph{window} relative to
 
13068
the parent.
 
13069
 
 
13070
@item width
 
13071
Type @var{card16}.
 
13072
 
 
13073
@emph{width} and @emph{height} specify the initial size of the @emph{window} interior.
 
13074
 
 
13075
@item height
 
13076
Type @var{card16}.
 
13077
 
 
13078
@emph{width} and @emph{height} specify the initial size of the @emph{window} interior.
 
13079
 
 
13080
@item border-width
 
13081
Type @var{card16}.
 
13082
 
 
13083
The initial @emph{window} border width.
 
13084
 
 
13085
@item override-redirect-p
 
13086
Type @var{boolean}.
 
13087
 
 
13088
@emph{override-redirect-p} is true if the override-redirect attribute of the @emph{window} is
 
13089
@var{:on}; otherwise, it is @var{nil}. See @var{window-override-redirect} in @ref{Window Attributes}.
 
13090
 
 
13091
@end table
 
13092
 
 
13093
@end deftp
 
13094
 
 
13095
 
 
13096
@deftp {Event Type} :destroy-notify
 
13097
 
 
13098
Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.
 
13099
 
 
13100
The @var{:destroy-notify} event is generated when a @emph{window}
 
13101
is destroyed. The ordering of the @var{:destroy-notify} events is
 
13102
such that for any given window, @var{:destroy-notify} is generated
 
13103
on all inferiors of a window before @var{:destroy-notify} is
 
13104
generated on the @emph{window}. The ordering among siblings and
 
13105
across subhierarchies is not otherwise constrained.
 
13106
 
 
13107
@table @var
 
13108
@item event-window
 
13109
Type @var{window}.
 
13110
 
 
13111
The window receiving the event.
 
13112
 
 
13113
@item window
 
13114
Type @var{window}.
 
13115
 
 
13116
The window that was destroyed.
 
13117
@end table
 
13118
 
 
13119
@end deftp
 
13120
 
 
13121
 
 
13122
@deftp {Event Type} :gravity-notify
 
13123
 
 
13124
Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.
 
13125
 
 
13126
The X server can report @var{:gravity-notify} events to clients
 
13127
wanting information about when a @emph{window} is moved because of a
 
13128
change in the size of its parent. The X server generates this event
 
13129
whenever a client application actually moves a child window as a
 
13130
result of resizing its parent by calling @var{with-state} with the
 
13131
appropriate arguments set.
 
13132
 
 
13133
@table @var
 
13134
@item event-window
 
13135
Type @var{window}.
 
13136
 
 
13137
The window receiving the event.
 
13138
 
 
13139
@item window
 
13140
Type @var{window}.
 
13141
 
 
13142
The window that was moved.
 
13143
 
 
13144
@item x
 
13145
Type @var{int16}.
 
13146
 
 
13147
x and y specify the new upper-left corner position of the @emph{window} relative to its
 
13148
parent.
 
13149
 
 
13150
@item y
 
13151
Type @var{int16}.
 
13152
 
 
13153
x and y specify the new upper-left corner position of the @emph{window} relative to its
 
13154
parent.
 
13155
@end table
 
13156
 
 
13157
@end deftp
 
13158
 
 
13159
 
 
13160
@deftp {Event Type} :map-notify
 
13161
 
 
13162
Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.
 
13163
 
 
13164
The X server can report @var{:map-notify} events to clients wanting
 
13165
information about which windows are mapped. The X server generates
 
13166
this event type whenever a client application changes the
 
13167
@emph{window}'s state from unmapped to mapped by calling
 
13168
@var{map-window} or @var{map-subwindow}.
 
13169
 
 
13170
To receive this event type, you @var{setf :structure-notify} as the
 
13171
event-mask on the @emph{window}'s @var{event-mask} slot. You can
 
13172
also receive this event type by @code{setf}ing the
 
13173
@var{:substructure-notify} event-mask on the parent window.
 
13174
 
 
13175
@table @var
 
13176
@item event-window
 
13177
Type @var{window}.
 
13178
 
 
13179
The window receiving the event.
 
13180
 
 
13181
@item window
 
13182
Type @var{window}.
 
13183
 
 
13184
The window that was mapped.
 
13185
 
 
13186
@item override-redirect-p
 
13187
Type @var{boolean}.
 
13188
 
 
13189
@emph{override-redirect-p} is true if the override-redirect attribute of the @emph{window} is
 
13190
@var{:on}; otherwise, it is @var{nil}. See @var{window-override-redirect} in @ref{Window Attributes}.
 
13191
@end table
 
13192
 
 
13193
@end deftp
 
13194
 
 
13195
 
 
13196
@deftp {Event Type} :reparent-notify
 
13197
Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its old or new parent.
 
13198
 
 
13199
The @var{:reparent-notify} event is generated when a @emph{window}
 
13200
is reparented.
 
13201
 
 
13202
@table @var
 
13203
@item event-window
 
13204
Type @var{window}.
 
13205
 
 
13206
The window receiving the event.
 
13207
 
 
13208
@item window
 
13209
Type @var{window}.
 
13210
 
 
13211
The window that was reparented.
 
13212
 
 
13213
@item parent
 
13214
Type @var{window}.
 
13215
 
 
13216
The new parent of the @emph{window}.
 
13217
 
 
13218
@item x
 
13219
Type @var{int16}.
 
13220
 
 
13221
x and y specify the upper-left corner position of the @emph{window} relative to its new
 
13222
@emph{parent}.
 
13223
 
 
13224
@item y
 
13225
Type @var{int16}.
 
13226
 
 
13227
x and y specify the upper-left corner position of the @emph{window} relative to its new
 
13228
@emph{parent}.
 
13229
 
 
13230
@item override-redirect-p
 
13231
Type @var{boolean}.
 
13232
 
 
13233
@emph{override-redirect-p} is true if the override-redirect attribute
 
13234
of the @emph{window} is @var{:on}; otherwise, it is @var{nil}. See
 
13235
@var{window-override-redirect} in @ref{Window Attributes}.
 
13236
@end table
 
13237
 
 
13238
@end deftp
 
13239
 
 
13240
 
 
13241
@deftp {Event Type} :unmap-notify
 
13242
 
 
13243
Selected by: @var{:structure-notify} on a window or @var{:substructure-notify} on its parent.
 
13244
 
 
13245
The @var{:unmap-notify} event is generated when a mapped
 
13246
@emph{window} is unmapped.
 
13247
 
 
13248
@table @var
 
13249
@item event-window
 
13250
Type @var{window}.
 
13251
 
 
13252
The window receiving the event.
 
13253
 
 
13254
@item window
 
13255
Type @var{window}.
 
13256
 
 
13257
The window that was unmapped.
 
13258
 
 
13259
@item configure-p
 
13260
Type @var{boolean}.
 
13261
 
 
13262
@emph{configure-p} is true if the @emph{window} has a win-gravity
 
13263
attribute of @var{:unmap}, and the event was generated because
 
13264
@emph{window}'s parent was resized.
 
13265
@end table
 
13266
 
 
13267
@end deftp
 
13268
 
 
13269
 
 
13270
@deftp {Event Type} :visibility-notify
 
13271
 
 
13272
Selected by: @var{:visibility-change}.
 
13273
 
 
13274
The @var{:visibility-notify} event is sent when the visibility of a
 
13275
@emph{window} changes.  @var{:visibility-notify} events are never
 
13276
generated on @var{:input-only} windows. For the purposes of this
 
13277
event, the visibility of the @emph{window} is not affected by its
 
13278
subwindows.
 
13279
 
 
13280
All @var{:visibility-notify} events caused by a hierarchy change
 
13281
are generated after any hierarchy event caused by that change (for
 
13282
example, @var{:unmap-notify}, @var{:map-notify},
 
13283
@var{:configure-notify}, @var{:gravity-notify}, or
 
13284
@var{:circulate-notify}). Any @var{:visibility-notify} event on a
 
13285
given window is generated before any @var{:exposure} events on that
 
13286
window, but it is not required that all @var{:visibility-notify}
 
13287
events on all windows be generated before all @var{:exposure}
 
13288
events on all windows. The ordering of @var{:visibility-notify}
 
13289
events with respect to @var{:focus-out}, @var{:enter-notify}, and
 
13290
@var{:leave-notify} events is not constrained.
 
13291
 
 
13292
@table @var
 
13293
@item window
 
13294
@itemx event-window
 
13295
Type @var{window}.
 
13296
 
 
13297
The window that changed in visibility.
 
13298
 
 
13299
@item state
 
13300
Type (@var{member :unobscured :partially-obscured} @var{:fully-obscured}).
 
13301
 
 
13302
When the @emph{window} was either unviewable or it was viewable and at least
 
13303
partially obscured, and the @emph{window} changed to viewable and completely
 
13304
unobscured, then @emph{state} is @var{:unobscured}.
 
13305
 
 
13306
When the @emph{window} was either unviewable or it was viewable and completely
 
13307
obscured, and the @emph{window} changed to viewable and partially obscured, then
 
13308
@emph{state} is @var{:partially-obscured}.
 
13309
 
 
13310
When the @emph{window} was either unviewable or it was at least partially visible, and
 
13311
the @emph{window} changed to viewable and completely obscured, then @emph{state} is
 
13312
@var{:fully-obscured}.
 
13313
@end table
 
13314
 
 
13315
@end deftp
 
13316
 
 
13317
 
 
13318
@node Structure Control Events, Client Communications Events, Window State Events, Event Types
 
13319
@subsection Structure Control Events
 
13320
 
 
13321
 
 
13322
The following paragraphs describe events used to @emph{redirect}
 
13323
client requests that reconfigure, restack, or map a window. Structure
 
13324
control events are typically used only by window managers and not by
 
13325
ordinary client applications. Structure control events report
 
13326
redirected requests, allowing a window manager to modify the requests
 
13327
before they are actually performed. However, if the override-redirect
 
13328
attribute of a window is @var{:on}, then no requests are redirected
 
13329
and no structure control events are generated.
 
13330
 
 
13331
@deftp {Event Type} :circulate-request
 
13332
 
 
13333
The @var{:circulate-request} event is generated when a client
 
13334
application calls @var{circulate-window-up} or
 
13335
@var{circulate-window-down} with a window that has the
 
13336
override-redirect attribute @var{:off}. The @emph{window} argument
 
13337
specifies the window to be restacked, and @emph{place} specifies
 
13338
what the new position in the stacking order should be (either
 
13339
@var{:top} or @var{:bottom}).
 
13340
 
 
13341
Selected by: @var{:substructure-redirect} on @emph{parent}.
 
13342
 
 
13343
@table @var
 
13344
@item parent
 
13345
@itemx event-window
 
13346
Type @var{window}.
 
13347
 
 
13348
The window receiving the event. The receiving client must have selected
 
13349
@var{:substructure-redirect} on this window.
 
13350
 
 
13351
@item window
 
13352
Type @var{window}.
 
13353
 
 
13354
The window to be restacked.
 
13355
 
 
13356
@item place
 
13357
Type @code{(member :top :bottom)}.
 
13358
 
 
13359
The new stacking priority requested for @emph{window}.
 
13360
@end table
 
13361
 
 
13362
@end deftp
 
13363
 
 
13364
 
 
13365
@deftp {Event Type} :colormap-notify
 
13366
Selected by: @var{:colormap-change}.
 
13367
 
 
13368
The @var{:colormap-notify} event is generated with @emph{new-p}
 
13369
@var{t} when the @emph{colormap} associated with a @emph{window} is
 
13370
changed, installed, or uninstalled.
 
13371
 
 
13372
@table @var
 
13373
@item window
 
13374
@itemx event-window
 
13375
Type @var{window}.
 
13376
 
 
13377
The window receiving the event.
 
13378
 
 
13379
@item colormap
 
13380
Type @code{(or null colormap)}.
 
13381
 
 
13382
The colormap attribute of the window.
 
13383
 
 
13384
@item new-p
 
13385
Type @var{boolean}.
 
13386
 
 
13387
If @emph{new-p} is true, then the @emph{window}'s colormap attribute has changed to the given
 
13388
@emph{colormap}. Otherwise, the @emph{window}'s colormap attribute has not, but the
 
13389
@emph{colormap} has been installed or uninstalled.
 
13390
 
 
13391
@item installed-p
 
13392
Type @var{boolean}.
 
13393
 
 
13394
If @emph{installed-p} is true, then the @emph{colormap} is currently installed.
 
13395
@end table
 
13396
 
 
13397
@end deftp
 
13398
 
 
13399
 
 
13400
@deftp {Event Type} :configure-request
 
13401
 
 
13402
Selected by:@var{:substructure-redirect} on parent.
 
13403
 
 
13404
The @var{:configure-request} event is generated when a client
 
13405
program sets the @emph{x}, @emph{y}, @emph{width}, @emph{heigh}t,
 
13406
@emph{border-width} or stacking priority attributes of a window that
 
13407
has the override-redirect attribute @var{:off}.
 
13408
 
 
13409
@table @var
 
13410
@item parent
 
13411
@itemx event-window
 
13412
Type @var{window}.
 
13413
 
 
13414
The window receiving the event. The receiving client must have selected
 
13415
@var{:substructure-redirect} on this window.
 
13416
 
 
13417
@item window
 
13418
Type @var{window}.
 
13419
 
 
13420
The window to be reconfigured.
 
13421
 
 
13422
@item x
 
13423
Type @var{int16}.
 
13424
 
 
13425
@emph{x} and @emph{y} specify the requested upper-left corner position of the @emph{window} relative
 
13426
to the parent. If either @emph{x} or @emph{y} is not specified in the value-mask, then it is set to
 
13427
the current window position.
 
13428
 
 
13429
@item y
 
13430
Type @var{int16}.
 
13431
 
 
13432
@emph{x} and @emph{y} specify the requested upper-left corner position of the @emph{window} relative
 
13433
to the @emph{parent}. If either @emph{x} or @emph{y} is not specified in the @emph{value-mask}, then it is set to
 
13434
the current window position.
 
13435
 
 
13436
@item width
 
13437
@itemx height
 
13438
Type @var{card16}.
 
13439
 
 
13440
@emph{width} and @emph{height} specify the requested size of the @emph{window} interior. If either
 
13441
@emph{width} or @emph{height} is not specified in the @emph{value-mask}, then it is set to the current
 
13442
window size.
 
13443
 
 
13444
@item border-width
 
13445
Type @var{card16}
 
13446
 
 
13447
The requested @emph{window} border width. If @emph{border-width} is not specified in the
 
13448
@emph{value-mask}, then it is set to the current window @emph{border-width}.
 
13449
 
 
13450
@item stack-mode
 
13451
Type @code{(member :above :below :top-if :bottom-if :opposite)}.
 
13452
 
 
13453
@emph{stack-mode} and @emph{above-sibling} specify the requested stacking priority of the
 
13454
@emph{window}. If @emph{stack-mode} is not specified in the @emph{value-mask}, then it is set to
 
13455
@var{:above}.
 
13456
 
 
13457
@item above-sibling
 
13458
Type (@var{or null window}).
 
13459
 
 
13460
@emph{stack-mode} and @emph{above-sibling} specify the requested stacking priority of the
 
13461
@emph{window}. If @emph{above-sibling} is not specified in the @emph{value-mask}, then it is set to @var{nil}.
 
13462
 
 
13463
@item value-mask
 
13464
Type @var{mask16}.
 
13465
 
 
13466
Specifies the changed @emph{window} attributes contained in the redirected client
 
13467
request. Each 1 bit specifies that the corresponding attribute was changed.
 
13468
@end table
 
13469
 
 
13470
@end deftp
 
13471
 
 
13472
 
 
13473
@deftp {Event Type} :map-request
 
13474
 
 
13475
Selected by: @var{:substructure-redirect} on parent.
 
13476
 
 
13477
The @var{:map-request} event is generated when a client application
 
13478
maps a @emph{window} that has the override-redirect attribute
 
13479
@var{:off}.
 
13480
 
 
13481
@table @var
 
13482
@item parent
 
13483
@itemx event-window
 
13484
Type @var{window}.
 
13485
 
 
13486
The window receiving the event. The receiving client must have selected
 
13487
@var{:substructure-redirect} on this window.
 
13488
 
 
13489
@item window
 
13490
Type @var{window}.
 
13491
 
 
13492
The window to be mapped.
 
13493
@end table
 
13494
 
 
13495
@end deftp
 
13496
 
 
13497
 
 
13498
@deftp {Event Type} :resize-request
 
13499
 
 
13500
Selected by: @var{:resize-redirect}.
 
13501
 
 
13502
The @var{:resize-request} event is generated when a client program
 
13503
sets the @emph{width} or @emph{height} attributes of a @emph{window}
 
13504
that has the override-redirect attribute @var{:off}.
 
13505
 
 
13506
@table @var
 
13507
@item window
 
13508
@itemx event-window
 
13509
Type @var{window}.
 
13510
 
 
13511
The window to be resized.
 
13512
 
 
13513
@item width
 
13514
@itemx height
 
13515
Type @var{card16}.
 
13516
 
 
13517
@emph{width} and @emph{height} specify the requested size of the wi@emph{ndow} interior. If either
 
13518
@emph{width} or @emph{height} was unchanged in the client request, then it is set to the current
 
13519
window size.
 
13520
@end table
 
13521
 
 
13522
@end deftp
 
13523
 
 
13524
 
 
13525
@node Client Communications Events, Declaring Event Types, Structure Control Events, Event Types
 
13526
@subsection Client Communications Events
 
13527
 
 
13528
 
 
13529
The client communications events discussed in the following paragraphs
 
13530
are: @var{:client-message}, @var{:property-notify},
 
13531
@var{:selection-clear}, @var{:selection-request}, and
 
13532
@var{:selection-notify}.
 
13533
 
 
13534
@deftp {Event Type} :client-message
 
13535
 
 
13536
The @var{:client-message} event is generated exclusively by client
 
13537
calls to @var{send-event}. The X server places no interpretation on
 
13538
the @emph{type} or content of @emph{data} sent in a
 
13539
@var{:client-message}. A client can neither select
 
13540
@var{:client-message} events nor avoid receiving them.
 
13541
 
 
13542
@table @var
 
13543
@item window
 
13544
@itemx event-window
 
13545
Type @var{window}.
 
13546
 
 
13547
The window receiving the event.
 
13548
 
 
13549
@item type
 
13550
Type @var{keyword}.
 
13551
 
 
13552
An xatom keyword that specifies the type of client message. Interpretation of
 
13553
the type is determined solely by agreement between the sending and receiving
 
13554
clients.
 
13555
 
 
13556
@item format
 
13557
Type (@var{member 8 16 32}).
 
13558
 
 
13559
An integer that specifies whether @emph{data} should be viewed as a sequence of 8-bit,
 
13560
16-bit, or 32-bit quantities.
 
13561
 
 
13562
@item data
 
13563
Type @code{(sequence integer)}.
 
13564
 
 
13565
The data content of the client message. @emph{data} always consists of 160 bytes --
 
13566
depending on format, either 20 8-bit values, 10 16-bit values or 5 32-bit values.
 
13567
The amount of this data actually used by a particular client message depends on
 
13568
the type.
 
13569
@end table
 
13570
 
 
13571
@end deftp
 
13572
 
 
13573
 
 
13574
@deftp {Event Type} :property-notify
 
13575
Selected by: @var{:property-change}.
 
13576
 
 
13577
The @var{:property-notify} event is generated when a window
 
13578
property is changed or deleted.
 
13579
 
 
13580
@table @var
 
13581
@item window
 
13582
@itemx event-window
 
13583
Type @var{window}.
 
13584
 
 
13585
The window receiving the event.
 
13586
 
 
13587
@item atom
 
13588
Type @var{keyword}.
 
13589
 
 
13590
The property that was changed or deleted.
 
13591
 
 
13592
@item state
 
13593
Type @code{(member :new-value :deleted)}.
 
13594
 
 
13595
@emph{state} is @var{:new-value} if the property was changed using @var{change-property} or
 
13596
@var{rotate-properties}, even if zero-length data was added or if all or part of the
 
13597
property was replaced with identical data. @emph{state} is @var{:deleted} if the property was
 
13598
deleted using @var{delete-property} or @var{get-property}.
 
13599
 
 
13600
@item time
 
13601
Type @var{timestamp}.
 
13602
 
 
13603
The server time when the property was changed or deleted.
 
13604
@end table
 
13605
 
 
13606
@end deftp
 
13607
 
 
13608
 
 
13609
@deftp {Event Type} :selection-clear
 
13610
 
 
13611
The @var{:selection-clear} event is reported to the previous owner
 
13612
of a @emph{selection} when the owner of the @emph{selection} is
 
13613
changed. The selection owner is changed by a client using
 
13614
@code{setf}.  A client can neither select @var{:selection-clear}
 
13615
events nor avoid receiving them.
 
13616
@table @var
 
13617
@item window
 
13618
@itemx event-window
 
13619
Type @var{window}.
 
13620
 
 
13621
The window losing ownership of the @emph{selection}.
 
13622
 
 
13623
@item selection
 
13624
Type @var{keyword}.
 
13625
 
 
13626
The name of the selection.
 
13627
 
 
13628
@item time
 
13629
Type @var{timestamp}.
 
13630
 
 
13631
The last-change time recorded for the @emph{selection}.
 
13632
@end table
 
13633
 
 
13634
@end deftp
 
13635
 
 
13636
@deftp {Event Type} :selection-notify
 
13637
 
 
13638
The @var{:selection-notify} event is sent to a client calling
 
13639
@var{convert-selection}.  @var{:selection-notify} reports the
 
13640
result of the client request to return the current value of a
 
13641
@emph{selection} into a particular form. @var{:selection-notify} is
 
13642
sent using @var{send-event} by the owner of the selection or (if no
 
13643
owner exists) by the X server. A client can neither select
 
13644
@var{:selection-notify} events nor avoid receiving them.
 
13645
 
 
13646
@var{NOTE:} Standard conventions for inter-client communication require the following
 
13647
additional steps in processing a @var{:selection-notify} event:
 
13648
 
 
13649
@enumerate
 
13650
 
 
13651
@item
 
13652
The client receiving this event should call @var{get-property} to
 
13653
return the converted selection value.
 
13654
 
 
13655
@item
 
13656
After receiving the selection value, the property should then be
 
13657
deleted (either by using the @var{:delete-p} argument to
 
13658
@var{get-property} or by calling @var{delete-property}).
 
13659
@end enumerate
 
13660
 
 
13661
@table @var
 
13662
@item window
 
13663
@itemx event-window
 
13664
Type @var{window}.
 
13665
 
 
13666
The requestor window given in the call to @var{convert-selection}.
 
13667
 
 
13668
@item selection
 
13669
Type @var{keyword}.
 
13670
 
 
13671
The selection to be converted.
 
13672
 
 
13673
@item target
 
13674
Type @var{keyword}.
 
13675
 
 
13676
An @var{xatom} specifying the type of the converted selection value. This is the same
 
13677
target type given in the call to @var{convert-selection}.
 
13678
 
 
13679
@item property
 
13680
Type @code{(or null keyword)}.
 
13681
 
 
13682
The window property containing the converted selection. If the property is @var{nil},
 
13683
then either the @emph{selection} has no owner or the owner could not perform the
 
13684
conversion to the @emph{target} type.
 
13685
 
 
13686
@item time
 
13687
Type @var{timestamp}.
 
13688
 
 
13689
The timestamp from the client call to @var{convert-selection}.
 
13690
@end table
 
13691
 
 
13692
@end deftp
 
13693
 
 
13694
 
 
13695
@deftp {Event Type} :selection-request
 
13696
 
 
13697
The @var{:selection-request} event is reported to the owner of a
 
13698
selection when a client calls @var{convert-selection}. This event
 
13699
requests the selection owner to convert the current value of a
 
13700
@emph{selection} into a specified form and to return it to the
 
13701
requestor. A client can neither select @var{:selection-request}
 
13702
events nor avoid receiving them.
 
13703
 
 
13704
The selection owner should respond to a @var{:selection-request} event by performing the
 
13705
following steps:
 
13706
 
 
13707
@enumerate
 
13708
 
 
13709
@item
 
13710
Convert the current @emph{selection} value to the @emph{target}
 
13711
type.
 
13712
 
 
13713
@item
 
13714
Store the converted selection value in the @emph{property}. If
 
13715
@emph{property} is @var{nil}, then the owner should choose the
 
13716
@emph{property}.
 
13717
 
 
13718
@item
 
13719
Call @var{send-event} to send a @var{:selection-notify} event to
 
13720
the @emph{requestor} containing the @emph{property} with the
 
13721
converted value. If the @emph{selection} could not be converted to
 
13722
the @emph{target} type, then a @var{nil} @emph{property} should
 
13723
be sent. The @var{:selection}, @var{:target}, and @var{:time}
 
13724
arguments to @var{send-event} should be the same as those
 
13725
received in the @var{:selection-request} event. The event-mask
 
13726
argument to @var{send-event} should be @var{nil}; that is, the
 
13727
@var{:selection-notify} event should be sent to client that
 
13728
created the @emph{requestor}.
 
13729
@end enumerate
 
13730
 
 
13731
 
 
13732
@var{NOTE:} Standard conventions for inter-client communication
 
13733
require the following additional steps in processing a
 
13734
@var{:selection-request} event:
 
13735
 
 
13736
@enumerate
 
13737
 
 
13738
@item
 
13739
The property used to store the selection value must belong to the
 
13740
requestor.
 
13741
 
 
13742
@item
 
13743
If the property is @var{nil}, the target type @var{atom} should
 
13744
be used as the property name.
 
13745
 
 
13746
@item
 
13747
If the window did not actually own the selection at the given
 
13748
time, the request should be refused, just as if it could not be
 
13749
converted to the target type.
 
13750
@end enumerate
 
13751
 
 
13752
@table @var
 
13753
@item window
 
13754
@itemx event-window
 
13755
Type @var{window}.
 
13756
 
 
13757
The selection owner receiving the event.
 
13758
 
 
13759
@item requestor
 
13760
Type @var{window}.
 
13761
 
 
13762
The window requesting the converted @emph{selection}.
 
13763
 
 
13764
@item selection
 
13765
Type @var{keyword}.
 
13766
 
 
13767
The selection to be converted.
 
13768
 
 
13769
@item target
 
13770
Type @var{keyword}.
 
13771
 
 
13772
An @var{xatom} specifying the type of the converted @emph{selection} value.
 
13773
 
 
13774
@item property
 
13775
Type @code{(or null keyword)}.
 
13776
 
 
13777
A requestor window property.
 
13778
 
 
13779
@item time
 
13780
Type @var{timestamp}.
 
13781
 
 
13782
The timestamp sent in the client @var{convert-selection} request.
 
13783
@end table
 
13784
 
 
13785
@end deftp
 
13786
 
 
13787
 
 
13788
@node Declaring Event Types,  , Client Communications Events, Event Types
 
13789
@subsection Declaring Event Types
 
13790
 
 
13791
 
 
13792
CLX uses the @var{declare-event} macro to define the event slot symbols
 
13793
that access the contents of X events. Most client applications do not
 
13794
need to use @var{declare-event} because the declarations for all core X
 
13795
events are already defined by CLX.  Programmers using extensions to the
 
13796
X protocol can use @var{declare-event} to allow CLX to handle new event
 
13797
types returned by an extended X server.
 
13798
 
 
13799
@defmac declare-event event-codes &rest slot-declarations
 
13800
 
 
13801
Defines a mapping between event slot symbols and the data items in
 
13802
event messages received from an X server.
 
13803
 
 
13804
The @emph{event-codes} argument gives the event type keyword for the
 
13805
event described. If several event types share the same slots, then
 
13806
@emph{event-codes} can be a list of event type
 
13807
keywords. @emph{slot-declarations} is a list containing an element
 
13808
for each event data item. The order of @emph{slot-declarations}
 
13809
corresponds to the order of event data items defined by the X
 
13810
protocol.
 
13811
 
 
13812
Each element of @emph{slot-declarations} is a list of the form
 
13813
(@emph{type slot-name}*), where @emph{type} is a Common Lisp type
 
13814
specifier and @emph{slot-name} is a slot name symbol. The effect of
 
13815
such a list is to declare that the next data items in the event have
 
13816
the given data @emph{type} and are associated with the given
 
13817
@emph{slot-name} symbols. @emph{slot-name} can also be a list of
 
13818
slot name symbols; in this case, each symbol in the list is an alias
 
13819
that refers to the same event data item.
 
13820
 
 
13821
@table @var
 
13822
@item event-codes
 
13823
An event type keyword or a list of event type keywords.
 
13824
@item slot-declarations
 
13825
A list of clauses defining event slot symbols.
 
13826
@end table
 
13827
 
 
13828
@end defmac
 
13829
 
 
13830
 
 
13831
@node Releasing Queued Events,  , Event Types, Events and Input
 
13832
@section Releasing Queued Events
 
13833
 
 
13834
 
 
13835
A client grabbing the keyboard or pointer can freeze the reporting of
 
13836
events on that device. When an input device is thus frozen, the server
 
13837
queues events until explicitly requested to release them by the grabbing
 
13838
client. CLX programs can use the @var{allow-events} function to release
 
13839
queued events from a frozen input device.
 
13840
 
 
13841
@defun allow-events display mode &optional time
 
13842
 
 
13843
@table @var
 
13844
@item display
 
13845
A @var{display}.
 
13846
 
 
13847
@item mode
 
13848
One of: @var{:async-pointer}, @var{:sync-pointer},
 
13849
@var{:reply-pointer}, @var{:async-keyboard}, @var{:sync-keyboard},
 
13850
@var{:replay-keyboard}, @var{:async-both}, @var{:sync-both}.
 
13851
 
 
13852
@item time
 
13853
A @var{timestamp}.
 
13854
@end table
 
13855
 
 
13856
Releases some queued events if the client has caused a device to
 
13857
freeze. The request has no effect if the @emph{time} is earlier than
 
13858
the last-grab time of the most recent active grab for the client, or
 
13859
if the @emph{time} is later than the current server time. If
 
13860
@emph{time} is @var{nil}, the current server time is used. The
 
13861
effect of this function depends on the specified @emph{mode}.
 
13862
@itemize @bullet
 
13863
 
 
13864
@item
 
13865
@var{:async-pointer} -- If the pointer is frozen by the client,
 
13866
pointer event processing continues normally. If the pointer is
 
13867
frozen twice by the client on behalf of two separate grabs,
 
13868
@var{:async-pointer} releases events for both
 
13869
grab@emph{s}. @var{:async-pointer} has no effect if the pointer
 
13870
is not frozen by the client, but the pointer need not be grabbed
 
13871
by the client.
 
13872
 
 
13873
@item
 
13874
@var{:sync-pointer} -- If the pointer is frozen and actively
 
13875
grabbed by the client, pointer event processing continues normally
 
13876
until the next @var{:button-press} or @var{:button-release}
 
13877
event is reported to the client, at which time the pointer again
 
13878
appears to freeze. However, if the reported event causes the
 
13879
pointer grab to be released, the pointer does not
 
13880
freeze. @var{:sync-pointer} has no effect if the pointer is not
 
13881
frozen by the client, or if the pointer is not grabbed by the
 
13882
client.
 
13883
 
 
13884
@item
 
13885
@var{:replay-pointer} -- If the pointer is actively grabbed by
 
13886
the client and is frozen as the result of an event having been
 
13887
sent to the client (either from the activation of a
 
13888
@var{grab-button}, or from a previous @var{allow-events} with
 
13889
mode @var{:sync-pointer}, but not from a @var{grab-pointer}),
 
13890
the pointer grab is released and that event is completely
 
13891
reprocessed, but this time ignoring any passive grabs at or above
 
13892
(towards the root) the @var{grab-window} of the grab just
 
13893
released. The request has no effect if the pointer is not grabbed
 
13894
by the client, or if the pointer is not frozen as the result of an
 
13895
event.
 
13896
 
 
13897
@item
 
13898
@var{:async-keyboard} -- If the keyboard is frozen by the client,
 
13899
keyboard event processing continues normally. If the keyboard is
 
13900
frozen twice by the client on behalf of two separate grabs,
 
13901
@var{:async-keyboard} releases events for both grabs.
 
13902
@var{:async-keyboard} has no effect if the keyboard is not frozen
 
13903
by the client, but the keyboard need not be grabbed by the client.
 
13904
 
 
13905
@item
 
13906
@var{:sync-keyboard} -- If the keyboard is frozen and actively
 
13907
grabbed by the client, keyboard event processing continues
 
13908
normally until the next @var{:key-press} or @var{:key-release}
 
13909
event is reported to the client, at which time the keyboard again
 
13910
appears to freeze. However if the reported event causes the
 
13911
keyboard grab to be released, the keyboard does not
 
13912
freeze. @var{:sync-keyboard} has no effect if the keyboard is not
 
13913
frozen by the client, or if the keyboard is not grabbed by the
 
13914
client.
 
13915
 
 
13916
@item
 
13917
@var{:replay-keyboard} -- If the keyboard is actively grabbed by
 
13918
the client and is frozen as the result of an event having been
 
13919
sent to the client (either from the activation of a grab-key, or
 
13920
from a previous @var{allow-events} with mode
 
13921
@var{:sync-keyboard}, but not from a @var{grab-keyboard}), the
 
13922
keyboard grab is released and that event is completely
 
13923
reprocessed, but this time ignoring any passive grabs at or above
 
13924
(towards the root) the @var{grab-window} of the grab just
 
13925
released. The request has no effect if the keyboard is not grabbed
 
13926
by the client, or if the keyboard is not frozen as the result of
 
13927
an event.
 
13928
 
 
13929
@item
 
13930
@var{:sync-both} -- If both pointer and keyboard are frozen by
 
13931
the client, event processing (for both devices) continues normally
 
13932
until the next @var{:button-press}, @var{:button-release},
 
13933
@var{:key-press}, or @var{:key-release} event is reported to the
 
13934
client for a grabbed device (button event for the pointer, key
 
13935
event for the keyboard). At this time, the devices again appear to
 
13936
freeze. If the reported event causes the grab to be released, the
 
13937
devices do not freeze. However, if the other device is still
 
13938
grabbed, then a subsequent event for it will still cause both
 
13939
devices to freeze. @var{:sync-both} has no effect unless both
 
13940
pointer and keyboard are frozen by the client. If the pointer of
 
13941
keyboard is frozen twice by the client on behalf of two separate
 
13942
grabs, @var{:sync-both} @emph{thaws} for both, but a subsequent
 
13943
freeze for @var{:sync-both} will only freeze each device once.
 
13944
 
 
13945
@item
 
13946
@var{:async-both} -- If the pointer and the keyboard are frozen
 
13947
by the client, event processing for both devices continues
 
13948
normally. If a device is frozen twice by the client on behalf of
 
13949
two separate grabs, @var{:async-both} @emph{thaws} for
 
13950
both. @var{:async-both} has no effect unless both pointer and
 
13951
keyboard are frozen by the client.
 
13952
@end itemize
 
13953
 
 
13954
@var{:async-pointer}, @var{:sync-pointer}, and
 
13955
@var{:replay-pointer} have no effect on processing of keyboard
 
13956
events. @var{:async-keyboard}, @var{:sync-keyboard}, and
 
13957
@var{:replay-keyboard} have no effect on processing of pointer
 
13958
events.
 
13959
 
 
13960
It is possible for both a pointer grab and a keyboard grab to be
 
13961
active simultaneously by the same or different clients. When a
 
13962
device is frozen on behalf of either grab, no event processing is
 
13963
performed for the device. It is possible for a single device to be
 
13964
frozen due to both grabs. In this case, the freeze must be released
 
13965
on behalf of both grabs before events can again be processed.
 
13966
 
 
13967
 
 
13968
 
 
13969
@end defun
 
13970
 
 
13971
@node Resources, Control Functions, Events and Input, Top
 
13972
@chapter Resources
 
13973
 
 
13974
Users need a way to specify preferences for various user interface
 
13975
values (for example, colors, fonts, title strings, and so
 
13976
forth). Applications need a consistent method for determining the
 
13977
default interface values that are specific to them. It is also useful if
 
13978
application interface values can be modified by users without changes to
 
13979
the program code. For example, this capability can make it easy to
 
13980
change the color scheme of a user interface. In CLX, such interface
 
13981
values are referred to as @emph{resources}. CLX defines functions for
 
13982
storing and retrieving interface resources from a resource database. A
 
13983
user can store various user interface values as resources in a resource
 
13984
database; a CLX application can then read these resource values and
 
13985
modify its user interface accordingly.
 
13986
 
 
13987
@var{NOTE:} The general term @emph{resource} refers to any application
 
13988
user interface value stored in a resource database. The term @emph{server
 
13989
resource} is used more specifically to refer to the types of objects
 
13990
allocated by an X server and referenced by clients (for example,
 
13991
windows, fonts, graphics contexts, and so forth).
 
13992
 
 
13993
@menu
 
13994
* Resource Binings::
 
13995
* Basic Resource Database Functions::
 
13996
* Accessing Resource Values::
 
13997
* Resource Database Files::
 
13998
@end menu
 
13999
 
 
14000
@node Resource Binings, Basic Resource Database Functions, Resources, Resources
 
14001
@section Resource Binings
 
14002
 
 
14003
 
 
14004
Conceptually, a resource database is a set of resource name-value pairs
 
14005
(or @emph{resource bindings}). The name in a resource binding is a list
 
14006
that is the concatenation of a @emph{path list} and an @emph{attribute
 
14007
name}.
 
14008
 
 
14009
A path list is a list of symbols (or strings) that corresponds to a path
 
14010
through a tree-structured hierarchy. For example, the path:
 
14011
 
 
14012
@lisp
 
14013
'(top middle bottom)
 
14014
@end lisp
 
14015
 
 
14016
 
 
14017
corresponds to a three-level hierarchy in which @code{middle} is
 
14018
the child of @code{top}, and @code{bottom} is the child of
 
14019
@code{middle}.
 
14020
 
 
14021
Typically, the path of a resource name corresponds to a path in a
 
14022
hierarchy of windows, and each symbol/string names a window in the
 
14023
hierarchy. However, the first element of the path can also represent the
 
14024
overall name of the entire program, and subsequent path elements can
 
14025
refer to an application-specific hierarchy of resource names not
 
14026
strictly related to windows. In addition, a resource name can contain a
 
14027
partially-specified path list.  The asterisk symbol (*) is a wildcard
 
14028
that can correspond to any sequence of levels in the hierarchy
 
14029
(including the null sequence). For example, the path:
 
14030
 
 
14031
@lisp
 
14032
'(top * bottom)
 
14033
@end lisp
 
14034
 
 
14035
 
 
14036
corresponds to a hierarchy of two or more levels in which
 
14037
@code{top} is at the top level and @code{bot-}
 
14038
@code{tom} is at the bottom level. An element of a path list can
 
14039
be the name of an individual window or the name of a class of windows.
 
14040
 
 
14041
The final element of a resource name list is an attribute name. This
 
14042
symbol (or string) identifies a specific attribute of the object(s)
 
14043
named by the preceding path list. The attribute name can also be the
 
14044
symbol * or the string "*", in which case the resource name refers to
 
14045
all attributes of the path object(s). However, this form of resource
 
14046
name is rarely useful.
 
14047
 
 
14048
Some examples of resource bindings are shown below. In these examples,
 
14049
assume that @code{mail} is the resource name of a mail reading
 
14050
application. @code{mail} uses a window of the class
 
14051
@code{button} whose name is @code{reply}.
 
14052
 
 
14053
@multitable {Resource Name} {Resource Value}
 
14054
@item @code{(mail screen-1 reply background)} @tab @code{'green}
 
14055
@item @code{(mail * background)} @tab @code{'red}
 
14056
@item @code{(* button background)} @tab @code{'blue}
 
14057
@end multitable
 
14058
 
 
14059
These resource bindings specify the following:
 
14060
@itemize @bullet
 
14061
 
 
14062
@item
 
14063
The @code{background} attribute resource of @code{mail}
 
14064
application@emph{'}s @code{reply} button has the value of
 
14065
@code{green} on @code{screen-1}.
 
14066
 
 
14067
@item
 
14068
The @code{background} attribute for the rest of the
 
14069
@code{mail} application is always @code{red} on all
 
14070
screens.
 
14071
 
 
14072
@item
 
14073
In general, the @code{background} attribute for all
 
14074
@code{button} windows is @code{blue}.
 
14075
@end itemize
 
14076
 
 
14077
@node Basic Resource Database Functions, Accessing Resource Values, Resource Binings, Resources
 
14078
@section Basic Resource Database Functions
 
14079
 
 
14080
 
 
14081
A @var{resource-database} structure is a CLX object that represents a
 
14082
set of resource bindings. The following paragraphs describe the CLX
 
14083
functions used to:
 
14084
@itemize @bullet
 
14085
 
 
14086
@item  Create a resource database
 
14087
 
 
14088
@item  Add a resource binding
 
14089
 
 
14090
@item  Remove a resource binding
 
14091
 
 
14092
@item  Merge two resource databases
 
14093
 
 
14094
@item  Map a function over the contents of a resource database
 
14095
@end itemize
 
14096
 
 
14097
@defun make-resource-database
 
14098
 
 
14099
@table @var
 
14100
@item resource-database
 
14101
Type @var{resource-database}.
 
14102
@end table
 
14103
 
 
14104
Returns an empty resource database.
 
14105
@end defun
 
14106
 
 
14107
 
 
14108
@defun add-resource database name-list value
 
14109
 
 
14110
@table @var
 
14111
@item database
 
14112
The @var{resource-database} for the new resource binding.
 
14113
@item name-list
 
14114
A list containing strings or symbols specifying the name for the resource binding.
 
14115
@item value
 
14116
The value associated with the @emph{name-list} in the resource binding. This can be an object of any type.
 
14117
@end table
 
14118
 
 
14119
Adds the resource binding specified by @emph{name-list} and
 
14120
@emph{value} to the given @emph{database}. Only one value can be
 
14121
associated with the @emph{name-list} in the @emph{database}. This
 
14122
function replaces any value previously associated with the
 
14123
@emph{name-list}.
 
14124
 
 
14125
 
 
14126
 
 
14127
@end defun
 
14128
 
 
14129
 
 
14130
@defun delete-resource database name-list
 
14131
 
 
14132
@table @var
 
14133
@item database
 
14134
The @var{resource-database} containing the resource binding.
 
14135
@item name-list
 
14136
A list containing strings or symbols specifying the name for the deleted resource binding.
 
14137
@end table
 
14138
 
 
14139
Removes the resource binding specified by @emph{name-list} from the given @emph{database}.
 
14140
 
 
14141
 
 
14142
 
 
14143
@end defun
 
14144
 
 
14145
 
 
14146
@defun map-resource database function &rest args
 
14147
 
 
14148
@table @var
 
14149
@item database
 
14150
A @var{resource-database}.
 
14151
@item function
 
14152
A @var{function} object or function symbol.
 
14153
@item args
 
14154
A list of arguments to the @emph{function}.
 
14155
@end table
 
14156
 
 
14157
Calls the function for each resource binding in the
 
14158
@emph{database}. For each resource binding consisting of a
 
14159
@emph{name-list} and a @emph{value}, the form
 
14160
(@var{apply} @emph{function name-list value args})
 
14161
is executed.
 
14162
 
 
14163
 
 
14164
 
 
14165
@end defun
 
14166
 
 
14167
 
 
14168
@defun merge-resources from-database to-database
 
14169
 
 
14170
@table @var
 
14171
@item from-database
 
14172
The @var{resource-database} from which resource bindings are read.
 
14173
@item to-database
 
14174
The @var{resource-database} to which resource bindings are added.
 
14175
@end table
 
14176
 
 
14177
 
 
14178
Merges the contents of the @emph{from-database} with the
 
14179
@emph{to-database}. @var{map-resource} invokes @var{add-resource}
 
14180
in order to add each resource binding in the @emph{from-database} to
 
14181
the @emph{to-database}. The updated @emph{to-database} is returned.
 
14182
 
 
14183
@table @var
 
14184
@item to-database
 
14185
Type @var{resource-database}.
 
14186
@end table
 
14187
 
 
14188
@end defun
 
14189
 
 
14190
 
 
14191
@node Accessing Resource Values, Resource Database Files, Basic Resource Database Functions, Resources
 
14192
@section Accessing Resource Values
 
14193
 
 
14194
 
 
14195
The power and flexibility of resource management is the result of the
 
14196
way resource values in a resource database are accessed. A resource
 
14197
binding binding stored in the database generally contains only a partial
 
14198
resource name consisting of a mixture of name and class identifiers and
 
14199
wildcard elements (that is, *). To look up a resource value, an
 
14200
application program starts with two resource name lists of the same
 
14201
length containing no wildcard elements -- a @emph{complete resource
 
14202
name} and a @emph{complete} @emph{resource class}. The lookup
 
14203
algorithm returns the value for the resource binding whose resource name
 
14204
is the closest match to the complete name and class given. The
 
14205
definition of @emph{closest match} takes into account the top-down,
 
14206
parent-child hierarchy of resource names and also the distinction
 
14207
between individual names and class names.
 
14208
 
 
14209
@menu
 
14210
* Complete Names and Classes::
 
14211
* Matching Resource Names::
 
14212
* Resource Access Functions::
 
14213
@end menu
 
14214
 
 
14215
@node Complete Names and Classes, Matching Resource Names, Accessing Resource Values, Accessing Resource Values
 
14216
@subsection Complete Names and Classes
 
14217
 
 
14218
A resource binding contains a resource name list that can contain names,
 
14219
class names, or a mixture of both. A class name is a symbol or string
 
14220
that represents a group of related objects. The set of names used as
 
14221
class names are not specified by CLX. Instead, class names are defined
 
14222
by agreement between those who use class names when creating resource
 
14223
bindings (that is, users) and those who use class names when accessing
 
14224
resource values (that is, application programmers).
 
14225
 
 
14226
In order to access a value in a resource database, an application uses a
 
14227
key consisting of two items: a @emph{complete resource name} and a
 
14228
@emph{complete resource class}. A complete resource name is a resource
 
14229
name list containing no wildcard elements. A complete resource class is
 
14230
a list of exactly the same form. The distinction between a complete
 
14231
resource name and a complete resource class lies in how they are used to
 
14232
access resource bindings. The elements of a complete resource name are
 
14233
interpreted as names of individual objects; the elements of a complete
 
14234
resource class are interpreted as names of object classes. The complete
 
14235
resource name and class lists used in a resource database access must
 
14236
have the same length.
 
14237
 
 
14238
Like any resource name list, a complete resource name consists of a path
 
14239
list and an attribute name. The first path list element is typically a
 
14240
symbol (or string) identifying the application as a whole. The second
 
14241
element can be a screen root identifier. Subsequent elements can be
 
14242
identifiers for each ancestor window of an application window. Thus, a
 
14243
path list typically identifies a specific window by tracing a path to it
 
14244
through the application window hierarchy. The final element of a
 
14245
complete resource name (its attribute name) is typically the name of a
 
14246
specific attribute of the window given by the path list (for example,
 
14247
@code{'background}). An attribute name can refer to a feature
 
14248
associated with the window by the application but not by the X server
 
14249
(for example, a font identifier).  Similarly, a complete resource class
 
14250
typically represents a path to a window in the application window
 
14251
hierarchy and a specific window attribute. However, a complete resource
 
14252
class contains the class name for each window and for the window
 
14253
attribute.
 
14254
 
 
14255
For instance, in the previous example, the @code{mail} application
 
14256
can attempt to look up the value of the @code{background} resource
 
14257
for the @code{reply button} window by using the following complete
 
14258
resource name:
 
14259
 
 
14260
@lisp
 
14261
(mail screen-1 reply background)
 
14262
@end lisp
 
14263
 
 
14264
and the following complete resource class:
 
14265
 
 
14266
@lisp
 
14267
(application root button fill)
 
14268
@end lisp
 
14269
 
 
14270
 
 
14271
This complete resource name contains a path list identifying the reply
 
14272
button window -- @code{(mail screen-1 reply)} -- and an attribute
 
14273
name for the window background. The corresponding resource class
 
14274
contains the class names for the same path list and window attribute.
 
14275
 
 
14276
@node Matching Resource Names, Resource Access Functions, Complete Names and Classes, Accessing Resource Values
 
14277
@subsection Matching Resource Names
 
14278
 
 
14279
 
 
14280
The resource lookup algorithm searches a specified resource data base
 
14281
and returns the value for the resource binding whose resource name is
 
14282
the closest match to a given complete resource name and class. The
 
14283
intent of the lookup algorithm is to formalize an intuitive notion of
 
14284
the closest match.
 
14285
 
 
14286
Precedence is given to a match which begins @emph{higher} in the
 
14287
parent-child contact hierarchy. This allows a resource binding with a
 
14288
partial name to define a resource value shared by all members of a
 
14289
window subtree. For example, suppose the resource database contained the
 
14290
following resource bindings:
 
14291
 
 
14292
@multitable {Resource Name} {Resource Value}
 
14293
@item @code{(mail * background)} @tab @code{'red}
 
14294
@item @code{(* reply background)} @tab @code{'blue}
 
14295
@end multitable
 
14296
 
 
14297
 
 
14298
Suppose an application program searched by using the following complete
 
14299
resource name:
 
14300
 
 
14301
@lisp
 
14302
(mail screen-1 reply background)
 
14303
@end lisp
 
14304
 
 
14305
 
 
14306
then the closest matching value returned would be @code{'red}.
 
14307
 
 
14308
Precedence is given to the more specific match. A name match is more
 
14309
specific than a class match. Either a name or class match is more
 
14310
specific than a wildcard match. For example, suppose the resource
 
14311
database contained the following resource bindings:
 
14312
 
 
14313
@multitable {Resource Name} {Resource Value}
 
14314
@item @code{(mail * background)} @tab @code{'red}
 
14315
@item @code{(mail * fill)} @tab @code{'blue}
 
14316
@end multitable
 
14317
 
 
14318
 
 
14319
Suppose an application program searched by using the following complete
 
14320
resource name and complete resource class:
 
14321
 
 
14322
@lisp
 
14323
(mail screen-1 reply background)
 
14324
(application root button fill)
 
14325
@end lisp
 
14326
 
 
14327
 
 
14328
then the closest matching value returned would be
 
14329
@code{'red}. However, suppose the resource database contained the
 
14330
following resource bindings:
 
14331
 
 
14332
@multitable {Resource Name} {Resource Value}
 
14333
@item @code{(mail * background)} @tab @code{'red}
 
14334
@item @code{(mail * button background)} @tab @code{'blue}
 
14335
@end multitable
 
14336
 
 
14337
 
 
14338
then the closest matching value returned would be @code{'blue}.
 
14339
 
 
14340
@node Resource Access Functions,  , Matching Resource Names, Accessing Resource Values
 
14341
@subsection Resource Access Functions
 
14342
 
 
14343
 
 
14344
The following paragraphs describe the CLX functions used to return a
 
14345
value from a resource database.
 
14346
 
 
14347
@defun get-resource database attribute-name attribute-class path-name path-class
 
14348
 
 
14349
@table @var
 
14350
@item database
 
14351
A @var{resource-database}.
 
14352
@item attribute-name
 
14353
A string or symbol giving an attribute name from a complete resource name.
 
14354
@item attribute-class
 
14355
A string or symbol giving an attribute class name from a complete resource class.
 
14356
@item path-name
 
14357
The path list from a complete resource name. @emph{path-name} and @emph{path-class} must have the same length.
 
14358
@item path-class
 
14359
The path list from a complete resource class. @emph{path-name} and @emph{path-class} must have the same length.
 
14360
@end table
 
14361
 
 
14362
 
 
14363
Returns the value of the resource binding in the @emph{database}
 
14364
whose resource name most closely matches the complete resource
 
14365
name/class given by the @emph{path-name}, @emph{path-class},
 
14366
@emph{attribute-name}, and @emph{attribute-class}. The lookup
 
14367
algorithm implements the precedence rules described previously to
 
14368
determine the closest match. When comparing name elements, case is
 
14369
significant only if both elements are strings; otherwise, element
 
14370
matching is case-insensitive.
 
14371
 
 
14372
@table @var
 
14373
@item value
 
14374
Type @var{t}.
 
14375
@end table
 
14376
 
 
14377
@end defun
 
14378
 
 
14379
 
 
14380
 
 
14381
 
 
14382
 
 
14383
@defun get-search-table database path-name path-class
 
14384
 
 
14385
@table @var
 
14386
@item database
 
14387
A @var{resource-database}.
 
14388
@item path-name
 
14389
The path list from a complete resource name. @emph{path-name} and @emph{path-class}must have the same length.
 
14390
@item path-class
 
14391
The path list from a complete resource class. @emph{path-name} and @emph{path-class} must have the same length.
 
14392
@end table
 
14393
 
 
14394
 
 
14395
Returns a table containing the subset of the @emph{database} that
 
14396
matches the @emph{path-name} and @emph{path-class}. Resources using
 
14397
the same @emph{path-name} and @emph{path-class} can be accessed much
 
14398
more efficiently by using this table as an argument to
 
14399
@var{get-search-resource}.
 
14400
 
 
14401
@table @var
 
14402
@item search-table
 
14403
Type @var{list}.
 
14404
@end table
 
14405
 
 
14406
@end defun
 
14407
 
 
14408
 
 
14409
@defun get-search-resource table attribute-name attribute-class
 
14410
 
 
14411
@table @var
 
14412
@item table
 
14413
A search table returned by @var{get-search-table}.
 
14414
@item attribute-name
 
14415
A string or symbol giving an attribute name from a complete resource name.
 
14416
@item attribute-class
 
14417
A string or symbol giving an attribute class name from a complete resource class.
 
14418
@end table
 
14419
 
 
14420
 
 
14421
Returns the value of the resource binding in the search @emph{table}
 
14422
that most closely matches the @emph{attribute-name} and
 
14423
@emph{attribute-class}. The @emph{table} is computed by
 
14424
@var{get-search-table} and represents a set of resource
 
14425
bindings. The closest match is determined by the same algorithm used
 
14426
in @var{get-resource}.
 
14427
 
 
14428
The following two forms are functionally equivalent:
 
14429
 
 
14430
@lisp
 
14431
(get-resource
 
14432
 database attribute-name attribute-class path-name path-class)
 
14433
 
 
14434
(get-search-resource
 
14435
 (get-search-table database path-name path-class)
 
14436
 attribute-name attribute-class)
 
14437
@end lisp
 
14438
 
 
14439
 
 
14440
However, the hard part of the search is done by
 
14441
@var{get-search-table}. Looking up values for several resource
 
14442
attributes that share the same path list can be done much more
 
14443
efficiently with calls to @var{get-search-resource}.
 
14444
@table @var
 
14445
@item value
 
14446
Type @var{t}.
 
14447
@end table
 
14448
 
 
14449
@end defun
 
14450
 
 
14451
@node Resource Database Files,  , Accessing Resource Values, Resources
 
14452
@section Resource Database Files
 
14453
 
 
14454
 
 
14455
X users and application programs can save resource bindings in a file,
 
14456
using a standard file format shared by all X clients. The following
 
14457
paragraphs describe the CLX functions used to convert between the
 
14458
standard external format of resource files and the internal
 
14459
resource-database format used by application programs.
 
14460
 
 
14461
@defun read-resources database pathname &key :key :test :test-not
 
14462
 
 
14463
@table @var
 
14464
@item database
 
14465
The @var{resource-database} to merge.
 
14466
@item pathname
 
14467
A pathname for the resource file to read.
 
14468
@item :key
 
14469
A function used to convert a value from the resource file into a resource binding value.
 
14470
@item :test
 
14471
@itemx :test-not
 
14472
Functions used to select which resource bindings from the resource file are merged with the @emph{database}.
 
14473
@end table
 
14474
 
 
14475
 
 
14476
 
 
14477
 
 
14478
Reads resource bindings from a resource file in standard X11 format
 
14479
and merges them with the given resource @emph{database}. The
 
14480
@var{:key} function is called to convert a file resource value into
 
14481
the value stored in the @emph{database}. By default, @var{:key} is
 
14482
@var{#'identity}. The @var{:test} and @var{:test-not} functions
 
14483
are predicates that select resource bindings to merge, based on the
 
14484
result of the @var{:key} function. For each file resource binding
 
14485
consisting of a @emph{resource-name} and a @emph{resource-value},
 
14486
the @var{:test} (or @var{:test-not}) function is called with the
 
14487
arguments @emph{resource-name} and (@var{funcall} @emph{key
 
14488
resource-value}).
 
14489
 
 
14490
@table @var
 
14491
@item database
 
14492
Type @var{resource-database}.
 
14493
@end table
 
14494
 
 
14495
@end defun
 
14496
 
 
14497
 
 
14498
@defun write-resources database pathname &key :write :test :test-not
 
14499
 
 
14500
@table @var
 
14501
@item database
 
14502
The @var{resource-database} to write.
 
14503
@item pathname
 
14504
A pathname of the file to write.
 
14505
@item :write
 
14506
A function for writing resource values.
 
14507
@item :test
 
14508
@itemx :test-not
 
14509
Functions used to select which resource bindings from the resource file are merged with the @emph{database}.
 
14510
@end table
 
14511
 
 
14512
Writes resource bindings found in the @emph{database} to the file
 
14513
given by the @emph{pathname}. The output file is written in the
 
14514
standard X11 format. The @var{:write} function is used for writing
 
14515
resource values; the default is @var{#'princ}. The @var{:write}
 
14516
function is passed two arguments: a @emph{resource-value} and a
 
14517
@emph{stream}. The @var{:test} and @var{:test-not} functions are
 
14518
predicates which select resource bindings to write. For each
 
14519
resource binding consisting of a @emph{resource-name} and a
 
14520
@emph{resource-value}, the @var{:test} (or @var{:test-not})
 
14521
function is called with the arguments @emph{resource-name} and
 
14522
@emph{resource-value}.
 
14523
 
 
14524
 
 
14525
@end defun
 
14526
 
 
14527
 
 
14528
@node Control Functions, Extensions, Resources, Top
 
14529
@chapter Control Functions
 
14530
 
 
14531
@menu
 
14532
* Grabbing the Server::
 
14533
* Pointer Control::
 
14534
* Keyboard Control::
 
14535
* Keyboard Encodings::
 
14536
* Client Termination::
 
14537
* Managing Host Access::
 
14538
* Screen Saver::
 
14539
@end menu
 
14540
 
 
14541
@node Grabbing the Server, Pointer Control, Control Functions, Control Functions
 
14542
@section Grabbing the Server
 
14543
 
 
14544
 
 
14545
Certain cases may require that a client demand exclusive access to the
 
14546
server, causing the processing for all other clients to be
 
14547
suspended. Such exclusive access is referred to as @emph{grabbing the
 
14548
server}. CLX provides functions to grab and release exclusive access
 
14549
to the server. These function should be used rarely and always with
 
14550
extreme caution, since they have the potential to disrupt the entire
 
14551
window system for all clients.
 
14552
 
 
14553
@defun grab-server display
 
14554
 
 
14555
@table @var
 
14556
@item display
 
14557
A @var{display}.
 
14558
@end table
 
14559
 
 
14560
Disables processing of requests and close-downs on all connections
 
14561
other than the one on which this request arrived.
 
14562
 
 
14563
 
 
14564
@end defun
 
14565
 
 
14566
@defun ungrab-server display
 
14567
 
 
14568
@table @var
 
14569
@item display
 
14570
A @var{display}.
 
14571
@end table
 
14572
 
 
14573
Restarts processing of requests and close-downs on other
 
14574
connections.
 
14575
 
 
14576
 
 
14577
@end defun
 
14578
 
 
14579
 
 
14580
@defmac with-server-grabbed display &body body
 
14581
 
 
14582
Grabs the @emph{display} server only within the dynamic extent of
 
14583
the @emph{body}. @var{ungrab-server} is automatically called upon
 
14584
exit from the @emph{body}. This macro provides the most reliable way
 
14585
for CLX clients to grab the server.
 
14586
 
 
14587
@table @var
 
14588
@item display
 
14589
A @var{display}.
 
14590
@item body
 
14591
The forms to execute while the server is grabbed.
 
14592
@end table
 
14593
 
 
14594
@end defmac
 
14595
 
 
14596
 
 
14597
@node Pointer Control, Keyboard Control, Grabbing the Server, Control Functions
 
14598
@section Pointer Control
 
14599
 
 
14600
 
 
14601
The following paragraphs describe the CLX functions used to:
 
14602
@itemize @bullet
 
14603
 
 
14604
@item  Return or change the pointer acceleration and acceleration threshold
 
14605
 
 
14606
@item  Return or change the mapping of pointer button numbers
 
14607
@end itemize
 
14608
 
 
14609
@defun change-pointer-control display &key :acceleration :threshold
 
14610
 
 
14611
@table @var
 
14612
@item display
 
14613
A @var{display}.
 
14614
@item :acceleration
 
14615
A number for the acceleration ratio.
 
14616
@item :threshold
 
14617
The number of pixels required for acceleration to take effect.
 
14618
@end table
 
14619
 
 
14620
Changes the acceleration and/or the acceleration threshold of the
 
14621
pointer for the @emph{display}.  The @var{:acceleration} number is
 
14622
used as a multiplier, typically specified as a rational number of
 
14623
the form @emph{C/P}, where @emph{C} is the number of pixel positions
 
14624
of cursor motion displayed for @emph{P} units of pointer device
 
14625
motion. The acceleration only occurs if the pointer moves more that
 
14626
@var{:threshold} pixels at once, and only applies to the motion
 
14627
beyond the @var{:threshold}. Either @var{:acceleration} or
 
14628
@var{:threshold} can be set to @var{:default}, that restores the
 
14629
default settings of the server.
 
14630
 
 
14631
 
 
14632
@end defun
 
14633
 
 
14634
 
 
14635
@defun pointer-control display
 
14636
 
 
14637
@table @var
 
14638
@item display
 
14639
A @var{display}.
 
14640
@end table
 
14641
 
 
14642
 
 
14643
Returns the acceleration and threshold for the @emph{display}
 
14644
pointer.
 
14645
@table @var
 
14646
@item acceleration
 
14647
@itemx threshold
 
14648
Type @var{number}.
 
14649
@end table
 
14650
 
 
14651
@end defun
 
14652
 
 
14653
 
 
14654
@defun pointer-mapping display &key (:result-type 'list)
 
14655
 
 
14656
@table @var
 
14657
@item display
 
14658
A @var{display}.
 
14659
@item :result-type
 
14660
The type of sequence to return.
 
14661
@end table
 
14662
 
 
14663
 
 
14664
Returns or (with @code{setf}) changes the mapping of button numbers
 
14665
for the @emph{display} pointer.  The @var{:result-type} is not used
 
14666
when changing the mapping. If element @emph{i} of the mapping
 
14667
sequence is @emph{j}, then the events from pointer button @emph{j}
 
14668
are reported by the server as events for button @emph{i}+1. (Note
 
14669
that pointer buttons are numbered beginning with one, while the
 
14670
mapping sequence itself is indexed normally from zero.) If element
 
14671
@emph{i} of the mapping sequence is zero, then button @emph{i}+1 is
 
14672
disabled and can no longer generate input events. No two elements of
 
14673
the mapping can have the same non-zero value.
 
14674
 
 
14675
The length of the mapping sequence indicates the actual number of
 
14676
buttons on the device. When changing the mapping, the new mapping
 
14677
must have this same length.
 
14678
@table @var
 
14679
@item mapping
 
14680
Type @var{sequence} or @var{card8}@emph{.}
 
14681
@end table
 
14682
 
 
14683
@end defun
 
14684
 
 
14685
 
 
14686
@node Keyboard Control, Keyboard Encodings, Pointer Control, Control Functions
 
14687
@section Keyboard Control
 
14688
 
 
14689
 
 
14690
The following paragraphs describe the CLX functions used to:
 
14691
@itemize @bullet
 
14692
 
 
14693
@item  Return or change keyboard controls
 
14694
 
 
14695
@item  Ring the keyboard bell
 
14696
 
 
14697
@item  Return or change the mapping of modifiers
 
14698
 
 
14699
@item  Return the current up/down state of all keys
 
14700
@end itemize
 
14701
 
 
14702
@defun bell display &optional (percent-from-normal 0)
 
14703
 
 
14704
@table @var
 
14705
@item display
 
14706
A @var{display}.
 
14707
@item percent-from-normal
 
14708
An integer (-100 through 100).
 
14709
@end table
 
14710
 
 
14711
Rings the bell on the keyboard at a volume relative to the base volume for the keyboard,
 
14712
if possible. Percent can range from -100 to 100 inclusive, or else a Value error occurs.
 
14713
The following is the bell volume when percent is non-negative:
 
14714
 
 
14715
@lisp
 
14716
(- (+ @emph{base percent}) (@var{quotient} (* @emph{base percent}) 100))
 
14717
@end lisp
 
14718
 
 
14719
and when percent is negative:
 
14720
 
 
14721
@lisp
 
14722
(+ @emph{base} (@var{quotient} (* @emph{base percent}) 100))
 
14723
@end lisp
 
14724
 
 
14725
 
 
14726
 
 
14727
@end defun
 
14728
 
 
14729
 
 
14730
@defun change-keyboard-control display &key :key-click-percent :bell-percent :bell-pitch :bell-duration :led :led-mode :key :auto-repeat-mode
 
14731
 
 
14732
@table @var
 
14733
@item display
 
14734
A @var{display}.
 
14735
@item :key-click-percent
 
14736
An integer (0 100).
 
14737
@item :bell-percent
 
14738
An integer (0 100).
 
14739
@item :bell-pitch
 
14740
A @var{card16}.
 
14741
@item :bell-duration
 
14742
A @var{card16}.
 
14743
@item :led
 
14744
A @var{card8}.
 
14745
@item :led-mode
 
14746
Either @var{:on} or @var{:off}.
 
14747
@item :key
 
14748
A @var{card8} keycode.
 
14749
@item :auto-repeat-mode
 
14750
Either @var{:on}, @var{:off}, or @var{:default}.
 
14751
@end table
 
14752
 
 
14753
Changes the various aspects of the keyboard. The keyword arguments
 
14754
specify which controls to change.
 
14755
 
 
14756
The @var{:key-click-percent} keyword sets the volume for key
 
14757
clicks, if possible. A value of 0 implies off, while a value of 100
 
14758
implies loud. Setting @var{:key-click-percent} to @var{:default}
 
14759
restores the default value.
 
14760
 
 
14761
The @var{:bell-percent} sets the base volume for the bell between 0
 
14762
(off) and 100 (loud) if possible. Setting @var{:bell-percent} to
 
14763
@var{:default} restores the default value.
 
14764
 
 
14765
The @var{:bell-pitch} sets the pitch (specified in Hz) of the bell,
 
14766
if possible. Setting the @var{:bell-pitch} to @var{:default}
 
14767
restores the default value. The @var{:bell-duration} sets the
 
14768
duration ( specified in milliseconds) of the bell, if
 
14769
possible. Setting @var{:bell-pitch} to @var{:default} restores the
 
14770
default. Note that a bell generator connected with the console but
 
14771
not directly on the keyboard is treated as if it were part of the
 
14772
keyboard.
 
14773
 
 
14774
If both @var{:led-mode} and @var{:led} are specified, then the
 
14775
state of that LED is changed, if possible. If only @var{:led-mode}
 
14776
is specified, the state of all LEDs are changed, if possible. At
 
14777
most 32 LEDs are supported, numbered from one. No standard
 
14778
interpretation of the LEDs are defined.
 
14779
 
 
14780
If both @var{:auto-repeat-mode} and @var{:key} are specified, the
 
14781
auto-repeat mode of that key is changed, if possible. If only
 
14782
@var{:auto-repeat-mode} is specified, the global auto-repeat mode
 
14783
for the entire keyboard is changed, if possible, without affecting
 
14784
the per-key settings. An error occurs if @var{:key} is specified
 
14785
without @var{:auto-repeat-mode}.
 
14786
 
 
14787
 
 
14788
@end defun
 
14789
 
 
14790
 
 
14791
@defun keyboard-control display
 
14792
 
 
14793
@table @var
 
14794
@item display
 
14795
A @var{display}.
 
14796
@end table
 
14797
 
 
14798
 
 
14799
Returns the current control values for the keyboard. For the LEDs,
 
14800
the least significant bit of @emph{led-mask} corresponds to LED one,
 
14801
and each one bit in @emph{led-mask} indicates an LED that is
 
14802
lit. @emph{auto-repeats} is a bit vector; each one bit indicates
 
14803
that auto-repeat is enabled for the corresponding key. The vector is
 
14804
represented as 32 bytes. Byte @emph{n} (from 0) contains the bits
 
14805
for keys 8@emph{n} to 8@emph{n}+7, with the least significant bit in
 
14806
the byte representing key 8@emph{n}.
 
14807
@table @var
 
14808
@item key-click-percent
 
14809
@itemx bell-percent
 
14810
Type @var{card8}.
 
14811
@item bell-pitch
 
14812
@itemx bell-duration
 
14813
Type @var{card16}.
 
14814
@item led-mask
 
14815
Type @var{card32}.
 
14816
@item global-auto-repeat
 
14817
Either @var{:on} or @var{:off}.
 
14818
@item auto-repeats
 
14819
Type @var{bit-vector}.
 
14820
@end table
 
14821
 
 
14822
@end defun
 
14823
 
 
14824
 
 
14825
@defun modifier-mapping display
 
14826
 
 
14827
@table @var
 
14828
@item display
 
14829
A @var{display}.
 
14830
@end table
 
14831
 
 
14832
 
 
14833
Returns the set of keycodes used for each modifier on the
 
14834
@emph{display} keyboard. Each return value is a list of the
 
14835
@var{card8} keycodes used for each modifier key. The order of
 
14836
keycodes within each list is server-dependent.
 
14837
@table @var
 
14838
@item shift-keycodes
 
14839
@itemx lock-keycodes
 
14840
@itemx control-keycodes
 
14841
@itemx mod1-keycodes
 
14842
@itemx mod2-keycodes
 
14843
@itemx mod3-keycodes
 
14844
@itemx mod4-keycodes
 
14845
@itemx mod5-keycodes
 
14846
Type @var{list} of @var{card8}.
 
14847
@end table
 
14848
 
 
14849
@end defun
 
14850
 
 
14851
 
 
14852
@defun query-keymap display
 
14853
 
 
14854
@table @var
 
14855
@item display
 
14856
A @var{display}.
 
14857
@end table
 
14858
 
 
14859
Returns a bit vector that describes the state of the keyboard. Each
 
14860
one bit indicates that the corresponding key is currently
 
14861
pressed. The vector is represented as 32 bytes. Byte @emph{n} (from
 
14862
0) contains the bits for keys 8@emph{n} to 8@emph{n}+7, with the
 
14863
least significant bit in the byte representing key 8@emph{n}.
 
14864
@table @var
 
14865
@item keymap
 
14866
Type @var{bit-vector} 256.
 
14867
@end table
 
14868
 
 
14869
@end defun
 
14870
 
 
14871
 
 
14872
@defun set-modifier-mapping display &key :shift :lock :control :mod1 :mod2 :mod3 :mod4 :mod5
 
14873
 
 
14874
@table @var
 
14875
@item display
 
14876
A @var{display}.
 
14877
@item :shift
 
14878
@itemx :lock
 
14879
@itemx :control
 
14880
@itemx :mod1
 
14881
@itemx :mod2
 
14882
@itemx :mod3
 
14883
@itemx :mod4
 
14884
@itemx :mod5
 
14885
A sequence of @var{card8} keycodes for the given modifier.
 
14886
@end table
 
14887
 
 
14888
 
 
14889
Changes the set of keycodes mapped to the specified modifier keys on
 
14890
the @emph{display} keyboard. Each keyword argument contains a
 
14891
sequence of new @var{card8} keycodes for a specific modifier. The
 
14892
return value indicates whether the change was completed
 
14893
successfully.
 
14894
 
 
14895
A status of @var{:failed} is returned if hardware limitations
 
14896
prevent the requested change. For example, multiple keycodes per
 
14897
modifier may not be supported, up transitions on a given keycode may
 
14898
not be supported, or autorepeat may be mandatory for a given
 
14899
keycode. If @var{:failed} is returned, the mappings for all
 
14900
modifiers remain unchanged.
 
14901
 
 
14902
A status of @var{:device-busy} is returned if a new keycode given
 
14903
for a modifier was not previously mapped to that modifier and is
 
14904
currently in the down state. In this case, the mappings for all
 
14905
modifiers remain unchanged.
 
14906
@table @var
 
14907
@item status
 
14908
One of @var{:success}, @var{:failed}, or @var{:device-busy}.
 
14909
@end table
 
14910
 
 
14911
@end defun
 
14912
 
 
14913
 
 
14914
@node Keyboard Encodings, Client Termination, Keyboard Control, Control Functions
 
14915
@section Keyboard Encodings
 
14916
 
 
14917
 
 
14918
Handling the great diversity of keyboard devices and international
 
14919
language character encodings is a difficult problem for interactive
 
14920
programs that need to receive text input but must also be portable. The
 
14921
X Window System solves this problem by using different sets of encodings
 
14922
for device keys (@emph{keycodes}) and for character symbols
 
14923
(@emph{keysyms}). Each X server maintains a @emph{keyboard mapping} that
 
14924
associates keycodes and keysyms, and which can be returned or changed by
 
14925
client programs.
 
14926
 
 
14927
To handle text input, a CLX client program must follow these steps:
 
14928
@enumerate
 
14929
 
 
14930
@item
 
14931
Receive a @var{:key-press} (or @var{:key-release}) event containing
 
14932
a keycode.
 
14933
 
 
14934
@item
 
14935
Convert the keycode into its corresponding keysym, based on the
 
14936
current keyboard mapping. See @var{keycode->keysym}.
 
14937
 
 
14938
@item
 
14939
Convert the keysym into the corresponding Common Lisp character. See
 
14940
@var{keysym->character}.
 
14941
@end enumerate
 
14942
 
 
14943
@menu
 
14944
* Keycodes and Keysyms::
 
14945
* Keyboard Mapping::
 
14946
* Using Keycodes and Keysyms::
 
14947
@end menu
 
14948
 
 
14949
@node Keycodes and Keysyms, Keyboard Mapping, Keyboard Encodings, Keyboard Encodings
 
14950
@subsection Keycodes and Keysyms
 
14951
 
 
14952
 
 
14953
A @emph{keycode} represents a physical (or logical) key. In CLX,
 
14954
keycodes are values of type (@var{integer} 8 255). A keycode value
 
14955
carries no intrinsic information, although server implementors may
 
14956
attempt to encode geometry (for example, matrix) information in some
 
14957
fashion so it can be interpreted in a server- dependent fashion. The
 
14958
mapping between keys and keycodes cannot be changed.
 
14959
 
 
14960
A @emph{keysym} is an encoding of a symbol on the cap of a key. In CLX,
 
14961
keysyms are values of type @var{card32}. The set of defined keysyms
 
14962
include the ISO Latin character sets (1-4), Katakana, Arabic, Cyrillic,
 
14963
Greek, Technical, Special, Publishing, APL, Hebrew, and miscellaneous
 
14964
keys found on keyboards (RETURN, HELP, TAB, and so on). The encoding of
 
14965
keysyms is defined by the X Protocol.
 
14966
 
 
14967
A list of keysyms is associated with each keycode. The length of the
 
14968
list can vary with each keycode. The list is intended to convey the set
 
14969
of symbols on the corresponding key. By convention, if the list contains
 
14970
a single keysym and if that keysym is alphabetic and case distinction is
 
14971
relevant, then it should be treated as equivalent to a two-element list
 
14972
of the lowercase and uppercase keysyms. For example, if the list
 
14973
contains the single keysym for uppercase A, the client should treat it
 
14974
as if it were a pair with lowercase as the first keysym and uppercase A
 
14975
as the second keysym.
 
14976
 
 
14977
For any keycode, the first keysym in the list should be chosen as the
 
14978
interpretation of a key press when no modifier keys are down. The second
 
14979
keysym in the list normally should be chosen when the @var{:shift}
 
14980
modifier is on, or when the @var{:lock} modifier is on and @var{:lock}
 
14981
is interpreted as @var{:shift-lock}. When the @var{:lock} modifier is
 
14982
on and is interpreted as @var{:caps-lock}, it is suggested that the
 
14983
@var{:shift} modifier first be applied to choose a keysym, but if that
 
14984
keysym is lowercase alphabetic, the corresponding uppercase keysym
 
14985
should be used instead.
 
14986
 
 
14987
Other interpretations of @var{:caps-lock} are possible; for example, it
 
14988
may be viewed as equivalent to @var{:shift-lock}, but only applying
 
14989
when the first keysym is lowercase alphabetic and the second keysym is
 
14990
the corresponding uppercase alphabetic. No interpretation of keysyms
 
14991
beyond the first two in a list is suggested here. No spatial geometry of
 
14992
the symbols on the key is defined by their order in the keysym list,
 
14993
although a geometry might be defined on a vendor-specific basis. The X
 
14994
server does not use the mapping between keycodes and keysyms. Rather,
 
14995
the X server stores the mapping merely for reading and writing by
 
14996
clients.
 
14997
 
 
14998
@node Keyboard Mapping, Using Keycodes and Keysyms, Keycodes and Keysyms, Keyboard Encodings
 
14999
@subsection Keyboard Mapping
 
15000
 
 
15001
The X server maintains a keyboard mapping that associates each keycode
 
15002
with one or more keysyms. The following paragraphs describe the CLX
 
15003
functions used to return or change the mapping of keycodes.
 
15004
 
 
15005
@defun change-keyboard-mapping display keysyms &key (:start 0) :end
 
15006
 
 
15007
@table @var
 
15008
@item display
 
15009
A @var{display}.
 
15010
@item keysyms
 
15011
A two-dimensional array of keysym (@var{card32}) values.
 
15012
@item :start
 
15013
@itemx :end
 
15014
Indexes for the subsequence of @emph{keysyms} used.
 
15015
@item :first-keycode
 
15016
A @var{card8} defining the first keycode mapping changed.
 
15017
@end table
 
15018
 
 
15019
(@var{:first-keycode :start})
 
15020
 
 
15021
Changes the mapping of keycodes to @emph{keysyms}. A
 
15022
@var{:mapping-notify} event is generated for all clients.
 
15023
 
 
15024
The new @emph{keysyms} are specified as a two-dimensional array in
 
15025
which:
 
15026
 
 
15027
(@var{aref} @emph{keysyms} (+ @var{:start} @emph{i}) @emph{j})
 
15028
 
 
15029
is @emph{keysym j} associated with keycode (+ @var{:first-keycode}
 
15030
@emph{i}). The maximum number of @emph{keysyms} associated with any
 
15031
one keycode is given by:
 
15032
 
 
15033
(@var{array-dimension} @emph{keysyms} 1)
 
15034
 
 
15035
@emph{keysyms} should contain @var{nil} elements to represent those
 
15036
keysyms that are undefined for a given keycode. @var{:start} and
 
15037
@var{:end} define the subsequence of the @emph{keysyms} array that
 
15038
defines the new mapping, and the number of keycode mappings
 
15039
changed. By default, @var{:end} is given by:
 
15040
 
 
15041
(@var{array-dimension} @emph{keysyms} 0)
 
15042
 
 
15043
The keycodes whose mappings are changed are given by
 
15044
@var{:first-keycode} through the following:
 
15045
 
 
15046
(+ @var{:first-keycode} (- @var{:end :start}) -1)
 
15047
 
 
15048
keycodes outside this range of are not
 
15049
affected. @var{:first-keycode} must not be less than
 
15050
(@var{display-min-keycode} @emph{display}), and the last keycode
 
15051
modified must not be greater than (@var{display-max-keycode}
 
15052
@emph{display}).
 
15053
 
 
15054
 
 
15055
@end defun
 
15056
 
 
15057
 
 
15058
 
 
15059
@defun keyboard-mapping display &key :first-keycode :start :end :data
 
15060
 
 
15061
@table @var
 
15062
@item display
 
15063
A @var{display}.
 
15064
@item :first-keycode
 
15065
A @var{card8} defining the first keycode mapping returned.
 
15066
@item :start
 
15067
@itemx :end
 
15068
Indexes for the subsequence of the returned array which is modified.
 
15069
@item :data
 
15070
If given, a two-dimensional array to receive the returned keysyms.
 
15071
@end table
 
15072
Returns the keysyms mapped to the given range of keycodes for the
 
15073
@emph{display} keyboard.  The mappings are returned in the form of a
 
15074
two-dimensional array of @var{card32} keysym values. The
 
15075
@var{:data} argument, if given, must be a two-dimensional array in
 
15076
which the returned mappings will be stored. In this case:
 
15077
 
 
15078
(@var{array-dimension :data} 1)
 
15079
 
 
15080
defines the maximum number of keysyms returned for any
 
15081
keycode. Otherwise, a new array is created and returned.
 
15082
 
 
15083
Upon return:
 
15084
 
 
15085
(@var{aref} @emph{mappings} (+ @emph{:start i}) @emph{j})
 
15086
 
 
15087
will contain keysym @emph{j} associated with keycode (+
 
15088
@var{:first-keycode i}) (or @var{nil}, if keysym @emph{j} is
 
15089
undefined for that keycode).
 
15090
 
 
15091
@var{:first-keycode} specifies the first keycode whose mapping is
 
15092
returned; by default, @var{:first-keycode} is
 
15093
(@var{display-min-keycode} @emph{display}). @var{:start} and
 
15094
@var{:end} define the subsequence of the returned array in which
 
15095
the returned mappings are stored. By default, @var{:start} is given
 
15096
by @var{:first-keycode} and @var{:end} is given by:
 
15097
 
 
15098
(1+ (@var{display-max-keycode} @emph{display}))
 
15099
 
 
15100
@var{:first-keycode} must not be less than
 
15101
(@var{display-min-keycode} @emph{display}), and the last keycode
 
15102
returned must not be greater than (@var{display-max-keycode}
 
15103
@emph{display}).
 
15104
@table @var
 
15105
@item mappings
 
15106
Type (@var{array card32} (* *)).
 
15107
@end table
 
15108
 
 
15109
@end defun
 
15110
 
 
15111
 
 
15112
@node Using Keycodes and Keysyms,  , Keyboard Mapping, Keyboard Encodings
 
15113
@subsection Using Keycodes and Keysyms
 
15114
 
 
15115
 
 
15116
The following paragraphs describe the CLX functions used to:
 
15117
@itemize @bullet
 
15118
 
 
15119
@item  Convert a keycode into a keysym
 
15120
 
 
15121
@item  Convert a keysym into a character
 
15122
@end itemize
 
15123
 
 
15124
@defun keycode->keysym display keycode keysym-index
 
15125
 
 
15126
@table @var
 
15127
@item display
 
15128
A @var{display}.
 
15129
@item keycode
 
15130
A @var{card8}.
 
15131
@item keysym-index
 
15132
A @var{card8}.
 
15133
@end table
 
15134
 
 
15135
 
 
15136
Returns the @emph{keysym} at the given @emph{keysym-index} from the
 
15137
keysym list for the @emph{keycode} in the current keyboard mapping
 
15138
for the @emph{display} server.
 
15139
@emph{This function was called keycode-keysym in X11R4 and older versions of CLX.}
 
15140
@table @var
 
15141
@item keysym
 
15142
Type @var{keysym}.
 
15143
@end table
 
15144
 
 
15145
@end defun
 
15146
 
 
15147
 
 
15148
@defun keysym->character display keysym &optional (state 0)
 
15149
 
 
15150
@table @var
 
15151
@item display
 
15152
A @var{display}.
 
15153
@item keysym
 
15154
A @var{keysym}.
 
15155
@item state
 
15156
A @var{mask16}.
 
15157
@end table
 
15158
 
 
15159
Returns the @emph{character} associated with the @emph{keysym} and
 
15160
the @emph{state}. The @emph{state} is a @var{mask16} bit mask
 
15161
representing the state of the @emph{display} modifier keys and
 
15162
pointer buttons. See @var{state-mask-key} in @ref{Data Types}. If the @emph{keysym} does not represent a Common Lisp
 
15163
character, then @var{nil} is returned.
 
15164
@emph{This function was called keysym-character in X11R4 and older versions of CLX.}
 
15165
 
 
15166
The @emph{state} determines the bits attribute of the returned
 
15167
@emph{character}, as follows:
 
15168
@table @var
 
15169
@item :control
 
15170
@var{char-control-bit}
 
15171
@item :mod-1
 
15172
@var{char-meta-bit}
 
15173
@item :mod-2
 
15174
@var{char-super-bit}
 
15175
@item :mod-3
 
15176
@var{char-hyper-bit}
 
15177
@end table
 
15178
 
 
15179
@c Of course *we* know that this mapping is bull shit!
 
15180
@table @var
 
15181
@item character
 
15182
Type @var{character} or @var{null}.
 
15183
@end table
 
15184
 
 
15185
@end defun
 
15186
 
 
15187
 
 
15188
@node Client Termination, Managing Host Access, Keyboard Encodings, Control Functions
 
15189
@section Client Termination
 
15190
 
 
15191
 
 
15192
The CLX functions affecting client termination are discussed in the
 
15193
following paragraphs.
 
15194
 
 
15195
When a display connection to an X server is closed, whether by an
 
15196
explicit call to @var{close-display} or by some external condition, the
 
15197
server automatically performs a sequence of operations to clean up
 
15198
server state information associated with the closed connection.  The
 
15199
effect of these operations depends the @emph{close-down mode} and the
 
15200
@emph{save-set} that the client has specified for the closed display
 
15201
connection. The close-down mode of a display determines whether server
 
15202
resources allocated by the connection are freed or not. The save-set
 
15203
identifies windows that will remain after the connection is closed.
 
15204
 
 
15205
The display save-set is used primarily by window managers that reparent
 
15206
the top-level windows of other clients. For example, such a window
 
15207
manager can automatically create a frame window that encloses a
 
15208
top-level client window, along with a set of controls used for window
 
15209
management. Ordinarily, termination of the window manager client would
 
15210
then destroy all client windows! However, the window manager can prevent
 
15211
this by adding to its save-set those windows created by other clients
 
15212
that should be preserved.
 
15213
 
 
15214
When a display connection closes, an X server performs the following
 
15215
operations:
 
15216
@enumerate
 
15217
 
 
15218
@item
 
15219
For each selection owned by a window created on the connection, the
 
15220
selection owner is set to @var{nil}.
 
15221
 
 
15222
@item
 
15223
An active or passive grab established for a window created on the
 
15224
connection is released.
 
15225
 
 
15226
@item
 
15227
If the connection has grabbed the server, the server is ungrabbed.
 
15228
 
 
15229
@item
 
15230
Server resources and colormap cells allocated by the connection are
 
15231
freed and destroyed, depending on the close-down mode, as follows:
 
15232
@itemize @bullet
 
15233
 
 
15234
@item
 
15235
@var{:retain-permanent} -- All resources are marked
 
15236
@emph{permanent}, and no resources are destroyed. These resources
 
15237
can later be destroyed by a call to @var{kill-client}.
 
15238
 
 
15239
@item
 
15240
@var{:retain-temporary} -- All resources are marked
 
15241
@emph{temporary}, and no resources are destroyed. These resources
 
15242
can later be destroyed by a call to @var{kill-client} or
 
15243
@var{kill-temporary-clients}.
 
15244
 
 
15245
@item
 
15246
@var{:destroy} -- All resources are destroyed.
 
15247
@end itemize
 
15248
@end enumerate
 
15249
 
 
15250
When server resources allocated by a display connection are destroyed --
 
15251
whether by closing the connection with close-down mode @var{:destroy}
 
15252
or by later calling @var{kill-client} or @var{kill-temporary-clients}
 
15253
-- then an X server performs the following operations on each member of
 
15254
the save-set before actually destroying resources.
 
15255
@enumerate
 
15256
 
 
15257
@item
 
15258
If the save-set window is a descendant of a window created on the
 
15259
connection, the save-set window is reparented. The new parent is the
 
15260
closest ancestor such that the save-set window is no longer a
 
15261
descendant of any window created on the connection. The position of
 
15262
the reparented window with respect to its parent remains unchanged.
 
15263
 
 
15264
@item
 
15265
If the save-set window is unmapped, then it is mapped.
 
15266
@end enumerate
 
15267
 
 
15268
If the last connection open to an X server is closed with close-down
 
15269
mode @var{:destroy}, the server resets its state to restore all initial
 
15270
defaults. The server state after reset is the same as its initial state
 
15271
when first started. When an X server resets, it performs the following
 
15272
operations:
 
15273
@itemize @bullet
 
15274
 
 
15275
@item
 
15276
All permanent and temporary server resources from previously-closed
 
15277
connections are destroyed.
 
15278
 
 
15279
@item
 
15280
All but the predefined atoms are deleted.
 
15281
 
 
15282
@item
 
15283
All root window properties are deleted.
 
15284
 
 
15285
@item
 
15286
All device control attributes and mappings are restored to their
 
15287
original default values.
 
15288
 
 
15289
@item
 
15290
The default background and cursor for all root windows are restored.
 
15291
 
 
15292
@item
 
15293
The default font path is restored.
 
15294
 
 
15295
@item
 
15296
The input focus is set to @var{:pointer-root}.
 
15297
 
 
15298
@item
 
15299
The access control list is reset.
 
15300
@end itemize
 
15301
 
 
15302
The following paragraphs describe the CLX functions used to:
 
15303
@itemize @bullet
 
15304
 
 
15305
@item
 
15306
Add or remove a window from a display save-set.
 
15307
 
 
15308
@item
 
15309
Return or change the display close-down mode.
 
15310
 
 
15311
@item
 
15312
Force a connection to be closed or all its server resources to be
 
15313
destroyed.
 
15314
 
 
15315
@item
 
15316
Force a connection to be closed and all temporary resources to be
 
15317
destroyed.
 
15318
@end itemize
 
15319
 
 
15320
@defun add-to-save-set window
 
15321
 
 
15322
@table @var
 
15323
@item window
 
15324
A @var{window}.
 
15325
@end table
 
15326
 
 
15327
Adds the specified @emph{window} to the save-set of the
 
15328
@emph{window} display. The @emph{window} must have been created by
 
15329
some other display. Windows are removed automatically from the
 
15330
save-set when they are destroyed.
 
15331
 
 
15332
 
 
15333
@end defun
 
15334
 
 
15335
 
 
15336
@defun close-down-mode display
 
15337
 
 
15338
@table @var
 
15339
@item display
 
15340
A @var{display}.
 
15341
@end table
 
15342
Returns and (with @code{setf}) sets the close-down mode of the
 
15343
client's resources at connection close.
 
15344
@table @var
 
15345
@item mode
 
15346
One of @var{:destroy}, @var{:retain-permanent}, or @var{:retain-temporary}.
 
15347
@end table
 
15348
 
 
15349
@end defun
 
15350
 
 
15351
 
 
15352
@defun kill-client display resource-id
 
15353
 
 
15354
@table @var
 
15355
@item display
 
15356
A @var{display}.
 
15357
@item resource-id
 
15358
A valid @var{card29} resource ID.
 
15359
@end table
 
15360
 
 
15361
Closes the display connection which created the given
 
15362
@emph{resource-id}. The @emph{resource-id} must be valid, but need
 
15363
not belong to the given @emph{display}.
 
15364
 
 
15365
If the closed connection was previously open, the connection is
 
15366
closed according to its close-down mode. Otherwise, if the
 
15367
connection had been previously terminated with close-down mode
 
15368
@var{:retain-permanent} or @var{:retain-temporary}, then all its
 
15369
retained server resources -- both permanent and temporary -- are
 
15370
destroyed.
 
15371
 
 
15372
 
 
15373
@end defun
 
15374
 
 
15375
 
 
15376
@defun kill-temporary-clients display
 
15377
 
 
15378
@table @var
 
15379
@item display
 
15380
A @var{display}.
 
15381
@end table
 
15382
 
 
15383
Closes the @emph{display} connection and destroys all retained
 
15384
temporary server resources for this and all previously-terminated
 
15385
connections.
 
15386
 
 
15387
If the @emph{display} connection was previously open, the connection
 
15388
is closed according to its close-down mode. Otherwise, if the
 
15389
@emph{display} connection had been previously terminated with
 
15390
close-down mode @var{:retain-permanent} or
 
15391
@var{:retain-temporary}, then all its retained server resources --
 
15392
both permanent and temporary -- are destroyed.
 
15393
 
 
15394
 
 
15395
@end defun
 
15396
 
 
15397
 
 
15398
@defun remove-from-save-set window
 
15399
 
 
15400
@table @var
 
15401
@item window
 
15402
A @var{window}.
 
15403
@end table
 
15404
 
 
15405
Removes the specified @emph{window} from the save-set of the
 
15406
@emph{window} display. The @emph{window} must have been created by
 
15407
some other display. Windows are removed automatically from the
 
15408
save-set when they are destroyed.
 
15409
 
 
15410
 
 
15411
@end defun
 
15412
 
 
15413
 
 
15414
@node Managing Host Access, Screen Saver, Client Termination, Control Functions
 
15415
@section Managing Host Access
 
15416
 
 
15417
 
 
15418
An X server maintains a list of hosts from which client programs can be
 
15419
run. Only clients executing on hosts that belong to this @emph{access
 
15420
control list} are allowed to open a connection to the
 
15421
server. Typically, the access control list can be changed by clients
 
15422
running on the same host as the server. Some server implementations can
 
15423
also implement other authorization mechanisms in addition to, or in
 
15424
place of, this mechanism.  The action of this mechanism can be
 
15425
conditional based on the authorization protocol name and data received
 
15426
by the server at connection setup.
 
15427
 
 
15428
The following paragraphs describe the CLX functions used to:
 
15429
@itemize @bullet
 
15430
 
 
15431
@item  Add or remove hosts on the access control list.
 
15432
 
 
15433
@item  Return the hosts on the access control list.
 
15434
 
 
15435
@item  Return or change the state of the access control list mechanism
 
15436
@end itemize
 
15437
 
 
15438
@defun access-control display
 
15439
 
 
15440
@table @var
 
15441
@item display
 
15442
A @var{display}.
 
15443
@end table
 
15444
Returns and (with @code{setf}) changes the state of the access
 
15445
control list mechanism for the @emph{display} server. Returns true
 
15446
if access control is enabled; otherwise, @var{nil} is returned. If
 
15447
enabled, the access control list is used to validate each client
 
15448
during connection setup.
 
15449
 
 
15450
Only a client running on the same host as the server is allowed to
 
15451
enable or disable the access control list mechanism.
 
15452
@table @var
 
15453
@item enabled-p
 
15454
Type @var{boolean}.
 
15455
@end table
 
15456
 
 
15457
@end defun
 
15458
 
 
15459
 
 
15460
@defun access-hosts display &key (:result-type 'list)
 
15461
 
 
15462
@table @var
 
15463
@item display
 
15464
A @var{display}.
 
15465
@item :result-type
 
15466
The type of hosts sequence to return.
 
15467
@end table
 
15468
Returns a sequence containing the @emph{hosts} that belong to the
 
15469
access control list of the @emph{display} server. Elements of the
 
15470
returned @emph{hosts} sequence are either strings or some other type
 
15471
of object recognized as a host name by @var{add-access-host} and
 
15472
@var{remove-access-host}.  The second returned value specifies
 
15473
whether the access control list mechanism is currently enabled or
 
15474
disabled (see @var{access-control}).
 
15475
@table @var
 
15476
@item hosts
 
15477
@var{sequence} of @var{string}.
 
15478
@item enabled-p
 
15479
Type @var{boolean}.
 
15480
@end table
 
15481
 
 
15482
@end defun
 
15483
 
 
15484
 
 
15485
@defun add-access-host display host
 
15486
 
 
15487
@table @var
 
15488
@item display
 
15489
A @var{display}.
 
15490
@item host
 
15491
A host name. Either a string or some other implementation-dependent type.
 
15492
@end table
 
15493
 
 
15494
Adds the specified @emph{host} to the access control list. Only a
 
15495
client running on the same host as the server can change the access
 
15496
control list.
 
15497
 
 
15498
 
 
15499
@end defun
 
15500
 
 
15501
 
 
15502
@defun remove-access-host display host
 
15503
 
 
15504
@table @var
 
15505
@item display
 
15506
A @var{display}.
 
15507
@item host
 
15508
A host name. Either a string or some other implementation-dependent type.
 
15509
@end table
 
15510
 
 
15511
Removes the specified @emph{host} from the access control list. Only
 
15512
a client running on the same host as the server can change the
 
15513
access control list.
 
15514
 
 
15515
 
 
15516
@end defun
 
15517
 
 
15518
 
 
15519
@node Screen Saver,  , Managing Host Access, Control Functions
 
15520
@section Screen Saver
 
15521
 
 
15522
 
 
15523
To prevent monitor damage, an X server implements a screen saver
 
15524
function which blanks screens during periods of unuse. The screen saver
 
15525
can be in one of three states:
 
15526
@itemize @bullet
 
15527
 
 
15528
@item
 
15529
Disabled -- No screen blanking is done and screen content remains unchanged.
 
15530
 
 
15531
@item
 
15532
Deactivated -- The server is being used. When the server input devices
 
15533
are unused for a specific amount of time, the screen saver becomes
 
15534
activated.
 
15535
 
 
15536
@item
 
15537
Activated -- The server input devices are unused. The screen saver
 
15538
blanks all server screens or displays a server-dependent image. As
 
15539
soon as an input event from either the pointer or the keyboard occurs,
 
15540
the screen saver is deactivated and its timer is reset.
 
15541
@end itemize
 
15542
 
 
15543
The following paragraphs describe the CLX functions used to:
 
15544
@itemize @bullet
 
15545
 
 
15546
@item
 
15547
Return or change screen saver control values.
 
15548
 
 
15549
@item
 
15550
Activate or reset the screen saver
 
15551
@end itemize
 
15552
 
 
15553
@defun activate-screen-saver display
 
15554
 
 
15555
@table @var
 
15556
@item display
 
15557
A @var{display}.
 
15558
@end table
 
15559
 
 
15560
Activates the screen saver for the @emph{display} server.
 
15561
 
 
15562
 
 
15563
@end defun
 
15564
 
 
15565
 
 
15566
@defun reset-screen-saver display
 
15567
 
 
15568
@table @var
 
15569
@item display
 
15570
A @var{display}.
 
15571
@end table
 
15572
 
 
15573
Deactivates the screen saver for the @emph{display} server (if
 
15574
necessary) and resets its timer, just as if a pointer or keyboard
 
15575
event had occurred.
 
15576
 
 
15577
 
 
15578
@end defun
 
15579
 
 
15580
 
 
15581
@defun screen-saver display
 
15582
 
 
15583
@table @var
 
15584
@item display
 
15585
A @var{display}.
 
15586
@end table
 
15587
Returns the current control values for the @emph{display} server
 
15588
screen saver. See @var{set-screen-saver}.
 
15589
@table @var
 
15590
@item timeout
 
15591
@itemx period
 
15592
Type @var{int16}.
 
15593
@item blanking
 
15594
@itemx exposures
 
15595
One of @var{:yes} or @var{:no}.
 
15596
@end table
 
15597
 
 
15598
@end defun
 
15599
 
 
15600
 
 
15601
@defun set-screen-saver display timeout period blanking exposures
 
15602
 
 
15603
@table @var
 
15604
@item display
 
15605
A @var{display}.
 
15606
@item timeout
 
15607
Specifies the delay until timeout takes over.
 
15608
@item period
 
15609
Specifies the periodic change interval, if used.
 
15610
@item blanking
 
15611
Specifies whether the blanking option is available.
 
15612
@item exposures
 
15613
Specifies whether exposures are allowed during blanking.
 
15614
@end table
 
15615
 
 
15616
Changes the current control values for the @emph{display} server
 
15617
screen saver. The screen saver is reset. The screen saver is also
 
15618
disabled if:
 
15619
@itemize @bullet
 
15620
 
 
15621
@item
 
15622
@emph{timeout} is zero, or
 
15623
 
 
15624
@item
 
15625
Both @emph{blanking} and @emph{exposures} are disabled and the
 
15626
server cannot regenerate the screen contents without sending
 
15627
@var{:exposure} events.
 
15628
@end itemize
 
15629
 
 
15630
The @emph{timeout} specifies the (non-negative) number of seconds of
 
15631
input device inactivity that must elapse before the screen saver is
 
15632
activated. The @emph{timeout} can be set to @var{:default} to
 
15633
restore the server default timeout interval.
 
15634
 
 
15635
If @emph{blanking} is @var{:yes} and the screen hardware supports
 
15636
blanking, blanking is enabled; that is, the screen saver will simply
 
15637
blank all screens when it is activated. @emph{blanking} can be set
 
15638
to @var{:default} to restore the server default state for blanking.
 
15639
 
 
15640
If @emph{exposures} is @var{:yes}, exposures are enabled. If
 
15641
exposures are enabled, or if the server is capable of regenerating
 
15642
screen contents without sending @var{:exposure} events, the screen
 
15643
saver will display some server-dependent image when
 
15644
activated. Frequently, this image will consist of a repeating
 
15645
animation sequence, in which case @emph{period} specifies the (
 
15646
non-negative) number of seconds for each repetition. A @emph{period}
 
15647
of zero is a hint that no repetition should occur.
 
15648
 
 
15649
 
 
15650
@end defun
 
15651
 
 
15652
 
 
15653
 
 
15654
@node Extensions, Errors, Control Functions, Top
 
15655
@chapter Extensions
 
15656
@menu
 
15657
* Extensions (Extensions)::
 
15658
* SHAPE - The X11 Nonrectangular Window Shape Extension::
 
15659
* RENDER - A new rendering system for X11::
 
15660
@end menu
 
15661
 
 
15662
@node Extensions (Extensions), SHAPE - The X11 Nonrectangular Window Shape Extension, Extensions, Extensions
 
15663
@section Extensions
 
15664
 
 
15665
 
 
15666
The X Window System is based on a core protocol which can be extended to
 
15667
provide new functionality. An extension is generally represented by an
 
15668
additional set of requests or event types that are implemented by an X
 
15669
server supporting the extension.  By definition, a client program using
 
15670
an extension may not be portable to other servers.  However, extensions
 
15671
allow different server implementations and different sites to add their
 
15672
own special features to X, without disrupting clients that rely only on
 
15673
the core protocol.
 
15674
 
 
15675
Extensions are identified by assigning them unique name strings and
 
15676
major protocol numbers. A client program can request an X server to use
 
15677
a protocol extension by furnishing the extension protocol number as an
 
15678
argument to @var{open-display}. The X Consortium maintains a registry
 
15679
of standard extension names and protocol numbers.
 
15680
 
 
15681
The following paragraphs describe the CLX functions used to:
 
15682
@itemize @bullet
 
15683
 
 
15684
@item  List all supported extensions.
 
15685
 
 
15686
@item  Find out if a given extension is supported.
 
15687
@end itemize
 
15688
 
 
15689
 
 
15690
@defun list-extensions display &key (:result-type 'list)
 
15691
 
 
15692
@table @var
 
15693
@item display
 
15694
A @var{display}.
 
15695
@item :result-type
 
15696
The type of name sequence to return.
 
15697
@end table
 
15698
Returns a sequence containing the @emph{names} of all extensions
 
15699
supported by the @emph{display} server.
 
15700
@table @var
 
15701
@item names
 
15702
Type @var{sequence} of @var{string}.
 
15703
@end table
 
15704
 
 
15705
@end defun
 
15706
 
 
15707
 
 
15708
@defun query-extension display name
 
15709
 
 
15710
@table @var
 
15711
@item display
 
15712
A @var{display}.
 
15713
@item name
 
15714
An extension name string.
 
15715
@end table
 
15716
 
 
15717
 
 
15718
Returns the @emph{major-opcode} for the given extension @emph{name}
 
15719
support by the @emph{display} server. If the extension is not
 
15720
supported, only @var{nil} values are returned. The extension
 
15721
@emph{name} must contain only ISO Latin-1 characters; case is
 
15722
significant.
 
15723
 
 
15724
If the extension involves additional event types, the
 
15725
@emph{first-event} returned is the base event type code for new
 
15726
events; otherwise, the @emph{first-event} is @var{nil}. If the
 
15727
extension involves additional error codes, the @emph{first-error}
 
15728
returned is the base code for new errors; otherwise, the
 
15729
@emph{first-error} is @var{nil}. The formats of error and event
 
15730
messages sent by the server are completely defined by the extension.
 
15731
@table @var
 
15732
@item major-opcode
 
15733
@itemx first-event
 
15734
@itemx first-error
 
15735
Type @var{card8} or @var{null}.
 
15736
@end table
 
15737
 
 
15738
@end defun
 
15739
 
 
15740
 
 
15741
@node SHAPE - The X11 Nonrectangular Window Shape Extension, RENDER - A new rendering system for X11, Extensions (Extensions), Extensions
 
15742
@section SHAPE - The X11 Nonrectangular Window Shape Extension
 
15743
 
 
15744
 
 
15745
This documentation is yet to be written.
 
15746
 
 
15747
@node RENDER - A new rendering system for X11,  , SHAPE - The X11 Nonrectangular Window Shape Extension, Extensions
 
15748
@section RENDER - A new rendering system for X11
 
15749
 
 
15750
 
 
15751
XRENDER is an experimental step in building a newer and modern graphics rendering
 
15752
system that can keep up with the demands of visual appearance on current user
 
15753
interfaces.
 
15754
 
 
15755
The X Rendering Extension (Render) introduces digital image composition as
 
15756
the foundation of a new rendering model within the X Window System.
 
15757
Rendering geometric figures is accomplished by client-side tesselation into
 
15758
either triangles or trapezoids.  Text is drawn by loading glyphs into the
 
15759
server and rendering sets of them.
 
15760
 
 
15761
@menu
 
15762
* Picture formats::
 
15763
* The picture object::
 
15764
* Glyphs and Glyphsets::
 
15765
* Using glyphs::
 
15766
* Errors (Extensions)::
 
15767
@end menu
 
15768
 
 
15769
@node Picture formats, The picture object, RENDER - A new rendering system for X11, RENDER - A new rendering system for X11
 
15770
@subsection Picture formats
 
15771
 
 
15772
The following is what the X protocol rendering spec has to say about picture formats.
 
15773
@url{http://www.xfree86.org/~keithp/render/protocol.html}
 
15774
 
 
15775
 
 
15776
The @var{picture-format} object holds information needed to translate pixel values
 
15777
into red, green, blue and alpha channels.  The server has a list of picture
 
15778
formats corresponding to the various visuals on the screen.  There are two
 
15779
classes of formats, Indexed and Direct.  Indexed picture-formats hold a list of
 
15780
pixel values and RGBA values while Direct picture-formats hold bit masks for each
 
15781
of R, G, B and A.
 
15782
 
 
15783
 
 
15784
The server must support a direct @var{picture-format} with 8 bits each of red, green,
 
15785
blue and alpha as well as a direct @var{picture-format} with 8 bits of red, green and
 
15786
blue and 0 bits of alpha.  The server must also support direct @var{picture-format}s
 
15787
with 1, 4 and 8 bits of alpha and 0 bits of r, g and b.
 
15788
 
 
15789
 
 
15790
Pixel component values lie in the closed range [0,1].  These values are
 
15791
encoded in a varying number of bits.  Values are encoded in a straight
 
15792
forward manner.  For a component encoded in m bits, a binary encoding b
 
15793
is equal to a component value of b/(2^m-1).
 
15794
 
 
15795
 
 
15796
A direct @var{picture-format} with zero bits of alpha component is declared to have
 
15797
alpha == 1 everywhere.  A direct @var{picture-format} with zero bits of red, green and
 
15798
blue is declared to have red, green, blue == 0 everywhere.  If any of red,
 
15799
green or blue components are of zero size, all are of zero size.  Direct
 
15800
@var{picture-format}s never have colormaps and are therefore screen independent.
 
15801
 
 
15802
 
 
15803
Indexed @var{picture-format}s never have alpha channels and the direct component is all
 
15804
zeros.  Indexed @var{picture-format}s always have a colormap in which the specified
 
15805
colors are allocated read- only and are therefore screen dependent.
 
15806
 
 
15807
These are valid accessors for picture-format objects.
 
15808
 
 
15809
@table @var
 
15810
@item picture-format-display
 
15811
A display
 
15812
@item picture-format-id
 
15813
The X protocol @var{resource-id}
 
15814
@item picture-format-type
 
15815
@code{(member :indexed :direct)}
 
15816
@item picture-format-depth
 
15817
Bitdepth as @var{card8}
 
15818
@item picture-format-red-byte
 
15819
A bitmask
 
15820
@item picture-format-green-byte
 
15821
@itemx picture-format-blue-byte
 
15822
@itemx picture-format-alpha-byte
 
15823
@itemx picture-format-colormap
 
15824
A @var{colormap} or nil
 
15825
@end table
 
15826
 
 
15827
@node The picture object, Glyphs and Glyphsets, Picture formats, RENDER - A new rendering system for X11
 
15828
@subsection The picture object
 
15829
 
 
15830
 
 
15831
The @var{picture} object contains a @var{drawable}, a @var{picture-format} and some
 
15832
rendering state.  More than one @var{picture} can refer to the same @var{drawable}.
 
15833
 
 
15834
 
 
15835
A @var{picture} is almost like a @var{gcontext}, except that it is tied in use to
 
15836
a single @var{drawable}. Another similarity it has with @var{gcontext} is that it is
 
15837
a cached object. Updates are not processed until the @var{picture} is used. This also
 
15838
makes it possible to query state, as there is no such request in XRENDER to do so.
 
15839
 
 
15840
 
 
15841
The @var{picture} object is also a lot like a @var{drawable}, in that it is used as a
 
15842
target for graphics operations. Or at least that it occurs where you would expect a
 
15843
drawable in XRENDER requests.
 
15844
 
 
15845
@defun render-create-picture drawable &key format picture ...
 
15846
 
 
15847
@table @var
 
15848
@item drawable
 
15849
A @var{Drawable}
 
15850
@item format
 
15851
A @var{picture-format}
 
15852
@item picture
 
15853
An existing @var{picture} object to use,
 
15854
one is created if not specified.
 
15855
@item repeat
 
15856
@code{(member :off :on)}
 
15857
@item alpha-map
 
15858
A @var{picture} or @var{:none}
 
15859
@item alpha-x-origin
 
15860
@var{int16}
 
15861
@item alpha-y-origin
 
15862
@var{int16}
 
15863
@item clip-x-origin
 
15864
@var{int16}
 
15865
@item clip-y-origin
 
15866
@var{int16}
 
15867
@item clip-mask
 
15868
A @var{Pixmap} or @var{:none}
 
15869
@item graphics-exposures
 
15870
@code{(member :off :on)}
 
15871
@item subwindow-mode
 
15872
@code{(member :clip-by-children :include-inferiors)}
 
15873
@item poly-edge
 
15874
@code{(member :sharp :smooth)}
 
15875
@item poly-mode
 
15876
@code{(member :precise :imprecise)}
 
15877
@item dither
 
15878
@var{xatom} or @var{:none}
 
15879
@item component-alpha
 
15880
@code{(member :off :on)}
 
15881
@end table
 
15882
This request creates a Picture object.  If the @emph{drawable} is a Window
 
15883
then the Red, Green and Blue masks must match those in the visual for the
 
15884
window else a Match error is generated.
 
15885
 
 
15886
@table @var
 
15887
@item picture
 
15888
A @var{picture}
 
15889
@end table
 
15890
 
 
15891
@end defun
 
15892
 
 
15893
 
 
15894
 
 
15895
@defun render-free-picture picture This request deletes all server resources associated with the picture object.
 
15896
 
 
15897
@table @var
 
15898
@item picture
 
15899
The @var{picture} object to free
 
15900
@end table
 
15901
 
 
15902
 
 
15903
 
 
15904
@end defun
 
15905
 
 
15906
@node Glyphs and Glyphsets, Using glyphs, The picture object, RENDER - A new rendering system for X11
 
15907
@subsection Glyphs and Glyphsets
 
15908
 
 
15909
 
 
15910
A glyph in XRENDER is an alpha mask and an associated orgin, advancement and numeric id. The application refers to them
 
15911
by the numeric id.
 
15912
 
 
15913
Glyphs are stored in a glyph-set. The client is responsible for making sure the glyphs it uses are stored in
 
15914
the glyph-set, or there will be a Glyph-error.
 
15915
 
 
15916
@defun render-create-glyph-set format &key glyph-set
 
15917
 
 
15918
@table @var
 
15919
@item format
 
15920
A @var{picture-format} for the alpha masks that this font will use.
 
15921
@item glyph-set
 
15922
An optional @var{glyph-set} object to initialize with a server side glyphset resource.
 
15923
@end table
 
15924
 
 
15925
 
 
15926
 
 
15927
Creates an initially empty glyph-set for the client to use.
 
15928
@emph{Format} must be a Direct format. When it contains RGB values, the glyphs are composited using
 
15929
component-alpha True, otherwise they are composited using component-alpha False.
 
15930
@end defun
 
15931
 
 
15932
 
 
15933
@defun render-reference-glyph-set existing-glyph-set &key glyph-set
 
15934
 
 
15935
@table @var
 
15936
@item existing-glyph-set
 
15937
An existing @var{glyph-set}
 
15938
@item glyph-set
 
15939
An optional @var{glyph-set}, just like in @var{render-create-glyph-set}
 
15940
@end table
 
15941
 
 
15942
 
 
15943
 
 
15944
Creates a new id refering to the existing-glyph-set. The glyph-set itself will not be freed until all
 
15945
ids has been removed.
 
15946
@end defun
 
15947
 
 
15948
@defun render-free-glyph-set glyph-set
 
15949
 
 
15950
@table @var
 
15951
@item glyph-set
 
15952
A glyphset resource to free
 
15953
@end table
 
15954
 
 
15955
Removes an id to a glyph-set. When all ids have been removed the glyph-set itself is removed.
 
15956
 
 
15957
 
 
15958
 
 
15959
@end defun
 
15960
 
 
15961
@defun render-add-glyph glyph-set id &key x-origin y-origin x-advance y-advance data
 
15962
 
 
15963
@table @var
 
15964
@item glyph-set
 
15965
A @var{glyph-set}
 
15966
@item id
 
15967
@var{card32}
 
15968
@item x-orgin
 
15969
@var{int16}
 
15970
@item y-orgin
 
15971
@var{int16}
 
15972
@item x-advance
 
15973
@var{int16}
 
15974
@item y-advance
 
15975
@var{int16}
 
15976
@item data
 
15977
An @var{array} of @var{card8} bytes.
 
15978
@end table
 
15979
 
 
15980
Associates id with the given description of a glyph. An existing glyph
 
15981
with the same id is replaced.
 
15982
 
 
15983
At the time of writing, only 8bit alpha masks are
 
15984
supported. Experimentation with glyph-sets in other pict-formats
 
15985
needed.
 
15986
 
 
15987
 
 
15988
 
 
15989
@end defun
 
15990
 
 
15991
@defun render-add-glyph-from-picture glyph-set picture &key x-origin y-origin x-advance y-advance width height
 
15992
 
 
15993
@table @var
 
15994
@item glyph-set
 
15995
glyph-set
 
15996
@item picture
 
15997
picture
 
15998
@item x-origin
 
15999
int16
 
16000
@item y-origin
 
16001
int16
 
16002
@item x-advance
 
16003
int16
 
16004
@item y-advance
 
16005
int16
 
16006
@item x
 
16007
int16
 
16008
@item y
 
16009
int16
 
16010
@item width
 
16011
card16
 
16012
@item height
 
16013
card16
 
16014
@end table
 
16015
 
 
16016
 
 
16017
 
 
16018
This request add a glyph to @emph{glyph-set} by copying it from the @emph{x,y} location in the @emph{picture}.
 
16019
 
 
16020
Existing glyphs with the same names are replaced.
 
16021
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.
 
16022
@end defun
 
16023
 
 
16024
@defun render-free-glyphs glyph-set glyphs
 
16025
 
 
16026
@table @var
 
16027
@item glyph-set
 
16028
A @var{glyph-set}
 
16029
@item glyphs
 
16030
sequence of @var{card32}
 
16031
@end table
 
16032
 
 
16033
 
 
16034
 
 
16035
 
 
16036
This request removes @emph{glyphs} from @emph{glyph-set}.
 
16037
Each glyph must exist in @emph{glyph-set} (else a @var{Match} error results).
 
16038
@end defun
 
16039
 
 
16040
@node Using glyphs, Errors (Extensions), Glyphs and Glyphsets, RENDER - A new rendering system for X11
 
16041
@subsection Using glyphs
 
16042
 
 
16043
@defun render-composite-glyph dest glyph-set source dest-x dest-y sequence &key op src-x src-y mask-format start end
 
16044
 
 
16045
@table @var
 
16046
@item dest
 
16047
picture
 
16048
@item glyph-set
 
16049
glyph-set
 
16050
@item source
 
16051
picture
 
16052
@item dest-x
 
16053
int16
 
16054
@item dest-y
 
16055
int16
 
16056
@item sequence
 
16057
 
 
16058
@item op
 
16059
(member clear :src :dst :over :over-reverse :in :in-reverse :out :out-reverse :atop :atop-reverse :xor :add :saturate :maximum)
 
16060
@item src-x
 
16061
int16
 
16062
@item src-y
 
16063
iny16
 
16064
@item mask-format
 
16065
picture-format
 
16066
@item start
 
16067
blah
 
16068
@item end
 
16069
blah
 
16070
@end table
 
16071
 
 
16072
 
 
16073
 
 
16074
 
 
16075
Requests the sequence of glyphs to be drawn with the glyph-set.
 
16076
@end defun
 
16077
 
 
16078
 
 
16079
 
 
16080
@node Errors (Extensions),  , Using glyphs, RENDER - A new rendering system for X11
 
16081
@subsection Errors
 
16082
 
 
16083
What new errors Xrender defines...
 
16084
 
 
16085
@node Errors, Undocumented, Extensions, Top
 
16086
@chapter Errors
 
16087
 
 
16088
@menu
 
16089
* Introduction (Errors)::
 
16090
@end menu
 
16091
 
 
16092
@node Introduction (Errors),  , Errors, Errors
 
16093
@section Introduction
 
16094
 
 
16095
CLX error conditions are hierarchial. The base error condition is
 
16096
@var{x-error}, and all other conditions are built on top of
 
16097
@var{x-error}. @var{x-error} can be built on a lower-level condition
 
16098
that is implementation dependent (this is probably the @var{error}
 
16099
condition).
 
16100
 
 
16101
@defmac define-condition name (parent-types*) [({slot-specifier*}) {option*}]
 
16102
 
 
16103
Any new condition type must be defined with the
 
16104
@var{define-condition} macro. A condition type has a name, parent
 
16105
types, report message, and any number of slot items. See the
 
16106
@emph{Lisp} @emph{Reference} manual for further information
 
16107
regarding @var{define-condition}.
 
16108
 
 
16109
The following are the predefined error conditions that can occur in CLX.
 
16110
@end defmac
 
16111
 
 
16112
 
 
16113
@deftp {Condition} access-error
 
16114
 
 
16115
An @var{access-error} can occur for several reasons:
 
16116
@itemize @bullet
 
16117
 
 
16118
@item
 
16119
A client attempted to grab a key/button combination already
 
16120
grabbed by another client
 
16121
 
 
16122
@item
 
16123
A client attempted to free a colormap entry that it did not already allocate
 
16124
 
 
16125
@item
 
16126
A client attempted to store into a read-only colormap entry
 
16127
 
 
16128
@item
 
16129
A client attempted to modify the access control list from other
 
16130
than the local (or otherwise authorized) host
 
16131
 
 
16132
@item
 
16133
A client attempted to select an event type that another client
 
16134
has already selected, and, that at most, one client can select
 
16135
at a time
 
16136
@end itemize
 
16137
 
 
16138
An @var{access-error} is a special case of the more general
 
16139
@var{request-error} (@pxref{request-error}).
 
16140
@end deftp
 
16141
 
 
16142
 
 
16143
@deftp {Condition} alloc-error
 
16144
 
 
16145
The server failed to allocate the requested resource or server memory.
 
16146
 
 
16147
An @var{alloc-error} is a special case of the more general
 
16148
@var{request-error} (@pxref{request-error}).
 
16149
@end deftp
 
16150
 
 
16151
 
 
16152
@deftp {Condition} atom-error
 
16153
 
 
16154
A value for an @emph{atom} argument does not name a defined atom.
 
16155
 
 
16156
An @var{atom-error} is a special case of the more general
 
16157
@var{request-error} (@pxref{request-error}).
 
16158
@end deftp
 
16159
 
 
16160
 
 
16161
@deftp {Condition} closed-display
 
16162
 
 
16163
The @var{closed-display} condition is signaled when trying to read
 
16164
or write a closed display (that is, @var{close-display} has been
 
16165
called on the @var{display} object, or a server-disconnect
 
16166
occurred). The @var{closed-display} object is reported with the
 
16167
error.
 
16168
 
 
16169
A @var{closed-display} condition is a special case of the more
 
16170
general @var{x-error} (@pxref{x-error}).
 
16171
@end deftp
 
16172
 
 
16173
 
 
16174
@deftp {Condition} colormap-error
 
16175
 
 
16176
A value for a @emph{colormap} argument does not name a defined
 
16177
colormap.
 
16178
 
 
16179
A @var{colormap-error} is a special case of the more general
 
16180
@var{resource-error} (@pxref{resource-error}).
 
16181
@end deftp
 
16182
 
 
16183
 
 
16184
@deftp {Condition} connection-failure
 
16185
 
 
16186
Signaled when an X11 server refuses a connection. The following
 
16187
items are reported along with the error:
 
16188
@itemize @bullet
 
16189
 
 
16190
@item  @emph{major-version} -- The major version of the X server code.
 
16191
 
 
16192
@item  @emph{minor-version} -- The minor version of the X server code.
 
16193
 
 
16194
@item  @emph{host} -- The host name for the X server.
 
16195
 
 
16196
@item  @emph{display} -- The display on which the error occurred.
 
16197
 
 
16198
@item  @emph{reason} -- A string indicating why the connection failed.
 
16199
@end itemize
 
16200
 
 
16201
A @var{connection-failure} is a special case of the more general
 
16202
@var{x-error} (@pxref{x-error}).
 
16203
@end deftp
 
16204
 
 
16205
 
 
16206
@deftp {Condition} cursor-error
 
16207
 
 
16208
A value for a @emph{cursor} argument does not name a defined cursor.
 
16209
 
 
16210
A @var{cursor-error} is a special case of the more general
 
16211
@var{resource-error} (@pxref{resource-error}).
 
16212
@end deftp
 
16213
 
 
16214
 
 
16215
@deftp {Condition} device-busy
 
16216
 
 
16217
Signaled by (@code{setf} (@var{pointer-mapping} @emph{display})
 
16218
@var{mapping}) when the @var{set-pointer-mapping} request returns
 
16219
a busy status. A similar condition occurs in
 
16220
@var{set-modifier-mapping}, but in this case, it returns a boolean
 
16221
indicating success, rather than signaling an error.  The
 
16222
@var{device-busy} condition returns the display object as part of
 
16223
the error.
 
16224
 
 
16225
A @var{device-busy} condition is a special case of the more general
 
16226
@var{x-error} (@pxref{x-error}).
 
16227
@end deftp
 
16228
 
 
16229
 
 
16230
@deftp {Condition} drawable-error
 
16231
 
 
16232
A value for a @emph{drawable} argument does not name a defined window or pixmap.
 
16233
 
 
16234
A @var{drawable-error} is a special case of the more general @var{resource-error} (@pxref{resource-error}).
 
16235
@end deftp
 
16236
 
 
16237
 
 
16238
@deftp {Condition} font-error
 
16239
 
 
16240
A value for a @emph{font} or @emph{gcontext} argument does not name a defined font.
 
16241
 
 
16242
A @var{font-error} is a special case of the more general
 
16243
@var{resource-error} (@pxref{resource-error}).
 
16244
@end deftp
 
16245
 
 
16246
 
 
16247
@deftp {Condition} gcontext-error
 
16248
 
 
16249
A value for a @emph{gcontext} argument does not name a defined GContext.
 
16250
 
 
16251
A @var{gcontext-error} is a special case of the more general
 
16252
@var{resource-error} (@pxref{resource-error}).
 
16253
@end deftp
 
16254
 
 
16255
 
 
16256
@deftp {Condition} id-choice-error
 
16257
 
 
16258
The value chosen for a resource identifier is either not included in
 
16259
the range assigned to the client or is already in use. Under normal
 
16260
circumstances, this cannot occur and should be considered a server
 
16261
or CLX library error.
 
16262
 
 
16263
An @var{id-choice-error} is a special case of the more general
 
16264
@var{resource-error} (@pxref{resource-error}).
 
16265
@end deftp
 
16266
 
 
16267
 
 
16268
@deftp {Condition} implementation-error
 
16269
 
 
16270
The server does not implement some aspect of the request. A server
 
16271
that generates this error for a core request is deficient. As such,
 
16272
this error is not listed for any of the requests.  However, clients
 
16273
should be prepared to receive such errors and either handle or
 
16274
discard them.
 
16275
 
 
16276
An @var{implementation-error} is a special case of the more general
 
16277
@var{resource-error} (@pxref{resource-error}).
 
16278
@end deftp
 
16279
 
 
16280
 
 
16281
@deftp {Condition} length-error
 
16282
 
 
16283
The length of a request is shorter or longer than that minimally
 
16284
required to contain the arguments. This usually means an internal
 
16285
CLX error.
 
16286
 
 
16287
A @var{length-error} is a special case of the more general
 
16288
@var{resource-error} (@pxref{resource-error}).
 
16289
@end deftp
 
16290
 
 
16291
 
 
16292
@deftp {Condition} lookup-error
 
16293
 
 
16294
CLX has the option of caching different resource types (see
 
16295
@var{*clx-cached-types*}) in a hash table by resource ID. When
 
16296
looking up an object in the hash table, if the type of the object is
 
16297
wrong, a @var{lookup-error} is signaled.
 
16298
 
 
16299
For example: The cursor with ID 123 is interned in the hash
 
16300
table. An event is received with a field for window 123. When 123 is
 
16301
looked up in the hash table, a cursor is found.  Since a window was
 
16302
expected, a @var{lookup-error} is signaled. This error indicates a
 
16303
problem with the extension code being used. The following items are
 
16304
reported along with the error:
 
16305
@itemize @bullet
 
16306
 
 
16307
@item  @emph{id} -- The resource ID.
 
16308
 
 
16309
@item  @emph{display} -- The display being used.
 
16310
 
 
16311
@item  @emph{type} -- The resource type.
 
16312
 
 
16313
@item  @emph{object} -- The @var{resource} object.
 
16314
@end itemize
 
16315
 
 
16316
A @var{lookup-error} is a special case of the more general
 
16317
@var{x-error} (@pxref{x-error}).
 
16318
@end deftp
 
16319
 
 
16320
 
 
16321
@deftp {Condition} match-error
 
16322
 
 
16323
In a graphics request, the root and depth of the GContext does not
 
16324
match that of the drawable. An @var{:input-only} window is used as
 
16325
a drawable. Some argument or pair of arguments has the correct type
 
16326
and range but fails to match in some other way required by the
 
16327
request. An @var{:input-only} window locks this attribute. The
 
16328
values do not exist for an @var{:input-only} window.
 
16329
 
 
16330
A @var{match-error} is a special case of the more general
 
16331
@var{request-error} (@pxref{request-error}).
 
16332
@end deftp
 
16333
 
 
16334
 
 
16335
@deftp {Condition} missing-parameter
 
16336
 
 
16337
One or more of the required keyword parameters is missing or
 
16338
@var{nil}. The missing parameters are reported along with the
 
16339
error.
 
16340
 
 
16341
A @var{missing-parameter} condition is a special case of the more
 
16342
general @var{x-error} (@pxref{x-error}).
 
16343
@end deftp
 
16344
 
 
16345
 
 
16346
@deftp {Condition} name-error
 
16347
 
 
16348
A font or color of the specified name does not exist.
 
16349
 
 
16350
A @var{name-error} is a special case of the more general
 
16351
@var{request-error} (@pxref{request-error}).
 
16352
@end deftp
 
16353
 
 
16354
 
 
16355
@deftp {Condition} pixmap-error
 
16356
 
 
16357
A value for a @emph{pixmap} argument does not name a defined pixmap.
 
16358
 
 
16359
A @var{pixmap-error} is a special case of the more general
 
16360
@var{resource-error}. (@pxref{resource-error}.)
 
16361
@end deftp
 
16362
 
 
16363
 
 
16364
@deftp {Condition} reply-length-error (x-error) (slots*)
 
16365
 
 
16366
The reply to a request has an unexpected length. The following items
 
16367
are reported along with the error:
 
16368
@itemize @bullet
 
16369
 
 
16370
@item  @emph{reply-length} -- The actual reply length.
 
16371
 
 
16372
@item  @emph{expected-length} -- The expected reply length.
 
16373
 
 
16374
@item  @emph{display} -- The display on which the error occurred.
 
16375
@end itemize
 
16376
 
 
16377
A @var{reply-length-error} is a special case of the more general
 
16378
@var{x-error} (@pxref{x-error}).
 
16379
@end deftp
 
16380
 
 
16381
 
 
16382
@deftp {Condition} reply-timeout
 
16383
 
 
16384
The @var{*reply-timeout*} parameter specifies the maximum number of
 
16385
seconds to wait for a request reply, or @var{nil} to wait forever
 
16386
(the default). When a reply has not been received after
 
16387
*@var{reply-timeout}* seconds, the @var{reply-timeout} condition
 
16388
is signaled. The @emph{timeout} @emph{period} and @emph{display} are
 
16389
reported along with the error.
 
16390
 
 
16391
A @var{reply-timeout} condition is a special case of the more
 
16392
general @var{x-error} (@pxref{x-error}).
 
16393
@end deftp
 
16394
 
 
16395
 
 
16396
@deftp {Condition} request-error
 
16397
@anchor{request-error}
 
16398
 
 
16399
The following items are reported along with the error:
 
16400
 
 
16401
The major or minor opcode does not specify a valid request.
 
16402
@itemize @bullet
 
16403
 
 
16404
@item  @emph{display} -- The display on which the error occurred.
 
16405
 
 
16406
@item  @emph{error-key} -- The error (sub)type.
 
16407
 
 
16408
@item  @emph{major} -- The major opcode.
 
16409
 
 
16410
@item  @emph{minor} -- The minor opcode.
 
16411
 
 
16412
@item  @emph{sequence} -- The actual sequence number.
 
16413
 
 
16414
@item  @emph{current-sequence} -- The current sequence number.
 
16415
@end itemize
 
16416
 
 
16417
A @var{request-error} condition is a special case of the more
 
16418
general @var{x-error} (@pxref{x-error}).
 
16419
@end deftp
 
16420
 
 
16421
@deftp {Condition} resource-error
 
16422
@anchor{resource-error}
 
16423
 
 
16424
All X11 errors for incorrect resource IDs are built on top of
 
16425
@var{resource-error}. These are @var{colormap-error},
 
16426
@var{cursor-error}, @var{drawable-error}, @var{font-error},
 
16427
@var{gcontext-error}, @var{id-choice-error}, @var{pixmap-error}
 
16428
and @var{window-error}. @var{resource-error} is never signaled
 
16429
directly.
 
16430
 
 
16431
A @var{resource-error} is a special case of the more general
 
16432
@var{request-error} (@pxref{request-error}).
 
16433
@end deftp
 
16434
 
 
16435
 
 
16436
@deftp {Condition} sequence-error
 
16437
 
 
16438
All X11 request replies contain the sequence number of their
 
16439
request. If a reply's sequence does not match the request count, a
 
16440
@var{sequence-error} is signaled. A @var{sequence-error} usually
 
16441
indicates a locking problem with a multi-processing Lisp. The
 
16442
following items are reported along with the error:
 
16443
@itemize @bullet
 
16444
 
 
16445
@item  @emph{display} -- The display on which the error occurred.
 
16446
 
 
16447
@item  @emph{req-sequence} -- The sequence number in the reply.
 
16448
 
 
16449
@item  @emph{msg-sequence} -- The current sequence number.
 
16450
@end itemize
 
16451
 
 
16452
A @var{sequence-error} condition is a special case of the more
 
16453
general @var{x-error}. (@pxref{x-error})
 
16454
@end deftp
 
16455
 
 
16456
 
 
16457
@deftp {Condition} server-disconnect
 
16458
 
 
16459
The connection to the server was lost. The display on which the
 
16460
error occurred is reported along with the error.
 
16461
 
 
16462
A @var{server-disconnect} condition is a special case of the more
 
16463
general @var{x-error}. (@pxref{x-error})
 
16464
@end deftp
 
16465
 
 
16466
 
 
16467
@deftp {Condition} unexpected-reply
 
16468
 
 
16469
A reply was found when none was expected. This indicates a problem
 
16470
with the extension code. The following items are reported along with
 
16471
the error:
 
16472
 
 
16473
@table @code
 
16474
@item  display
 
16475
The display on which the error occurred.
 
16476
 
 
16477
@item  req-sequence
 
16478
The sequence number in the reply.
 
16479
 
 
16480
@item  msg-sequence
 
16481
The current sequence number.
 
16482
 
 
16483
@item  length
 
16484
The message length of the reply.
 
16485
@end table
 
16486
 
 
16487
 
 
16488
An @var{unexpected-reply} condition is a special case of the more general
 
16489
@var{x-error}. (@pxref{x-error}.)
 
16490
@end deftp
 
16491
 
 
16492
 
 
16493
@deftp {Condition} unknown-error (request-error) (error-code)
 
16494
 
 
16495
An error was received from the server with an unknown error
 
16496
code. This indicates a problem with the extension code. The
 
16497
undefined error code is reported.
 
16498
 
 
16499
An @var{unknown-error} is a special case of the more general
 
16500
@var{request-error}. (@pxref{request-error})
 
16501
@end deftp
 
16502
 
 
16503
 
 
16504
@deftp {Condition} value-error (request-error) (value)
 
16505
 
 
16506
Some numeric value falls outside the range of values accepted by the
 
16507
request. Unless a specific range is specified for an argument, the
 
16508
full range defined by the argument's type is accepted. Any argument
 
16509
defined as a set of alternatives can generate this error. The
 
16510
erroneous value is reported.
 
16511
 
 
16512
A @var{value-error} is a special case of the more general
 
16513
@var{request-error}. (@pxref{request-error})
 
16514
@end deftp
 
16515
 
 
16516
 
 
16517
@deftp {Condition} window-error (resource-error)
 
16518
 
 
16519
 
 
16520
A value for a @emph{window} argument does not name a defined window.
 
16521
 
 
16522
A @var{window-error} is a special case of the more general
 
16523
@var{resource-error}. (@pxref{resource-error}.)
 
16524
@end deftp
 
16525
 
 
16526
 
 
16527
@deftp {Condition} x-error
 
16528
@anchor{x-error}
 
16529
 
 
16530
This is the most general error condition upon which all other conditions are defined.
 
16531
@end deftp
 
16532
 
 
16533
 
 
16534
 
 
16535
@ignore
 
16536
@var{PROTOCOL VS. CLX FUNCTIONAL}
 
16537
 
 
16538
@var{CROSS-REFERENCE LISTING}
 
16539
 
 
16540
@var{X11 Request Name CLX Function Name}
 
16541
 
 
16542
AllocColor      @var{alloc-color}
 
16543
AllocColorCells @var{alloc-color-cells}
 
16544
AllocColorPlanes@var{alloc-color-planes}
 
16545
AllocNamedColor @var{alloc-color}
 
16546
AllowEvents     @var{allow-events}
 
16547
Bell  @var{bell}
 
16548
ChangeAccessControl       (@code{setf} (@var{access-control} @emph{display})
 
16549
ChangeActivePointerGrab   @var{change-active-pointer-grab}
 
16550
ChangeCloseDownMode       (@code{setf} (@var{close-down-mode} @emph{display}))
 
16551
ChangeGC        @var{force-gcontext-changes}
 
16552
(See @var{with-gcontext})
 
16553
(@code{setf} (@var{gcontext-function} @emph{gc}))
 
16554
(@code{setf} (@var{gcontext-plane-mask} @emph{gc}))
 
16555
(@code{setf} (@var{gcontext-foreground} @emph{gc}))
 
16556
(@code{setf} (@var{gcontext-background} @emph{gc}))
 
16557
(@code{setf} (@var{gcontext-line-width} @emph{gc}))
 
16558
(@code{setf} (@var{gcontext-line-style} @emph{gc}))
 
16559
(@code{setf} (@var{gcontext-cap-style} @emph{gc}))
 
16560
(@code{setf} (@var{gcontext-join-style} @emph{gc}))
 
16561
(@code{setf} (@var{gcontext-fill-style} @emph{gc}))
 
16562
(@code{setf} (@var{gcontext-fill-rule} @emph{gc}))
 
16563
(@code{setf} (@var{gcontext-tile} @emph{gc}))
 
16564
(@code{setf} (@var{gcontext-stipple} @emph{gc}))
 
16565
(@code{setf} (@var{gcontext-ts-x} @emph{gc}))
 
16566
(@code{setf} (@var{gcontext-ts-y} @emph{gc}))
 
16567
(@code{setf} (@var{gcontext-font} @emph{gc} &optional
 
16568
@var{metrics-p}))
 
16569
(@code{setf} (@var{gcontext-subwindow-mode} @emph{gc}))
 
16570
(@code{setf} (@var{gcontext-exposures} @emph{gc})))
 
16571
(@code{setf} (@var{gcontext-clip-x} @emph{gc}))
 
16572
(@code{setf} (@var{gcontext-clip-y} @emph{gc}))
 
16573
(@code{setf} (@var{gcontext-clip-mask} @emph{gc}
 
16574
&optional @var{ordering}))
 
16575
(@code{setf} (@var{gcontext-dash-offset} @emph{gc}))
 
16576
(@code{setf} (@var{gcontext-dashes} @emph{gc}))
 
16577
(@code{setf} (@var{gcontext-arc-mode} @emph{gc}))
 
16578
(@code{setf} (@var{gcontext-clip-ordering} @emph{gc}))
 
16579
 
 
16580
@var{X11 Request Name CLX Function Name}
 
16581
 
 
16582
ChangeHosts     @var{add-access-host}
 
16583
ChangeHosts     @var{remove-access-host}
 
16584
ChangeKeyboardControl     @var{change-keyboard-control}
 
16585
ChangePointerControl      @var{change-pointer-control}
 
16586
ChangeProperty  @var{change-property}
 
16587
ChangeSaveSet   @var{remove-from-save-set}
 
16588
ChangeSaveSet   @var{add-to-save-set}
 
16589
ChangeWindowAttributes    (See @var{with-state})
 
16590
(@code{setf} (@var{window-background} @emph{window}))
 
16591
(@code{setf} (@var{window-border} @emph{window}))
 
16592
(@code{setf} (@var{window-bit-gravity} @emph{window}))
 
16593
(@code{setf} (@var{window-gravity} @emph{window}))
 
16594
(@code{setf} (@var{window-backing-store} @emph{window}))
 
16595
(@code{setf} (@var{window-backing-planes} @emph{window}))
 
16596
(@code{setf} (@var{window-backing-pixel} @emph{window}))
 
16597
(@code{setf} (@var{window-override-redirect} @emph{window})
 
16598
@code{(setf (window-save-under} @emph{window}@var{))}
 
16599
(@code{setf} (@var{window-colormap} @emph{window}))
 
16600
(@code{setf} (@var{window-cursor} @emph{window}))
 
16601
(@code{setf} (@var{window-event-mask} @emph{window}))
 
16602
(@code{setf} (@var{window-do-not-propagate-mask}
 
16603
@emph{window}))
 
16604
CirculateWindow @var{circulate-window-down}
 
16605
CirculateWindow @var{circulate-window-up}
 
16606
ClearToBackground         @var{clear-area}
 
16607
CloseFont       @var{close-font}
 
16608
ConfigureWindow (See @var{with-state})
 
16609
(@code{setf} (@var{drawable-x} @emph{drawable}))
 
16610
(@code{setf} (@var{drawable-y} @emph{drawabl}e))
 
16611
(@code{setf} (@var{drawable-width} @emph{drawable}))
 
16612
(@code{setf} (@var{drawable-height} @emph{drawable}))
 
16613
(@code{setf} (@var{drawable-depth} @emph{drawable}))
 
16614
(@code{setf} (@var{drawable-border-width} @emph{drawable}))
 
16615
(@code{setf} (@var{window-priority} @emph{window} &optional
 
16616
@var{sibling}))
 
16617
ConvertSelection@var{convert-selection}
 
16618
CopyArea        @var{copy-area}
 
16619
CopyColormapAndFree       @var{copy-colormap-and-free}
 
16620
CopyGC@var{copy-gcontext}
 
16621
CopyGC@var{copy-gcontext-components}
 
16622
CopyPlane       @var{copy-plane}
 
16623
CreateColormap  @var{create-colormap}
 
16624
CreateCursor    @var{create-cursor}
 
16625
CreateGC        @var{create-gcontext}
 
16626
CreateGlyphCursor         @var{create-glyph-cursor}
 
16627
CreatePixmap    @var{create-pixmap}
 
16628
CreateWindow    @var{create-window}
 
16629
DeleteProperty  @var{delete-property}
 
16630
DestroySubwindows         @var{destroy-subwindows}
 
16631
DestroyWindow   @var{destroy-window}
 
16632
FillPoly        @var{draw-lines}
 
16633
ForceScreenSaver@var{reset-screen-saver}
 
16634
ForceScreenSaver@var{activate-screen-saver}
 
16635
FreeColormap    @var{free-colormap}
 
16636
FreeColors      @var{free-colors}
 
16637
FreeCursor      @var{free-cursor}
 
16638
 
 
16639
@var{X11 Request Name CLX Function Name}
 
16640
 
 
16641
FreeGC@var{free-gcontext}
 
16642
FreePixmap      @var{free-pixmap}
 
16643
GetAtomName     @var{atom-name}
 
16644
GetFontPath     @var{font-path}
 
16645
GetGeometry     (See @var{with-state})
 
16646
@var{drawable-root}
 
16647
@var{drawable-x}
 
16648
@var{drawable-y}
 
16649
@var{drawable-width}
 
16650
@var{drawable-height}
 
16651
@var{drawable-depth}
 
16652
@var{drawable-border-width}
 
16653
GetImage        @var{get-raw-image}
 
16654
GetInputFocus   @var{input-focus}
 
16655
GetKeyboardControl        @var{keyboard-control}
 
16656
GetKeyboardMapping        @var{keyboard-mapping}
 
16657
GetModifierMapping        @var{modifier-mapping}
 
16658
GetMotionEvents @var{motion-events}
 
16659
GetPointerControl         @var{pointer-control}
 
16660
GetPointerMapping         @var{pointer-mapping}
 
16661
GetProperty     @var{get-property}
 
16662
GetScreenSaver  @var{screen-saver}
 
16663
GetSelectionOwner         @var{selection-owner}
 
16664
GetWindowAttributes       (See @var{with-state})
 
16665
@var{window-visual}
 
16666
@var{window-class}
 
16667
@var{window-bit-gravity}
 
16668
@var{window-gravity}
 
16669
@var{window-backing-store}
 
16670
@var{window-backing-planes}
 
16671
@var{window-backing-pixel}
 
16672
@var{window-save-under}
 
16673
@var{window-override-redirect}
 
16674
@var{window-event-mask}
 
16675
@var{window-do-not-propagate-mask}
 
16676
@var{window-colormap}
 
16677
@var{window-colormap-installed-p}
 
16678
@var{window-all-event-masks}
 
16679
@var{window-map-state}
 
16680
GrabButton      @var{grab-button}
 
16681
GrabKey         @var{grab-key}
 
16682
GrabKeyboard    @var{grab-keyboard}
 
16683
GrabPointer     @var{grab-pointer}
 
16684
GrabServer      @var{grab-server}
 
16685
ImageText16     @var{draw-image-glyphs}
 
16686
ImageText16     @var{draw-image-glyph}
 
16687
ImageText8      @var{draw-image-glyphs}
 
16688
InstallColormap @var{install-colormap}
 
16689
InternAtom      @var{find-atom}
 
16690
InternAtom      @var{intern-atom}
 
16691
KillClient      @var{kill-temporary-clients}
 
16692
KillClient      @var{kill-client}
 
16693
ListExtensions  @var{list-extensions}
 
16694
ListFonts       @var{list-font-names}
 
16695
ListFontsWithInfo         @var{list-fonts}
 
16696
ListHosts       @var{access-control}
 
16697
 
 
16698
@var{X11 Request Name CLX Function Name}
 
16699
 
 
16700
ListHosts       @var{access-hosts}
 
16701
ListInstalledColormaps    @var{installed-colormaps}
 
16702
ListProperties  @var{list-properties}
 
16703
LookupColor     @var{lookup-color}
 
16704
MapSubwindows   @var{map-subwindows}
 
16705
MapWindow       @var{map-window}
 
16706
OpenFont        @var{open-font}
 
16707
PolyArc         @var{draw-arc}
 
16708
PolyArc         @var{draw-arcs}
 
16709
PolyFillArc     @var{draw-arc}
 
16710
PolyFillArc     @var{draw-arcs}
 
16711
PolyFillRectangle         @var{draw-rectangle}
 
16712
PolyFillRectangle         @var{draw-rectangles}
 
16713
PolyLine        @var{draw-line}
 
16714
PolyLine        @var{draw-lines}
 
16715
PolyPoint       @var{draw-point}
 
16716
PolyPoint       @var{draw-points}
 
16717
PolyRectangle   @var{draw-rectangle}
 
16718
PolyRectangle   @var{draw-rectangles}
 
16719
PolySegment     @var{draw-segments}
 
16720
PolyText16      @var{draw-glyph}
 
16721
PolyText16      @var{draw-glyphs}
 
16722
PolyText8       @var{draw-glyphs}
 
16723
PutImage        @var{put-raw-image}
 
16724
QueryBestSize   @var{query-best-cursor}
 
16725
QueryBestSize   @var{query-best-stipple}
 
16726
QueryBestSize   @var{query-best-tile}
 
16727
QueryColors     @var{query-colors}
 
16728
QueryExtension  @var{query-extension}
 
16729
QueryFont       @var{font-name}
 
16730
@var{font-name}
 
16731
@var{font-direction}
 
16732
@var{font-min-char}
 
16733
@var{font-max-char}
 
16734
@var{font-min-byte1}
 
16735
@var{font-max-byte1}
 
16736
@var{font-min-byte2}
 
16737
@var{font-max-byte2}
 
16738
@var{font-all-chars-exist-p}
 
16739
@var{font-default-char}
 
16740
@var{font-ascent}
 
16741
@var{font-descent}
 
16742
@var{font-properties}
 
16743
@var{font-property}
 
16744
@var{char-left-bearing}
 
16745
@var{char-right-bearing}
 
16746
@var{char-width}
 
16747
@var{char-ascent}
 
16748
@var{char-descent}
 
16749
@var{char-attributes}
 
16750
@var{min-char-left-bearing}
 
16751
@var{min-char-right-bearing}
 
16752
@var{min-char-width}
 
16753
@var{min-char-ascent}
 
16754
@var{min-char-descent}
 
16755
@var{min-char-attributes}
 
16756
 
 
16757
@var{X11 Request Name CLX Function Name}
 
16758
 
 
16759
@var{max-char-left-bearing}
 
16760
@var{max-char-right-bearing}
 
16761
@var{max-char-width}
 
16762
@var{max-char-ascent}
 
16763
@var{max-char-descent}
 
16764
@var{max-char-attributes}
 
16765
QueryKeymap     @var{query-keymap}
 
16766
QueryPointer    @var{global-pointer-position}
 
16767
QueryPointer    @var{pointer-position}
 
16768
QueryPointer    @var{query-pointer}
 
16769
QueryTextExtents@var{text-extents}
 
16770
QueryTextExtents@var{text-width}
 
16771
QueryTree       @var{query-tree}
 
16772
RecolorCursor   @var{recolor-cursor}
 
16773
ReparentWindow  @var{reparent-window}
 
16774
RotateProperties@var{rotate-properties}
 
16775
SendEvent       @var{send-event}
 
16776
SetClipRectangles         @var{force-gcontext-changes}
 
16777
(See @var{with-gcontext})
 
16778
(@code{setf} (@var{gcontext-clip-x} @emph{gc}))
 
16779
(@code{setf} (@var{gcontext-clip-y} @emph{gc}))
 
16780
(@code{setf} (@var{gcontext-clip-mask} @emph{gc} &optional
 
16781
@var{ordering}))
 
16782
(@code{setf} (@var{gcontext-clip-ordering} @emph{gc}))
 
16783
SetDashes       @var{force-gcontext-changes}
 
16784
(See @var{with-gcontext})
 
16785
(@code{setf} (@var{gcontext-dash-offset} @emph{gc}))
 
16786
(@code{setf} (@var{gcontext-dashes} @emph{gc}))
 
16787
SetFontPath     (@code{setf} (@var{font-path} @emph{font})
 
16788
SetInputFocus   @var{set-input-focus}
 
16789
SetKeyboardMapping        @var{change-keyboard-mapping}
 
16790
SetModifierMapping        @var{set-modifier-mapping}
 
16791
SetPointerMapping         @var{set-pointer-mapping}
 
16792
SetScreenSaver  @var{set-screen-saver}
 
16793
SetSelectionOwner         @var{set-selection-owner}
 
16794
StoreColors     @var{store-color}
 
16795
StoreColors     @var{store-colors}
 
16796
StoreNamedColor @var{store-color}
 
16797
StoreNamedColor @var{store-colors}
 
16798
TranslateCoords @var{translate-coordinates}
 
16799
UngrabButton    @var{ungrab-button}
 
16800
UngrabKey       @var{ungrab-key}
 
16801
UngrabKeyboard  @var{ungrab-keyboard}
 
16802
UngrabPointer   @var{ungrab-pointer}
 
16803
UngrabServer    @var{ungrab-server}
 
16804
UninstallColormap         @var{uninstall-colormap}
 
16805
UnmapSubwindows @var{unmap-subwindows}
 
16806
UnmapWindow     @var{unmap-window}
 
16807
WarpPointer     @var{warp-pointer}
 
16808
WarpPointer     @var{warp-pointer-if-inside}
 
16809
WarpPointer     @var{warp-pointer-relative}
 
16810
WarpPointer     @var{warp-pointer-relative-if-inside}
 
16811
ListHosts       @var{access-control}
 
16812
ListHosts       @var{access-hosts}
 
16813
ForceScreenSaver@var{activate-screen-saver}
 
16814
ChangeHosts     @var{add-access-host}
 
16815
 
 
16816
@var{X11 Request Name CLX Function Name}
 
16817
 
 
16818
ChangeSaveSet   @var{add-to-save-set}
 
16819
AllocColor      @var{alloc-color}
 
16820
AllocNamedColor @var{alloc-color}
 
16821
AllocColorCells @var{alloc-color-cells}
 
16822
AllocColorPlanes@var{alloc-color-planes}
 
16823
AllowEvents     @var{allow-events}
 
16824
GetAtomName     @var{atom-name}
 
16825
Bell  @var{bell}
 
16826
ChangeActivePointerGrab   @var{change-active-pointer-grab}
 
16827
ChangeKeyboardControl     @var{change-keyboard-control}
 
16828
SetKeyboardMapping        @var{change-keyboard-mapping}
 
16829
ChangePointerControl      @var{change-pointer-control}
 
16830
ChangeProperty  @var{change-property}
 
16831
QueryFont       @var{char-ascent}
 
16832
QueryFont       @var{char-attributes}
 
16833
QueryFont       @var{char-descent}
 
16834
QueryFont       @var{char-left-bearing}
 
16835
QueryFont       @var{char-right-bearing}
 
16836
QueryFont       @var{char-width}
 
16837
CirculateWindow @var{circulate-window-down}
 
16838
CirculateWindow @var{circulate-window-up}
 
16839
ClearToBackground         @var{clear-area}
 
16840
CloseFont       @var{close-font}
 
16841
ConvertSelection@var{convert-selection}
 
16842
CopyArea        @var{copy-area}
 
16843
CopyColormapAndFree       @var{copy-colormap-and-free}
 
16844
CopyGC@var{copy-gcontext}
 
16845
CopyGC@var{copy-gcontext-components}
 
16846
CopyPlane       @var{copy-plane}
 
16847
CreateColormap  @var{create-colormap}
 
16848
CreateCursor    @var{create-cursor}
 
16849
CreateGC        @var{create-gcontext}
 
16850
CreateGlyphCursor         @var{create-glyph-cursor}
 
16851
CreatePixmap    @var{create-pixmap}
 
16852
CreateWindow    @var{create-window}
 
16853
DeleteProperty  @var{delete-property}
 
16854
DestroySubwindows         @var{destroy-subwindows}
 
16855
DestroyWindow   @var{destroy-window}
 
16856
PolyArc         @var{draw-arc}
 
16857
PolyArc         @var{draw-arcs}
 
16858
PolyText16      @var{draw-glyph}
 
16859
PolyText16      @var{draw-glyphs}
 
16860
PolyText8       @var{draw-glyphs}
 
16861
ImageText16     @var{draw-image-glyph}
 
16862
ImageText16     @var{draw-image-glyphs}
 
16863
ImageText8      @var{draw-image-glyphs}
 
16864
PolyLine        @var{draw-line}
 
16865
PolyLine        @var{draw-lines}
 
16866
PolyPoint       @var{draw-point}
 
16867
PolyPoint       @var{draw-points}
 
16868
PolyFillRectangle         @var{draw-rectangle}
 
16869
PolyRectangle   @var{draw-rectangle}
 
16870
PolyFillRectangle         @var{draw-rectangles}
 
16871
PolyRectangle   @var{draw-rectangles}
 
16872
PolySegment     @var{draw-segments}
 
16873
GetGeometry     @var{drawable-border-width}
 
16874
 
 
16875
@var{X11 Request Name CLX Function Name}
 
16876
 
 
16877
GetGeometry     @var{drawable-depth}
 
16878
GetGeometry     @var{drawable-height}
 
16879
GetGeometry     @var{drawable-root}
 
16880
GetGeometry     @var{drawable-width}
 
16881
GetGeometry     @var{drawable-x}
 
16882
GetGeometry     @var{drawable-y}
 
16883
FillPoly        @var{fill-polygon}
 
16884
InternAtom      @var{find-atom}
 
16885
QueryFont       @var{font-all-chars-exist-p}
 
16886
QueryFont       @var{font-ascent}
 
16887
QueryFont       @var{font-default-char}
 
16888
QueryFont       @var{font-descent}
 
16889
QueryFont       @var{font-direction}
 
16890
QueryFont       @var{font-max-byte1}
 
16891
QueryFont       @var{font-max-byte2}
 
16892
QueryFont       @var{font-max-char}
 
16893
QueryFont       @var{font-min-byte1}
 
16894
QueryFont       @var{font-min-byte2}
 
16895
QueryFont       @var{font-min-char}
 
16896
QueryFont       @var{font-name}
 
16897
QueryFont       @var{font-name}
 
16898
GetFontPath     @var{font-path}
 
16899
QueryFont       @var{font-properties}
 
16900
QueryFont       @var{font-property}
 
16901
ChangeGC        @var{force-gcontext-changes}
 
16902
SetClipRectangles         @var{force-gcontext-changes}
 
16903
SetDashes       @var{force-gcontext-changes}
 
16904
FreeColormap    @var{free-colormap}
 
16905
FreeColors      @var{free-colors}
 
16906
FreeCursor      @var{free-cursor}
 
16907
FreeGC@var{free-gcontext}
 
16908
FreePixmap      @var{free-pixmap}
 
16909
GetProperty     @var{get-property}
 
16910
GetImage        @var{get-raw-image}
 
16911
QueryPointer    @var{global-pointer-position}
 
16912
GrabButton      @var{grab-button}
 
16913
GrabKey         @var{grab-key}
 
16914
GrabKeyboard    @var{grab-keyboard}
 
16915
GrabPointer     @var{grab-pointer}
 
16916
GrabServer      @var{grab-server}
 
16917
GrabServer      @var{with-server-grabbed}
 
16918
GetInputFocus   @var{input-focus}
 
16919
InstallColormap @var{install-colormap}
 
16920
ListInstalledColormaps    @var{installed-colormaps}
 
16921
InternAtom      @var{intern-atom}
 
16922
GetKeyboardControl        @var{keyboard-control}
 
16923
GetKeyboardMapping        @var{keyboard-mapping}
 
16924
KillClient      @var{kill-client}
 
16925
KillClient      @var{kill-temporary-clients}
 
16926
ListExtensions  @var{list-extensions}
 
16927
ListFonts       @var{list-font-names}
 
16928
ListFontsWithInfo         @var{list-fonts}
 
16929
ListProperties  @var{list-properties}
 
16930
LookupColor     @var{lookup-color}
 
16931
MapSubwindows   @var{map-subwindows}
 
16932
MapWindow       @var{map-window}
 
16933
 
 
16934
@var{X11 Request Name CLX Function Name}
 
16935
 
 
16936
QueryFont       @var{max-char-ascent}
 
16937
QueryFont       @var{max-char-attributes}
 
16938
QueryFont       @var{max-char-descent}
 
16939
QueryFont       @var{max-char-left-bearing}
 
16940
QueryFont       @var{max-char-right-bearing}
 
16941
QueryFont       @var{max-char-width}
 
16942
QueryFont       @var{min-char-ascent}
 
16943
QueryFont       @var{min-char-attributes}
 
16944
QueryFont       @var{min-char-descent}
 
16945
QueryFont       @var{min-char-left-bearing}
 
16946
QueryFont       @var{min-char-right-bearing}
 
16947
QueryFont       @var{min-char-width}
 
16948
GetModifierMapping        @var{modifier-mapping}
 
16949
GetMotionEvents @var{motion-events}
 
16950
OpenFont        @var{open-font}
 
16951
GetPointerControl         @var{pointer-control}
 
16952
GetPointerMapping         @var{pointer-mapping}
 
16953
QueryPointer    @var{pointer-position}
 
16954
PutImage        @var{put-raw-image}
 
16955
QueryBestSize   @var{query-best-cursor}
 
16956
QueryBestSize   @var{query-best-stipple}
 
16957
QueryBestSize   @var{query-best-tile}
 
16958
QueryColors     @var{query-colors}
 
16959
QueryExtension  @var{query-extension}
 
16960
QueryKeymap     @var{query-keymap}
 
16961
QueryPointer    @var{query-pointer}
 
16962
QueryTree       @var{query-tree}
 
16963
RecolorCursor   @var{recolor-cursor}
 
16964
ChangeHosts     @var{remove-access-host}
 
16965
ChangeSaveSet   @var{remove-from-save-set}
 
16966
ReparentWindow  @var{reparent-window}
 
16967
ForceScreenSaver@var{reset-screen-saver}
 
16968
RotateProperties@var{rotate-properties}
 
16969
GetScreenSaver  @var{screen-saver}
 
16970
GetSelectionOwner         @var{selection-owner}
 
16971
SendEvent       @var{send-event}
 
16972
ChangeAccessControl       @var{set-access-control}
 
16973
ChangeCloseDownMode       @var{set-close-down-mode}
 
16974
SetInputFocus   @var{set-input-focus}
 
16975
SetModifierMapping        @var{set-modifier-mapping}
 
16976
SetPointerMapping         @var{set-pointer-mapping}
 
16977
SetScreenSaver  @var{set-screen-saver}
 
16978
SetSelectionOwner         @var{set-selection-owner}
 
16979
StoreColors     @var{store-color}
 
16980
StoreColors     @var{store-colors}
 
16981
StoreNamedColor @var{store-color}
 
16982
StoreNamedColor @var{store-colors}
 
16983
QueryTextExtents@var{text-extents}
 
16984
QueryTextExtents@var{text-width}
 
16985
TranslateCoords @var{translate-coordinates}
 
16986
UngrabButton    @var{ungrab-button}
 
16987
UngrabKey       @var{ungrab-key}
 
16988
UngrabKeyboard  @var{ungrab-keyboard}
 
16989
UngrabPointer   @var{ungrab-pointer}
 
16990
UngrabServer    @var{ungrab-server}
 
16991
UngrabServer    @var{with-server-grabbed}
 
16992
 
 
16993
@var{X11 Request Name CLX Function Name}
 
16994
 
 
16995
UninstallColormap         @var{uninstall-colormap}
 
16996
UnmapSubwindows @var{unmap-subwindows}
 
16997
UnmapWindow     @var{unmap-window}
 
16998
WarpPointer     @var{warp-pointer}
 
16999
WarpPointer     @var{warp-pointer-if-inside}
 
17000
WarpPointer     @var{warp-pointer-relative}
 
17001
WarpPointer     @var{warp-pointer-relative-if-inside}
 
17002
GetWindowAttributes       @var{window-all-event-masks}
 
17003
GetWindowAttributes       @var{window-backing-pixel}
 
17004
GetWindowAttributes       @var{window-backing-planes}
 
17005
GetWindowAttributes       @var{window-backing-store}
 
17006
GetWindowAttributes       @var{window-bit-gravity}
 
17007
GetWindowAttributes       @var{window-class}
 
17008
GetWindowAttributes       @var{window-colormap}
 
17009
GetWindowAttributes       @var{window-colormap-installed-p}
 
17010
GetWindowAttributes       @var{window-do-not-propagate-mask}
 
17011
GetWindowAttributes       @var{window-event-mask}
 
17012
GetWindowAttributes       @var{window-gravity}
 
17013
GetWindowAttributes       @var{window-map-state}
 
17014
GetWindowAttributes       @var{window-override-redirect}
 
17015
GetWindowAttributes       @var{window-save-under}
 
17016
GetWindowAttributes       @var{window-visual}
 
17017
ConfigureWindow (@code{setf} (@var{drawable-border-width} @emph{drawable}))
 
17018
ConfigureWindow (@code{setf} (@var{drawable-depth} @emph{drawable}))
 
17019
ConfigureWindow (@code{setf} (@var{drawable-height} @emph{drawable}))
 
17020
ConfigureWindow (@code{setf} (@var{drawable-width} @emph{drawabl}e))
 
17021
ConfigureWindow (@code{setf} (@var{drawable-x} @emph{drawable}))
 
17022
ConfigureWindow (@code{setf} (@var{drawable-y} @emph{drawable}))
 
17023
SetFontPath     (@code{setf} (@var{font-path} @emph{font}) @var{paths})
 
17024
ChangeGC        (@code{setf} (@var{gcontext-arc-mode} @emph{gc}))
 
17025
ChangeGC        (@code{setf} (@var{gcontext-background} @emph{gc}))
 
17026
ChangeGC        (@code{setf} (@var{gcontext-cap-style} @emph{gc}))
 
17027
SetClipRectangles         (@code{setf} (@var{gcontext-clip-mask} @emph{gc} &optional
 
17028
@var{ordering}))
 
17029
SetClipRectangles         (@code{setf} (@var{gcontext-clip-ordering} @emph{gc}))
 
17030
SetClipRectangles         (@code{setf} (@var{gcontext-clip-x} @emph{gc}))
 
17031
SetClipRectangles         (@code{setf} (@var{gcontext-clip-y} @emph{gc}))
 
17032
SetDashes       (@code{setf} (@var{gcontext-dash-offset} @emph{gc}))
 
17033
SetDashes       (@code{setf} (@var{gcontext-dashes} @emph{gc}))
 
17034
ChangeGC        (@code{setf} (@var{gcontext-exposures} @emph{gc}))
 
17035
ChangeGC        (@code{setf} (@var{gcontext-fill-rule} @emph{gc}) @var{keyword})
 
17036
ChangeGC        (@code{setf} (@var{gcontext-fill-style} @emph{gc}) @var{keyword})
 
17037
ChangeGC        (@code{setf} (@var{gcontext-font} @emph{gc} &optional
 
17038
@var{metrics-p})
 
17039
ChangeGC        (@code{setf} (@var{gcontext-foreground} @emph{gc}) @var{card32})
 
17040
ChangeGC        (@code{setf} (@var{gcontext-function} @emph{gc}))
 
17041
ChangeGC        (@code{setf} (@var{gcontext-join-style} @emph{gc}) @var{keyword})
 
17042
ChangeGC        (@code{setf} (@var{gcontext-line-style} @emph{gc}) @var{keyword})
 
17043
ChangeGC        (@code{setf} (@var{gcontext-line-width} @emph{gc}) @var{card16})
 
17044
ChangeGC        (@code{setf} (@var{gcontext-plane-mask} @emph{gc}) @var{card32})
 
17045
ChangeGC        (@code{setf} (@var{gcontext-stipple} @emph{gc}) @var{pixmap})
 
17046
ChangeGC        (@code{setf} (@var{gcontext-subwindow-mode} @emph{gc}))
 
17047
ChangeGC        (@code{setf} (@var{gcontext-tile} @emph{gc}))
 
17048
ChangeGC        (@code{setf} (@var{gcontext-ts-x} @emph{gc}))
 
17049
ChangeGC        (@code{setf} (@var{gcontext-ts-y} @emph{gc}))
 
17050
ChangeWindowAttributes    (@code{setf} (@var{window-background} @emph{window}))
 
17051
 
 
17052
@var{X11 Request Name CLX Function Name}
 
17053
 
 
17054
ChangeWindowAttributes    (@code{setf} (@var{window-backing-pixel} @emph{window}))
 
17055
ChangeWindowAttributes    (@code{setf} (@var{window-backing-planes} @emph{window}))
 
17056
ChangeWindowAttributes    (@code{setf} (@var{window-backing-store} @emph{window}))
 
17057
ChangeWindowAttributes    (@code{setf} (@var{window-bit-gravity} @emph{window}))
 
17058
ChangeWindowAttributes    (@code{setf} (@var{window-border} @emph{window}))
 
17059
ChangeWindowAttributes    (@code{setf} (@var{window-colormap} @emph{window}))
 
17060
ChangeWindowAttributes    (@code{setf} (@var{window-cursor} @emph{window}))
 
17061
ChangeWindowAttributes    (@code{setf} (@var{window-do-not-propagate-mask}
 
17062
@emph{window}))
 
17063
ChangeWindowAttributes    (@code{setf} (@var{window-event-mask} @emph{window}))
 
17064
ChangeWindowAttributes    (@code{setf} (@var{window-gravity} @emph{window}))
 
17065
ChangeWindowAttributes    (@code{setf} (@var{window-override-redirect} @emph{window}))
 
17066
ConfigureWindow (@code{setf} (@var{window-priority} @emph{window} &optional
 
17067
@var{sibling}))
 
17068
ChangeWindowAttributes    (@code{setf} (@var{window-save-under} @emph{window}))
 
17069
@end ignore
 
17070
 
 
17071
@node Undocumented, Glossary, Errors, Top
 
17072
@chapter Undocumented
 
17073
 
 
17074
This section just lists all symbols exported from the
 
17075
@var{XLIB} package but not documented in this manual.
 
17076
 
 
17077
@defun bitmap-image &optional plist &rest patterns
 
17078
@end defun
 
17079
 
 
17080
 
 
17081
@defun character->keysyms character &optional display
 
17082
@end defun
 
17083
 
 
17084
 
 
17085
@defun character-in-map-p display character keymap
 
17086
 
 
17087
@table @var
 
17088
@item display
 
17089
A @var{display}.
 
17090
@end table
 
17091
 
 
17092
@end defun
 
17093
 
 
17094
@defun decode-core-error display event &optional arg
 
17095
@end defun
 
17096
 
 
17097
@defun default-error-handler display error-key &rest key-vals &key asynchronous &allow-other-keys
 
17098
@end defun
 
17099
 
 
17100
@defun default-keysym-index display keycode state
 
17101
@end defun
 
17102
 
 
17103
@defun default-keysym-translate display state object
 
17104
@end defun
 
17105
 
 
17106
@defun define-keysym object keysym &key lowercase translate modifiers mask display
 
17107
@end defun
 
17108
 
 
17109
@defun define-keysym-set set first-keysym last-keysym
 
17110
@end defun
 
17111
 
 
17112
@defun display-invoke-after-function display
 
17113
 
 
17114
 
 
17115
Explicitly invokes the @emph{after-function} of the display.
 
17116
(see @var{display-after-function}). This function is
 
17117
internally called after every request.
 
17118
@end defun
 
17119
 
 
17120
@defun display-nscreens display
 
17121
@end defun
 
17122
 
 
17123
@defun display-release-number object
 
17124
@end defun
 
17125
 
 
17126
@defun event-handler handlers event-key
 
17127
@end defun
 
17128
 
 
17129
@defun get-external-event-code display event
 
17130
@end defun
 
17131
 
 
17132
@defun get-standard-colormap window property
 
17133
@end defun
 
17134
 
 
17135
@defun get-wm-class window
 
17136
@end defun
 
17137
 
 
17138
@defun icon-sizes window
 
17139
@end defun
 
17140
 
 
17141
@defun iconify-window window screen
 
17142
@end defun
 
17143
 
 
17144
@defun keysym->keycodes display keysym
 
17145
@end defun
 
17146
 
 
17147
@defun keysym-in-map-p display keysym keymap
 
17148
@end defun
 
17149
 
 
17150
@defun keysym-set keysym
 
17151
@end defun
 
17152
 
 
17153
@defun mapping-notify display request start count
 
17154
 
 
17155
Called on a @var{:mapping-notify} event to update
 
17156
the keyboard-mapping cache in @emph{display}.
 
17157
@end defun
 
17158
 
 
17159
@defun no-operation display
 
17160
@end defun
 
17161
 
 
17162
@defun parse-color colormap spec
 
17163
@end defun
 
17164
 
 
17165
@defun resource-database-timestamp database
 
17166
@end defun
 
17167
 
 
17168
@defun resource-key stringable
 
17169
@end defun
 
17170
 
 
17171
@defun rgb-colormaps window property
 
17172
@end defun
 
17173
 
 
17174
@defun root-resources screen &key database key test test-not
 
17175
 
 
17176
Returns a resource database containing the contents of the
 
17177
root window @var{RESOURCE_MANAGER} property for the given
 
17178
@emph{screen}. If @emph{screen} is a display, then its
 
17179
default screen is used. If an existing @emph{database} is
 
17180
given, then resource values are merged with the
 
17181
@emph{database} and the modified @emph{database} is
 
17182
returned.
 
17183
 
 
17184
@emph{test} and @emph{test-not} are predicates for selecting
 
17185
which resources are read. Arguments are a resource name list
 
17186
and a resource value. The @emph{key} function, if given, is
 
17187
called to convert a resource value string to the value given
 
17188
to @emph{test} or @emph{test-not}.
 
17189
@end defun
 
17190
 
 
17191
@defun rotate-cut-buffers display &optional (delta 1) (careful-p t)
 
17192
@end defun
 
17193
 
 
17194
@defun set-access-control display enabled-p
 
17195
@end defun
 
17196
 
 
17197
@defun set-close-down-mode display mode
 
17198
@anchor{set-close-down-mode}
 
17199
@end defun
 
17200
 
 
17201
@defun set-pointer-mapping display map
 
17202
@end defun
 
17203
 
 
17204
@defun set-selection-owner display selection owner &optional time
 
17205
@end defun
 
17206
 
 
17207
@defun set-standard-colormap window property colormap base-pixel max-color mult-color
 
17208
@end defun
 
17209
 
 
17210
@defun set-standard-properties window &rest options
 
17211
@end defun
 
17212
 
 
17213
@defun set-wm-class window resource-name resource-class
 
17214
@end defun
 
17215
 
 
17216
@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
 
17217
@end defun
 
17218
 
 
17219
@defun set-wm-resources database window &key write test test-not
 
17220
@end defun
 
17221
 
 
17222
@defun transient-for window
 
17223
@end defun
 
17224
 
 
17225
@defun translate-default src src-start src-end font dst dst-start
 
17226
@end defun
 
17227
 
 
17228
@defun undefine-keysym object keysym &key display modifiers &allow-other-keys
 
17229
@end defun
 
17230
 
 
17231
@defun visual-info-blue-mask object
 
17232
@end defun
 
17233
 
 
17234
@defun visual-info-green-mask object
 
17235
@end defun
 
17236
 
 
17237
@defun visual-info-red-mask object
 
17238
@end defun
 
17239
 
 
17240
@defun window-cursor window
 
17241
@end defun
 
17242
 
 
17243
@defun window-visual-info window
 
17244
@end defun
 
17245
 
 
17246
@defun withdraw-window window screen
 
17247
@end defun
 
17248
 
 
17249
@defun wm-client-machine window
 
17250
@end defun
 
17251
 
 
17252
@defun wm-colormap-windows window
 
17253
@end defun
 
17254
 
 
17255
@defun wm-command window
 
17256
@end defun
 
17257
 
 
17258
@defun wm-hints window
 
17259
@end defun
 
17260
 
 
17261
@defun wm-hints-flags object
 
17262
@end defun
 
17263
 
 
17264
@defun wm-icon-name window
 
17265
@end defun
 
17266
 
 
17267
@defun wm-name window
 
17268
@end defun
 
17269
 
 
17270
@defun wm-normal-hints window
 
17271
@end defun
 
17272
 
 
17273
@defun wm-protocols window
 
17274
@end defun
 
17275
 
 
17276
@defun wm-resources database window &key key test test-not
 
17277
@end defun
 
17278
 
 
17279
@defun wm-zoom-hints window
 
17280
@end defun
 
17281
 
 
17282
@ignore
 
17283
XLIB:STATE-KEYSYM-P is undocumented.
 
17284
XLIB:*VERSION* is undocumented.
 
17285
XLIB:BITMAP-FORMAT-LSB-FIRST-P ???  [Function]
 
17286
XLIB:BITMAP-FORMAT-P ???  [Function]
 
17287
XLIB:BITMAP-FORMAT-PAD ???[Function]
 
17288
XLIB:BITMAP-FORMAT-UNIT ???         [Function]
 
17289
XLIB:CARD8->CHAR (card8)  [Function]
 
17290
XLIB:CHAR->CARD8 (char)   [Function]
 
17291
XLIB:COLORMAP-VISUAL-INFO ???       [Function]
 
17292
XLIB:CUT-BUFFER (display &key (buffer 0) (type :string) (result-type 'string)
 
17293
(transform #'card8->char) (start 0) end)     [Function]
 
17294
XLIB:DEFINE-ERROR ???     [Function]
 
17295
XLIB:DEFINE-EXTENSION ??? [Function]
 
17296
XLIB:DEFINE-GCONTEXT-ACCESSOR ???   [Function]
 
17297
XLIB:DISPLAY-DEFAULT-SCREEN ???     [Function]
 
17298
XLIB:DISPLAY-HOST ???     [Function]
 
17299
XLIB:DISPLAY-REPORT-ASYNCHRONOUS-ERRORS ???   [Function]
 
17300
XLIB:DISPLAY-XDEFAULTS ???[Function]
 
17301
XLIB:EXTENSION-OPCODE ??? [Function]
 
17302
XLIB:GCONTEXT-CLIP-ORDERING is undocumented.
 
17303
XLIB:GENERALIZED-BOOLEAN is undocumented.
 
17304
XLIB:ILLEGAL-REQUEST-ERROR is undocumented.
 
17305
XLIB:IMAGE is undocumented.
 
17306
XLIB:IMAGE-PIXMAP (drawable image &key gcontext width height depth)         [Function]
 
17307
XLIB:IMAGE-X is undocumented.
 
17308
XLIB:IMAGE-X-P ???        [Function]
 
17309
XLIB:IMAGE-XY is undocumented.
 
17310
XLIB:IMAGE-XY-P ???       [Function]
 
17311
XLIB:IMAGE-Z is undocumented.
 
17312
XLIB:IMAGE-Z-P ???        [Function]
 
17313
XLIB:INVALID-FONT is undocumented.
 
17314
XLIB:KEYCODE->CHARACTER (display keycode state &key keysym-index
 
17315
(keysym-index-function #'default-keysym-index))        [Function]
 
17316
XLIB:MAKE-EVENT-HANDLERS (&key (type 'array) default)   [Function]
 
17317
XLIB:MAKE-WM-HINTS (&key ((:input #:g0) nil) ((:initial-state #:g1) nil) ((:icon-pixmap #:g2) nil)
 
17318
((:icon-window #:g3) nil) ((:icon-x #:g4) nil) ((:icon-y #:g5) nil)
 
17319
((:icon-mask #:g6) nil) ((:window-group #:g7) nil) ((:flags #:g8) 0))      [Function]
 
17320
XLIB:MAKE-WM-SIZE-HINTS (&key ((:user-specified-position-p #:g0) nil)
 
17321
((:user-specified-size-p #:g1) nil) ((:x #:g2) nil) ((:y #:g3) nil)
 
17322
((:width #:g4) nil) ((:height #:g5) nil) ((:min-width #:g6) nil)
 
17323
((:min-height #:g7) nil) ((:max-width #:g8) nil) ((:max-height #:g9) nil)
 
17324
((:width-inc #:g10) nil) ((:height-inc #:g11) nil) ((:min-aspect #:g12) nil)
 
17325
((:max-aspect #:g13) nil) ((:base-width #:g14) nil) ((:base-height #:g15) nil)
 
17326
((:win-gravity #:g16) nil) ((:program-specified-position-p #:g17) nil)
 
17327
((:program-specified-size-p #:g18) nil))     [Function]
 
17328
XLIB:PIXMAP-FORMAT-BITS-PER-PIXEL ???         [Function]
 
17329
XLIB:PIXMAP-FORMAT-DEPTH ???        [Function]
 
17330
XLIB:PIXMAP-FORMAT-P ???  [Function]
 
17331
XLIB:PIXMAP-FORMAT-SCANLINE-PAD ??? [Function]
 
17332
XLIB:RESOURCE-DATABASE is undocumented.
 
17333
XLIB:SCREEN-ROOT-VISUAL-INFO ???    [Function]
 
17334
XLIB:TRANSLATION-FUNCTION is undocumented.
 
17335
XLIB:VISUAL-INFO-BITS-PER-RGB ???   [Function]
 
17336
XLIB:VISUAL-INFO-CLASS ???[Function]
 
17337
XLIB:VISUAL-INFO-COLORMAP-ENTRIES ???         [Function]
 
17338
XLIB:VISUAL-INFO-DISPLAY ???        [Function]
 
17339
XLIB:VISUAL-INFO-ID ???   [Function]
 
17340
XLIB:VISUAL-INFO-P ???    [Function]
 
17341
XLIB:VISUAL-INFO-PLIST ???[Function]
 
17342
XLIB:WINDOW-BACKGROUND is undocumented.
 
17343
XLIB:WINDOW-BORDER is undocumented.
 
17344
XLIB:WINDOW-PRIORITY is undocumented.
 
17345
XLIB:WM-HINTS-ICON-MASK ???         [Function]
 
17346
XLIB:WM-HINTS-ICON-PIXMAP ???       [Function]
 
17347
XLIB:WM-HINTS-ICON-WINDOW ???       [Function]
 
17348
XLIB:WM-HINTS-ICON-X ???  [Function]
 
17349
XLIB:WM-HINTS-ICON-Y ???  [Function]
 
17350
XLIB:WM-HINTS-INITIAL-STATE ???     [Function]
 
17351
XLIB:WM-HINTS-INPUT ???   [Function]
 
17352
XLIB:WM-HINTS-P ???       [Function]
 
17353
XLIB:WM-HINTS-WINDOW-GROUP ???      [Function]
 
17354
XLIB:WM-SIZE-HINTS is undocumented.
 
17355
XLIB:WM-SIZE-HINTS-BASE-HEIGHT ???  [Function]
 
17356
XLIB:WM-SIZE-HINTS-BASE-WIDTH ???   [Function]
 
17357
XLIB:WM-SIZE-HINTS-HEIGHT ???       [Function]
 
17358
XLIB:WM-SIZE-HINTS-HEIGHT-INC ???   [Function]
 
17359
XLIB:WM-SIZE-HINTS-MAX-ASPECT ???   [Function]
 
17360
XLIB:WM-SIZE-HINTS-MAX-HEIGHT ???   [Function]
 
17361
XLIB:WM-SIZE-HINTS-MAX-WIDTH ???    [Function]
 
17362
XLIB:WM-SIZE-HINTS-MIN-ASPECT ???   [Function]
 
17363
XLIB:WM-SIZE-HINTS-MIN-HEIGHT ???   [Function]
 
17364
XLIB:WM-SIZE-HINTS-MIN-WIDTH ???    [Function]
 
17365
XLIB:WM-SIZE-HINTS-P ???  [Function]
 
17366
XLIB:WM-SIZE-HINTS-USER-SPECIFIED-POSITION-P ???        [Function]
 
17367
XLIB:WM-SIZE-HINTS-USER-SPECIFIED-SIZE-P ???  [Function]
 
17368
XLIB:WM-SIZE-HINTS-WIDTH ???        [Function]
 
17369
XLIB:WM-SIZE-HINTS-WIDTH-INC ???    [Function]
 
17370
XLIB:WM-SIZE-HINTS-WIN-GRAVITY ???  [Function]
 
17371
XLIB:WM-SIZE-HINTS-X ???  [Function]
 
17372
XLIB:WM-SIZE-HINTS-Y ???  [Function]
 
17373
@end ignore
 
17374
 
 
17375
@node Glossary, Function Index, Undocumented, Top
 
17376
@appendix Glossary
 
17377
 
 
17378
@table @asis
 
17379
@item access control list
 
17380
X maintains a list of hosts from which client programs can be run. By
 
17381
default, only programs on the local host can use the display, plus any
 
17382
hosts specified in an initial list read by the server. This @emph{access
 
17383
control list} can be changed by clients on the local host. Some
 
17384
server implementations can also implement other authorization
 
17385
mechanisms in addition to or in place of this mechanism. The action of
 
17386
this mechanism can be conditional based on the authorization protocol
 
17387
name and data received by the server at connection setup.
 
17388
 
 
17389
@item action
 
17390
A function that is designed to handle an input event. CLUE input
 
17391
processing consists of matching an event with an event specification
 
17392
found in a contact's @var{event-translations} slot and then calling
 
17393
actions associated with the matching event specification.
 
17394
 
 
17395
@item active grab
 
17396
A grab is @emph{active} when the pointer or keyboard is actually owned
 
17397
by the single grabbing client.
 
17398
 
 
17399
@item ancestors
 
17400
If W is an inferior of A, then A is an @emph{ancestor} of W.
 
17401
 
 
17402
@item atom
 
17403
A unique ID corresponding to a string name. Atoms are used to identify
 
17404
properties, types, and selections.
 
17405
 
 
17406
@item backing store
 
17407
When a server maintains the contents of a window, the off-screen saved
 
17408
pixels are known as a @emph{backing store}.
 
17409
 
 
17410
@item before action
 
17411
An action of a @var{contact-display} that is called when an event is
 
17412
dispatched to a contact, but before any other contact input processing
 
17413
is performed.
 
17414
 
 
17415
@item bit gravity
 
17416
When a window is resized, the contents of the window are not
 
17417
necessarily discarded. It is possible to request the server to
 
17418
relocate the previous contents to some region of the window. This
 
17419
attraction of window contents for some location of a window is known
 
17420
as @emph{bit} @emph{gravity}.
 
17421
 
 
17422
@item bitmap
 
17423
A pixmap of depth one.
 
17424
 
 
17425
@item button grabbing
 
17426
Buttons on the pointer can be passively @emph{grabbed} by a
 
17427
client. When the button is pressed, the pointer is then actively
 
17428
grabbed by the client.
 
17429
 
 
17430
@item byte order
 
17431
For image (pixmap/bitmap) data, byte order is defined by the server,
 
17432
and clients with different native byte ordering must swap bytes as
 
17433
necessary. For all other parts of the protocol, the byte order is
 
17434
defined by the client, and the server swaps bytes as necessary.
 
17435
 
 
17436
@item callback
 
17437
A function that represents a connection between a contact and the rest
 
17438
of an application program. A contact calls a callback function in
 
17439
order to report the results of the user interface component that it
 
17440
represents.
 
17441
 
 
17442
@item children
 
17443
First-level subwindows of a window.
 
17444
 
 
17445
@item class event
 
17446
Event translations that belong to all instances of a contact class. A
 
17447
class event @var{translations} translation is created by the
 
17448
@var{defevent} macro.
 
17449
 
 
17450
@item class resources
 
17451
Resources defined for each instance of a contact class. Also see
 
17452
constraint resources.
 
17453
 
 
17454
@item click
 
17455
A @var{:button-press} event followed immediately by a
 
17456
@var{:button-release} event for the same button, with no intervening
 
17457
change in pointer position or modifier key state.
 
17458
 
 
17459
@item client
 
17460
An application program connects to the window system server by some
 
17461
interprocess communication (IPC) path, such as a TCP connection or a
 
17462
shared memory buffer. This program is referred to as a @emph{client}
 
17463
of the window system server. More precisely, the client is the IPC
 
17464
path itself. A program with multiple paths open to the server is
 
17465
viewed as multiple clients by the protocol. Resource lifetimes are
 
17466
controlled by connection lifetimes, not by program lifetimes.
 
17467
 
 
17468
@item clipping regions
 
17469
In a graphics context, a bitmap or list of rectangles can be specified
 
17470
to restrict output to a particular region of the window. The image
 
17471
defined by the bitmap or rectangles is called a @emph{clipping
 
17472
region}.
 
17473
 
 
17474
@item colormap
 
17475
A set of entries defining color values. The colormap associated with a
 
17476
window is used to display the contents of the window. Each pixel value
 
17477
indexes the colormap to produce RGB values that drive the guns of a
 
17478
monitor. Depending on hardware limitations, one or more colormaps can
 
17479
be installed at one time, such that windows associated with those maps
 
17480
display with correct colors.
 
17481
 
 
17482
@item composite
 
17483
A subclass of @var{contact} representing contacts that are the
 
17484
parents of other contacts. A composite provides geometry management
 
17485
and input focus management services for the contacts that are its
 
17486
children.
 
17487
 
 
17488
@item complete resource class
 
17489
A list of symbols containing the class of the contact, the class of
 
17490
the contact's @var{parent} (and so on), and the class of the
 
17491
@var{contact-display} to which the contact belongs.  The complete
 
17492
resource class is one of the two items used as a key by a CLUE
 
17493
application in order to access a contact resource value in a resource
 
17494
database.
 
17495
 
 
17496
@item complete resource name
 
17497
A list of symbols containing the @var{name} of the contact, the
 
17498
@var{name} of the contact's @var{parent} (and so on), and the name
 
17499
of the @var{contact-display} to which the contact belongs. The
 
17500
complete resource name is one of the two items used as a key by a CLUE
 
17501
application in order to access a contact resource value in a resource
 
17502
database.
 
17503
 
 
17504
@item connection
 
17505
The IPC path between the server and client program. A client program
 
17506
typically has one connection to the server over which requests and
 
17507
events are sent.
 
17508
 
 
17509
@item constraint resources
 
17510
Resources defined for each child belonging to a member of a composite
 
17511
class.  Constraint resources are typically used to control the
 
17512
parent's geometry management policy.  Also see class resources.
 
17513
 
 
17514
@item contact
 
17515
The basic CLUE object for programming a user interface.
 
17516
 
 
17517
@item contact-display
 
17518
The CLUE object type that represents a connection to an X server and
 
17519
that supports an event loop for application input.
 
17520
 
 
17521
@item contact initialization
 
17522
The process of collecting initial values for all contact
 
17523
attributes. No server resources (windows and so on) are actually
 
17524
allocated until contact realization.
 
17525
 
 
17526
@item contact realization
 
17527
The process of allocating contact resources. This process completes
 
17528
contact creation.
 
17529
 
 
17530
@item containment
 
17531
A window contains the pointer if the window is viewable and the hot
 
17532
spot of the cursor is within a visible region of the window or a
 
17533
visible region of one of its inferiors. The border of the window is
 
17534
included as part of the window for containment. The pointer is in a
 
17535
window if the window contains the pointer but no inferior contains the
 
17536
pointer.
 
17537
 
 
17538
@item content
 
17539
The single child of a shell. The basic geometry management policy
 
17540
implemented by the @var{shell} class constrains a shell and its
 
17541
content to have the same width and height; size changes to one are
 
17542
automatically applied to the other.
 
17543
 
 
17544
@item coordinate system
 
17545
The coordinate system has x horizontal and y vertical, with the origin
 
17546
[0, 0] at the upper left. Coordinates are discrete and are in terms of
 
17547
pixels. Each window and pixmap has its own coordinate system. For a
 
17548
window, the origin is at the inside upper left, inside the border.
 
17549
 
 
17550
@item cursor
 
17551
The visible shape of the pointer on a screen. It consists of a
 
17552
hot-spot, a source bitmap, a shape bitmap, and a pair of colors. The
 
17553
cursor defined for a window controls the visible appearance when the
 
17554
pointer is in that window.
 
17555
 
 
17556
@item depth
 
17557
The depth of a window or pixmap is number of bits per pixel it
 
17558
has. The depth of a graphics context is the depth of the drawables it
 
17559
can be used in conjunction with for graphics output.
 
17560
 
 
17561
@item descendant
 
17562
If W is an inferior of A, then W is a @emph{descendant} of A.
 
17563
 
 
17564
@item device
 
17565
Keyboards, mice, tablets, track-balls, button boxes, and so forth, are
 
17566
all collectively known as input @emph{devices}. The core protocol only
 
17567
deals with two devices: the keyboard and the pointer.
 
17568
 
 
17569
@item direct color
 
17570
A class of colormap in which a pixel value is decomposed into three
 
17571
separate subfields for indexing. One subfield indexes an array to
 
17572
produce red intensity values, the second subfield indexes a second
 
17573
array to produce blue intensity values, and the third subfield indexes
 
17574
a third array to produce green intensity values. The RGB values can be
 
17575
changed dynamically.
 
17576
 
 
17577
@item dispatching an event
 
17578
The process of finding the appropriate contact and its actions.
 
17579
 
 
17580
@item double-click
 
17581
A sequence of two clicks of the same button in rapid succession.
 
17582
 
 
17583
@item drawable
 
17584
Both windows and pixmaps can be used as sources and destinations in
 
17585
graphics operations. These are collectively known as
 
17586
@emph{drawables}. However, an @var{:input-only} window cannot be used
 
17587
as a source or destination in a graphics operation.
 
17588
 
 
17589
@item event
 
17590
Clients receive information asynchronously via @emph{events}. These
 
17591
events can be either asynchronously generated from devices, or
 
17592
generated as side effects of client requests.  Events are grouped into
 
17593
types; events are never sent to a client by the server unless the
 
17594
client has specifically asked to be informed of that type of event,
 
17595
but clients can force events to be sent to other clients. Events are
 
17596
typically reported relative to a window.
 
17597
 
 
17598
@item event compression
 
17599
Ignoring (or compressing) certain redundant input events. Compression
 
17600
of redundant events is controlled by the class slots
 
17601
@var{compress-exposures} and @var{compress-motion}, which are shared
 
17602
by all instances of a contact class.
 
17603
 
 
17604
@item event loop
 
17605
The fundamental application control structure: wait for an event,
 
17606
figure out how to handle it, process the event, then go back and wait
 
17607
for the next one. In CLUE, the event loop is implemented using the
 
17608
@var{process-next-event} function.
 
17609
 
 
17610
@item event mask
 
17611
Events are requested relative to a window. The set of event types a
 
17612
client requests relative to a window are described using an @emph{event
 
17613
mask}.
 
17614
 
 
17615
@item event propagation
 
17616
Device-related events @emph{propagate} from the source window to
 
17617
ancestor windows until some client has expressed interest in handling
 
17618
that type of event, or until the event is discarded explicitly.
 
17619
 
 
17620
@item event specification
 
17621
A notation for describing a certain sort of event. CLUE input
 
17622
processing consists of matching an event with an event specification
 
17623
found in a contact's @var{event-translations} slot and then calling
 
17624
actions associated with the matching event specification.
 
17625
 
 
17626
@item event synchronization
 
17627
Certain race conditions are possible when demultiplexing device events
 
17628
to clients (in particular deciding where pointer and keyboard events
 
17629
should be sent when in the middle of window management
 
17630
operations). The event synchronization mechanism allows synchronous
 
17631
processing of device events.
 
17632
 
 
17633
@item event source
 
17634
The smallest window containing the pointer is the @emph{source} of a
 
17635
device related event.
 
17636
 
 
17637
@item event translation
 
17638
The process of determining which contact action functions will be
 
17639
executed. An event translation is a list found in a contact's
 
17640
@var{event-translations} slot associating an event specification with
 
17641
one or more action names. Also see class event translations.
 
17642
 
 
17643
@item exposure event
 
17644
Servers do not guarantee to preserve the contents of windows when
 
17645
windows are obscured or reconfigured. @emph{Exposure} events are sent
 
17646
to clients to inform them when contents of regions of windows have
 
17647
been lost.
 
17648
 
 
17649
@item extension
 
17650
Named @emph{extensions} to the core protocol can be defined to extend
 
17651
the system. Extension to output requests, resources, and event types
 
17652
are all possible, and expected.
 
17653
 
 
17654
@item focus window
 
17655
Another term for the input focus.
 
17656
 
 
17657
@item font
 
17658
A matrix of glyphs (typically characters). The protocol does no
 
17659
translation or interpretation of character sets. The client simply
 
17660
indicates values used to index the glyph array. A font contains
 
17661
additional metric information to determine inter-glyph and inter-line
 
17662
spacing.
 
17663
 
 
17664
@item geometry management
 
17665
The process whereby a composite controls the geometrical properties of
 
17666
its child contacts; the composite is referred to as the geometry
 
17667
manager.
 
17668
 
 
17669
@item glyph
 
17670
An image, typically of a character, in a font.
 
17671
 
 
17672
@item grab
 
17673
Keyboard keys, the keyboard, pointer buttons, the pointer, and the
 
17674
server can be @emph{grabbed} for exclusive use by a client. In
 
17675
general, these facilities are not intended to be used by normal
 
17676
applications but are intended for various input and window managers to
 
17677
implement various styles of user interfaces.
 
17678
 
 
17679
@item gcontext
 
17680
Shorthand for graphics context.
 
17681
 
 
17682
@item graphics context
 
17683
Various information for graphics output is stored in a @emph{graphics
 
17684
context} (or gcontext), such as foreground pixel, background pixel,
 
17685
line width, clipping region, and so forth. A graphics context can only
 
17686
be used with drawables that have the same root and the same depth as
 
17687
the graphics context.
 
17688
 
 
17689
@item gray scale
 
17690
A degenerate case of pseudo color, in which the red, green, and blue
 
17691
values in any given colormap entry are equal, thus producing shades of
 
17692
gray. The gray values can be changed dynamically.
 
17693
 
 
17694
@item hot spot
 
17695
A cursor has an associated @emph{hot spot} that defines a point in the
 
17696
cursor that corresponds to the coordinates reported for the pointer.
 
17697
 
 
17698
@item identifier
 
17699
Each resource has an @emph{identifier}, a unique value associated with
 
17700
it that clients use to name the resource. An identifier can be used
 
17701
over any connection to name the resource.
 
17702
 
 
17703
@item inferiors
 
17704
All of the subwindows nested below a window: the children, the
 
17705
children's children, and so on.
 
17706
 
 
17707
@item initialization
 
17708
See contact initialization.
 
17709
 
 
17710
@item input event
 
17711
See event.
 
17712
 
 
17713
@item input focus
 
17714
Normally a window defining the scope for processing of keyboard
 
17715
input. If a generated keyboard event would normally be reported to
 
17716
this window or one of its inferiors, the event is reported normally;
 
17717
otherwise, the event is reported with respect to the focus window. The
 
17718
input focus also can be set such that all keyboard events are
 
17719
discarded and that the focus window is dynamically taken to be the
 
17720
root window of whatever screen the pointer is on at each keyboard
 
17721
event.
 
17722
 
 
17723
@item input-only window
 
17724
A window that cannot be used for graphics requests. @emph{input-only}
 
17725
windows are invisible, and can be used to control such things as
 
17726
cursors, input event generation, and grabbing.  @emph{input-only}
 
17727
windows cannot have @emph{input/output} windows as inferiors.
 
17728
 
 
17729
@item input/output window
 
17730
The normal kind of opaque window, used for both input and
 
17731
output. Input/output windows can have both @emph{input/output} and
 
17732
input-only windows as inferiors.
 
17733
 
 
17734
@item insensitivity
 
17735
See sensitivity.
 
17736
 
 
17737
@item interactive-stream
 
17738
A contact subclass designed to integrate CLUE with the conventional
 
17739
stream-based I/O of Common Lisp.
 
17740
 
 
17741
@item key grabbing
 
17742
Keys on the keyboard can be passively @emph{grabbed} by a client. When
 
17743
the key is pressed, the keyboard is then actively grabbed by the
 
17744
client.
 
17745
 
 
17746
@item keyboard grabbing
 
17747
A client can actively @emph{grab} control of the keyboard, and key
 
17748
events will be sent to that client rather than the client to which the
 
17749
events would normally have been sent.
 
17750
 
 
17751
@item keysym
 
17752
An encoding of a symbol on a keycap on a keyboard.
 
17753
 
 
17754
@item managed
 
17755
A contact under geometry management control.
 
17756
 
 
17757
@item mapped
 
17758
A window is said to be @emph{mapped} if a map call has been performed
 
17759
on it. Unmapped windows and their inferiors are never viewable or
 
17760
visible.
 
17761
 
 
17762
@item modifier keys
 
17763
SHIFT, CONTROL, META, SUPER, HYPER, ALT, Compose, Apple, CAPS LOCK,
 
17764
Shift Lock, and similar keys are called @emph{modifier keys}.
 
17765
 
 
17766
@item monochrome
 
17767
A special case of static gray, in which there are only two colormap
 
17768
entries.
 
17769
 
 
17770
@item obscure
 
17771
A window is @emph{obscured} if some other window obscures it. For
 
17772
example, window A obscures window B if:
 
17773
@itemize @bullet
 
17774
 
 
17775
@item  Both windows are viewable @var{:input-output} windows
 
17776
 
 
17777
@item  Window A is higher in the global stacking order than window B
 
17778
 
 
17779
@item  The rectangle defined by the outside edges of window A intersects the rectangle
 
17780
defined by the outside edges of window B
 
17781
@end itemize
 
17782
 
 
17783
Notice that window borders are included in the calculation, and that a window can be
 
17784
obscured and yet still have visible regions. See occlude (there is a fine distinction
 
17785
between obscure and occlude).
 
17786
 
 
17787
@item occlude
 
17788
A window is @emph{occluded} if some other window occludes it. For
 
17789
example, window A occludes window B if:
 
17790
@itemize @bullet
 
17791
 
 
17792
@item  Both windows are mapped
 
17793
 
 
17794
@item  Window A is higher in the global stacking order than window B
 
17795
 
 
17796
@item  The rectangle defined by the outside edges of window A intersects the rectangle
 
17797
defined by the outside edges of window B
 
17798
@end itemize
 
17799
 
 
17800
Notice that window borders are included in the calculation. See
 
17801
obscure (there is a fine distinction between occlude and obscure).
 
17802
 
 
17803
@item override-shell
 
17804
A subclass of @var{shell} used to override the window manager. This
 
17805
subclass contains pop-up menus and other temporary objects that the
 
17806
user can never resize and so on.
 
17807
 
 
17808
@item padding
 
17809
Some padding bytes are inserted in the data stream to maintain
 
17810
alignment of the protocol requests on natural boundaries. This
 
17811
increases ease of portability to some machine architectures.
 
17812
 
 
17813
@item parent window
 
17814
If C is a child of P, then P is the @emph{parent} of C.
 
17815
 
 
17816
@item passive grab
 
17817
Grabbing a key or button is a @emph{passive grab}. The grab activates
 
17818
when the key or button is actually pressed.
 
17819
 
 
17820
@item pixel value
 
17821
An @emph{n}-bit value, where @emph{n} is the number of bit planes used
 
17822
in (that is, the depth of) a particular window or pixmap. For a
 
17823
window, a pixel value indexes a colormap to derive an actual color to
 
17824
be displayed.
 
17825
 
 
17826
@item pixmap
 
17827
A three dimensional array of bits. A pixmap is normally thought of as
 
17828
a two dimensional array of pixels, where each pixel can be a value
 
17829
from 0 to (2@emph{n})-1, where @emph{n} is the depth (z axis) of
 
17830
the pixmap. A pixmap can also be thought of as a stack of @emph{n}
 
17831
bitmaps.
 
17832
 
 
17833
@item plane
 
17834
When a pixmap or window is thought of as a stack of bitmaps, each
 
17835
bitmap is called a @emph{plane} or @emph{bit plane}.
 
17836
 
 
17837
@item plane mask
 
17838
Graphics operations can be restricted to only affect a subset of bit
 
17839
planes of a destination.  A @emph{plane mask} is a bit mask describing
 
17840
which planes are to be modified, and it is stored in a graphics
 
17841
context.
 
17842
 
 
17843
@item pointer
 
17844
The pointing device attached to the cursor and tracked on the screens.
 
17845
 
 
17846
@item pointer grabbing
 
17847
A client can actively @emph{grab} control of the pointer, and button
 
17848
and motion events will be sent to that client rather than the client
 
17849
to which the events would normally have been sent.
 
17850
 
 
17851
@item pointing device
 
17852
Typically a mouse or tablet, or some other device with effective
 
17853
dimensional motion.  There is only one visible cursor defined by the
 
17854
core protocol, and it tracks whatever pointing device is attached as
 
17855
the pointer.
 
17856
 
 
17857
@item pop-up
 
17858
One of the uses of a top-level shell (for example, a menu that pops up
 
17859
when a command button contact is activated). Setting the @var{state}
 
17860
of a shell to @var{:mapped} is sometimes referred to as
 
17861
@emph{mapping} or @emph{popping up} the shell. Setting the
 
17862
@var{state} of a shell to @var{:withdrawn} or @var{:iconic} is
 
17863
sometimes referred to as @emph{unmapping} or @emph{popping down} the
 
17864
shell.
 
17865
 
 
17866
@item property
 
17867
Windows can have associated @emph{properties}, consisting of a name, a
 
17868
type, a data format, and some data. The protocol places no
 
17869
interpretation on properties; they are intended as a general-purpose
 
17870
naming mechanism for clients. For example, clients might share
 
17871
information such as resize hints, program names, and icon formats with
 
17872
a window manager via properties.
 
17873
 
 
17874
@item property list
 
17875
The list of properties that have been defined for a window.
 
17876
 
 
17877
@item pseudo color
 
17878
A class of colormap in which a pixel value indexes the colormap to
 
17879
produce independent red, green, and blue values. That is, the colormap
 
17880
is viewed as an array of triples (RGB values). The RGB values can be
 
17881
changed dynamically.
 
17882
 
 
17883
@item realization
 
17884
See contact realization.
 
17885
 
 
17886
@item redirecting control
 
17887
Window managers (or client programs) may choose to enforce window
 
17888
layout policy in various ways. When a client attempts to change the
 
17889
size or position of a window, the operation can be @emph{redirected}
 
17890
to a specified client, rather than the operation actually being
 
17891
performed.
 
17892
 
 
17893
@item reply
 
17894
Information requested by a client program is sent back to the client
 
17895
with a @emph{reply}. Both events and replies are multiplexed on the
 
17896
same connection. Most requests do not generate replies. However, some
 
17897
requests generate multiple replies.
 
17898
 
 
17899
@item representation type
 
17900
The type of representation of a resource value. For example, a color
 
17901
value might be represented either as a namestring ("red"), a pixel
 
17902
value, an RGB triplet, an HSV triplet, and so on.
 
17903
 
 
17904
@item request
 
17905
A command to the server is called a @emph{request}. It is a single
 
17906
block of data sent over a connection.
 
17907
 
 
17908
@item resource
 
17909
A value of the user interface that can be changed by the user in a
 
17910
resource database via CLX functions @var{add-resource},
 
17911
@var{get-resource}, and so forth. See server resource.
 
17912
 
 
17913
@item resource class, complete
 
17914
See complete resource class.
 
17915
 
 
17916
@item resource database
 
17917
Conceptually, a set of resource name/value pairs (or resource
 
17918
bindings). CLX defines functions for storing and retrieving interface
 
17919
resources from a resource database.
 
17920
 
 
17921
@item resource name, complete
 
17922
See complete resource name.
 
17923
 
 
17924
@item RGB values
 
17925
@emph{Red}, @emph{green}, and @emph{blue} intensity values used to
 
17926
define color. These values are always represented as 16-bit unsigned
 
17927
numbers, with zero being the minimum intensity and 65535 being the
 
17928
maximum intensity. The values are scaled by the server to match the
 
17929
display hardware.
 
17930
 
 
17931
@item root
 
17932
A special composite contact used to represent an entire display
 
17933
screen.
 
17934
 
 
17935
@item root window
 
17936
Each screen has a @emph{root window} covering it. It cannot be
 
17937
reconfigured or unmapped, but otherwise acts as a full-fledged
 
17938
window. A root window has no parent.
 
17939
 
 
17940
@item save set
 
17941
The @emph{save set} of a client is a list of other client's windows
 
17942
that, if they are inferiors of one of the client's windows at
 
17943
connection close, should not be destroyed and that should be remapped
 
17944
if it is unmapped. Save sets are typically used by window managers to
 
17945
avoid lost windows if the manager should terminate abnormally.
 
17946
 
 
17947
@item scanline
 
17948
A list of pixel or bit values viewed as a horizontal row (all values
 
17949
having the same y coordinate) of an image, with the values ordered by
 
17950
increasing x coordinate.
 
17951
 
 
17952
@item scanline order
 
17953
An image represented in @emph{scanline order} contains scanlines
 
17954
ordered by increasing y coordinate.
 
17955
 
 
17956
@item screen
 
17957
A server can provide several independent @emph{screens}, which
 
17958
typically have physically independent monitors. This would be the
 
17959
expected configuration when there is only a single keyboard and
 
17960
pointer shared among the screens.
 
17961
 
 
17962
@item selection
 
17963
 
 
17964
A @emph{selection} can be thought of as an indirect property with
 
17965
dynamic type. That is, rather than having the property stored in the
 
17966
server, it is maintained by some client (the @emph{owner}).  A
 
17967
selection is global in nature, being thought of as belonging to the
 
17968
user (but maintained by clients), rather than being private to a
 
17969
particular window subhierarchy or a particular set of clients. When
 
17970
a client asks for the contents of a selection, it specifies a
 
17971
selection @emph{target type}. This target type can be used to
 
17972
control the transmitted representation of the contents.
 
17973
 
 
17974
For example, if the selection is "the last thing the user clicked
 
17975
on" and that is currently an image, then the target type might
 
17976
specify whether the contents of the image should be sent in XY
 
17977
Format or Z Format. The target type can also be used to control the
 
17978
class of contents transmitted; that is, asking for the looks (fonts,
 
17979
line spacing, indentation, and so forth) of a paragraph selection,
 
17980
rather than the text of the paragraph. The target type can also be
 
17981
used for other purposes; the semantics is not constrained by the
 
17982
protocol.
 
17983
 
 
17984
@item sensitivity
 
17985
A condition in which a user interface component of an application will
 
17986
accept input.  Conversely, when a contact is insensitive, events of
 
17987
particular types are not dispatched to the contact and are ignored.
 
17988
 
 
17989
@item server
 
17990
The @emph{server} provides the basic windowing mechanism. It handles
 
17991
IPC connections from clients, demultiplexes graphics requests onto the
 
17992
screens, and multiplexes input back to the appropriate clients.
 
17993
 
 
17994
@item server grabbing
 
17995
The server can be @emph{grabbed} by a single client for exclusive
 
17996
use. This prevents processing of any requests from other client
 
17997
connections until the grab is complete. This is typically only a
 
17998
transient state for such things as rubber-banding and pop-up menus, or
 
17999
to execute requests indivisibly.
 
18000
 
 
18001
@item server resource
 
18002
Windows, pixmaps, cursors, fonts, gcontexts, and colormaps are known
 
18003
as resources.  They all have unique identifiers associated with them
 
18004
for naming purposes. The lifetime of a resource is bounded by the
 
18005
lifetime of the connection over which the resource was created. See
 
18006
resource.
 
18007
 
 
18008
@item shell
 
18009
A composite that handles the duties required by standard conventions
 
18010
for top-level X windows.
 
18011
 
 
18012
@item sibling
 
18013
Children of the same parent window are known as @emph{sibling}
 
18014
windows.
 
18015
 
 
18016
@item static color
 
18017
A degenerate case of pseudo color in which the RGB values are
 
18018
predefined and read-only.
 
18019
 
 
18020
@item static gray
 
18021
A degenerate case of gray scale in which the gray values are
 
18022
predefined and read-only.  The values are typically (near-)linear
 
18023
increasing ramps.
 
18024
 
 
18025
@item stacking order
 
18026
Sibling windows can @emph{stack} on top of each other. Windows above
 
18027
both obscure and occlude lower windows. This is similar to paper on a
 
18028
desk. The relationship between sibling windows is known as the
 
18029
@emph{stacking order}.
 
18030
 
 
18031
@item state
 
18032
A slot of @var{contact} that controls the visual effect of the
 
18033
contact.
 
18034
 
 
18035
@item stipple
 
18036
A bitmap that is used to tile a region to serve as an additional clip
 
18037
mask for a fill operation with the foreground color.
 
18038
 
 
18039
@item tile
 
18040
A pixmap can be replicated in two dimensions to @emph{tile} a
 
18041
region. The pixmap itself is also known as a tile.
 
18042
 
 
18043
@item timer
 
18044
A CLUE object that provides support for animation and other types of
 
18045
time-sensitive user interfaces. A timer causes @var{:timer} events to
 
18046
be dispatched to a specific contact for processing.
 
18047
 
 
18048
@item timestamp
 
18049
A time value, expressed in milliseconds, typically since the last
 
18050
server reset. Timestamp values wrap around (after about 49.7
 
18051
days). The server, given its current time is represented by timestamp
 
18052
T, always interprets timestamps from clients by treating half of the
 
18053
timestamp space as being earlier in time than T and half of the
 
18054
timestamp space as being later in time than T. One timestamp value
 
18055
(named CurrentTime) is never generated by the server; this value is
 
18056
reserved for use in requests to represent the current server time.
 
18057
 
 
18058
@item top-level contact
 
18059
A contact whose parent is a root. A top-level contact is usually a
 
18060
composite at the top of a hierarchy of other contacts created by an
 
18061
application program.
 
18062
 
 
18063
@item top-level-session
 
18064
A subclass of @var{shell} that is used to communicate with a session
 
18065
manager.
 
18066
 
 
18067
@item top-level-shell
 
18068
A subclass of @var{shell} that provides full window manager
 
18069
interaction.
 
18070
 
 
18071
@item transient-shell
 
18072
A subclass of @var{shell} that a window manager typically will unmap
 
18073
when its owner becomes unmapped or iconified and will not allow to be
 
18074
individually iconified.
 
18075
 
 
18076
@item true color
 
18077
A degenerate case of direct color in which the subfields in the pixel
 
18078
value directly encode the corresponding RGB values. That is, the
 
18079
colormap has predefined read-only RGB values. The values are typically
 
18080
(near-)linear increasing ramps.
 
18081
 
 
18082
@item type
 
18083
An arbitrary atom used to identify the interpretation of property
 
18084
data. Types are completely uninterpreted by the server; they are
 
18085
solely for the benefit of clients.
 
18086
 
 
18087
@item unmanaged
 
18088
A contact that is not under geometry management control.
 
18089
 
 
18090
@item user interface
 
18091
A set of abstract interface objects used to control the dialog between
 
18092
an application and its human user.
 
18093
 
 
18094
@item viewable
 
18095
A window is @emph{viewable} if it and all of its ancestors are
 
18096
mapped. This does not imply that any portion of the window is actually
 
18097
visible. Graphics requests can be performed on a window when it is not
 
18098
viewable, but output will not be retained unless the server is
 
18099
maintaining backing store.
 
18100
 
 
18101
@item visible
 
18102
A region of a window is @emph{visible} if someone looking at the screen
 
18103
can actually see it; that is, the window is viewable and the region is
 
18104
not occluded by any other window.
 
18105
 
 
18106
@item window gravity
 
18107
When windows are resized, subwindows can be repositioned automatically
 
18108
relative to some position in the window. This attraction of a subwindow
 
18109
to some part of its parent is known as @emph{window gravity}.
 
18110
 
 
18111
@item window manager
 
18112
Manipulation of windows on the screen, and much of the user interface
 
18113
(policy) is typically provided by a @emph{window manager} client.
 
18114
 
 
18115
@item window manager shell
 
18116
A subclass of @var{shell} called @var{wm-shell} that interacts with
 
18117
the window manager.
 
18118
 
 
18119
@item XY Format
 
18120
The data for a pixmap is said to be in @emph{XY Format} if it is
 
18121
organized as a set of bitmaps representing individual bit planes, with
 
18122
the planes appearing from most to least significant in bit order.
 
18123
 
 
18124
@item Z Format
 
18125
The data for a pixmap is said to be in @emph{Z Format} if it is
 
18126
organized as a set of pixel values in scanline order.
 
18127
@end table
 
18128
 
 
18129
@node Function Index, Type Index, Glossary, Top
 
18130
@appendix Function Index
 
18131
 
 
18132
@printindex fn
 
18133
 
 
18134
@node Type Index,  , Function Index, Top
 
18135
@appendix Type Index
 
18136
 
 
18137
@printindex tp
 
18138
 
 
18139
@bye