summary refs log tree commit diff stats
diff options
context:
space:
mode:
authorCase Duckworth2024-01-17 22:50:58 -0600
committerCase Duckworth2024-01-17 22:50:58 -0600
commit95ddeb52fce369af6ad910bd7593681dcc83c4d9 (patch)
tree48b097e0c5ddcd7b15a244a740afd67a3c4a1a69
parentChange organization and massively refactor (diff)
downloadacdwm-95ddeb52fce369af6ad910bd7593681dcc83c4d9.tar.gz
acdwm-95ddeb52fce369af6ad910bd7593681dcc83c4d9.zip
ignore binary and reference
-rw-r--r--.gitignore1
-rwxr-xr-xacdwmbin42792 -> 0 bytes
-rw-r--r--ref/libX11.txt33445
3 files changed, 1 insertions, 33445 deletions
diff --git a/.gitignore b/.gitignore index 89f1a5e..00b512f 100644 --- a/.gitignore +++ b/.gitignore
@@ -6,3 +6,4 @@ acdwm
6*.link 6*.link
7*.o 7*.o
8*.import.scm 8*.import.scm
9ref/ \ No newline at end of file
diff --git a/acdwm b/acdwm deleted file mode 100755 index 0471d86..0000000 --- a/acdwm +++ /dev/null
Binary files differ
diff --git a/ref/libX11.txt b/ref/libX11.txt deleted file mode 100644 index 5540d62..0000000 --- a/ref/libX11.txt +++ /dev/null
@@ -1,33445 +0,0 @@
1Xlib - C Language X Interface
2
3X Consortium Standard
4
5James Gettys
6
7 Digital Equipment Corporation
8 Cambridge Research Laboratory
9
10Robert W. Scheifler
11
12 Massachusetts Institute of Technology
13 Laboratory for Computer Science
14
15Chuck Adams
16
17 Tektronix, Inc.
18
19Vania Joloboff
20
21 Open Software Foundation
22
23Hideki Hiura
24
25 Sun Microsystems, Inc.
26
27Bill McMahon
28
29 Hewlett-Packard Company
30
31Ron Newman
32
33 Massachusetts Institute of Technology
34
35Al Tabayoyon
36
37 Tektronix, Inc.
38
39Glenn Widener
40
41 Tektronix, Inc.
42
43Shigeru Yamada
44
45 Fujitsu OSSI
46
47 X Version 11, Release 7.7
48
49 Copyright © 1985, 1986, 1987, 1988, 1989, 1991, 1994, 1996,
50 2002 The Open Group
51
52 Permission is hereby granted, free of charge, to any person
53 obtaining a copy of this software and associated documentation
54 files (the "Software"), to deal in the Software without
55 restriction, including without limitation the rights to use,
56 copy, modify, merge, publish, distribute, sublicense, and/or
57 sell copies of the Software, and to permit persons to whom the
58 Software is furnished to do so, subject to the following
59 conditions:
60
61 The above copyright notice and this permission notice shall be
62 included in all copies or substantial portions of the Software.
63
64 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
65 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
66 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
67 NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR
68 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
69 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
70 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
71 THE SOFTWARE.
72
73 Except as contained in this notice, the name of The Open Group
74 shall not be used in advertising or otherwise to promote the
75 sale, use or other dealings in this Software without prior
76 written authorization from The Open Group.
77
78 Copyright © 1985, 1986, 1987, 1988, 1989, 1991 Digital
79 Equipment Corporation
80
81 Permission to use, copy, modify and distribute this
82 documentation for any purpose and without fee is hereby
83 granted, provided that the above copyright notice appears in
84 all copies and that both that copyright notice and this
85 permission notice appear in supporting documentation, and that
86 the names of Digital and Tetronix not be used in in advertising
87 or publicity pertaining to distribution of the software without
88 specific, written prior permission. Digital and Tetronix make
89 no representations about the suitability of the software
90 described herein for any purpose. It is provided "as is"
91 without express or implied warranty.
92
93 TekHVC is a trademark of Tektronix, Inc.
94 __________________________________________________________
95
96 Table of Contents
97
98 Acknowledgments
99 1. Introduction to Xlib
100
101 Overview of the X Window System
102 Errors
103 Standard Header Files
104 Generic Values and Types
105 Naming and Argument Conventions within Xlib
106 Programming Considerations
107 Character Sets and Encodings
108 Formatting Conventions
109
110 2. Display Functions
111
112 Opening the Display
113 Obtaining Information about the Display, Image Formats, or
114 Screens
115
116 Display Macros
117 Image Format Functions and Macros
118 Screen Information Macros
119
120 Generating a NoOperation Protocol Request
121 Freeing Client-Created Data
122 Closing the Display
123 Using X Server Connection Close Operations
124 Using Xlib with Threads
125 Using Internal Connections
126
127 3. Window Functions
128
129 Visual Types
130 Window Attributes
131
132 Background Attribute
133 Border Attribute
134 Gravity Attributes
135 Backing Store Attribute
136 Save Under Flag
137 Backing Planes and Backing Pixel Attributes
138 Event Mask and Do Not Propagate Mask Attributes
139 Override Redirect Flag
140 Colormap Attribute
141 Cursor Attribute
142
143 Creating Windows
144 Destroying Windows
145 Mapping Windows
146 Unmapping Windows
147 Configuring Windows
148 Changing Window Stacking Order
149 Changing Window Attributes
150
151 4. Window Information Functions
152
153 Obtaining Window Information
154 Translating Screen Coordinates
155 Properties and Atoms
156 Obtaining and Changing Window Properties
157 Selections
158
159 5. Pixmap and Cursor Functions
160
161 Creating and Freeing Pixmaps
162 Creating, Recoloring, and Freeing Cursors
163
164 6. Color Management Functions
165
166 Color Structures
167 Color Strings
168
169 RGB Device String Specification
170 RGB Intensity String Specification
171 Device-Independent String Specifications
172
173 Color Conversion Contexts and Gamut Mapping
174 Creating, Copying, and Destroying Colormaps
175 Mapping Color Names to Values
176 Allocating and Freeing Color Cells
177 Modifying and Querying Colormap Cells
178 Color Conversion Context Functions
179
180 Getting and Setting the Color Conversion Context of
181 a Colormap
182
183 Obtaining the Default Color Conversion Context
184 Color Conversion Context Macros
185 Modifying Attributes of a Color Conversion Context
186 Creating and Freeing a Color Conversion Context
187
188 Converting between Color Spaces
189 Callback Functions
190
191 Prototype Gamut Compression Procedure
192 Supplied Gamut Compression Procedures
193 Prototype White Point Adjustment Procedure
194 Supplied White Point Adjustment Procedures
195
196 Gamut Querying Functions
197
198 Red, Green, and Blue Queries
199 CIELab Queries
200 CIELuv Queries
201 TekHVC Queries
202
203 Color Management Extensions
204
205 Color Spaces
206 Adding Device-Independent Color Spaces
207 Querying Color Space Format and Prefix
208 Creating Additional Color Spaces
209 Parse String Callback
210 Color Specification Conversion Callback
211 Function Sets
212 Adding Function Sets
213 Creating Additional Function Sets
214
215 7. Graphics Context Functions
216
217 Manipulating Graphics Context/State
218 Using Graphics Context Convenience Routines
219
220 Setting the Foreground, Background, Function, or
221 Plane Mask
222
223 Setting the Line Attributes and Dashes
224 Setting the Fill Style and Fill Rule
225 Setting the Fill Tile and Stipple
226 Setting the Current Font
227 Setting the Clip Region
228 Setting the Arc Mode, Subwindow Mode, and Graphics
229 Exposure
230
231 8. Graphics Functions
232
233 Clearing Areas
234 Copying Areas
235 Drawing Points, Lines, Rectangles, and Arcs
236
237 Drawing Single and Multiple Points
238 Drawing Single and Multiple Lines
239 Drawing Single and Multiple Rectangles
240 Drawing Single and Multiple Arcs
241
242 Filling Areas
243
244 Filling Single and Multiple Rectangles
245 Filling a Single Polygon
246 Filling Single and Multiple Arcs
247
248 Font Metrics
249
250 Loading and Freeing Fonts
251 Obtaining and Freeing Font Names and Information
252 Computing Character String Sizes
253 Computing Logical Extents
254 Querying Character String Sizes
255
256 Drawing Text
257
258 Drawing Complex Text
259 Drawing Text Characters
260 Drawing Image Text Characters
261
262 Transferring Images between Client and Server
263
264 9. Window and Session Manager Functions
265
266 Changing the Parent of a Window
267 Controlling the Lifetime of a Window
268 Managing Installed Colormaps
269 Setting and Retrieving the Font Search Path
270 Grabbing the Server
271 Killing Clients
272 Controlling the Screen Saver
273 Controlling Host Access
274
275 Adding, Getting, or Removing Hosts
276 Changing, Enabling, or Disabling Access Control
277
278 10. Events
279
280 Event Types
281 Event Structures
282 Event Masks
283 Event Processing Overview
284 Keyboard and Pointer Events
285
286 Pointer Button Events
287 Keyboard and Pointer Events
288
289 Window Entry/Exit Events
290
291 Normal Entry/Exit Events
292 Grab and Ungrab Entry/Exit Events
293
294 Input Focus Events
295
296 Normal Focus Events and Focus Events While Grabbed
297 Focus Events Generated by Grabs
298
299 Key Map State Notification Events
300 Exposure Events
301
302 Expose Events
303 GraphicsExpose and NoExpose Events
304
305 Window State Change Events
306
307 CirculateNotify Events
308 ConfigureNotify Events
309 CreateNotify Events
310 DestroyNotify Events
311 GravityNotify Events
312 MapNotify Events
313 MappingNotify Events
314 ReparentNotify Events
315 UnmapNotify Events
316 VisibilityNotify Events
317
318 Structure Control Events
319
320 CirculateRequest Events
321 ConfigureRequest Events
322 MapRequest Events
323 ResizeRequest Events
324
325 Colormap State Change Events
326 Client Communication Events
327
328 ClientMessage Events
329 PropertyNotify Events
330 SelectionClear Events
331 SelectionRequest Events
332 SelectionNotify Events
333
334 11. Event Handling Functions
335
336 Selecting Events
337 Handling the Output Buffer
338 Event Queue Management
339 Manipulating the Event Queue
340
341 Returning the Next Event
342 Selecting Events Using a Predicate Procedure
343 Selecting Events Using a Window or Event Mask
344
345 Putting an Event Back into the Queue
346 Sending Events to Other Applications
347 Getting Pointer Motion History
348 Handling Protocol Errors
349
350 Enabling or Disabling Synchronization
351 Using the Default Error Handlers
352
353 12. Input Device Functions
354
355 Pointer Grabbing
356 Keyboard Grabbing
357 Resuming Event Processing
358 Moving the Pointer
359 Controlling Input Focus
360 Manipulating the Keyboard and Pointer Settings
361 Manipulating the Keyboard Encoding
362
363 13. Locales and Internationalized Text Functions
364
365 X Locale Management
366 Locale and Modifier Dependencies
367 Variable Argument Lists
368 Output Methods
369
370 Output Method Overview
371 Output Method Functions
372 X Output Method Values
373 Output Context Functions
374 Output Context Values
375 Creating and Freeing a Font Set
376 Obtaining Font Set Metrics
377 Drawing Text Using Font Sets
378
379 Input Methods
380
381 Input Method Overview
382 Input Method Management
383 Input Method Functions
384 Input Method Values
385 Input Context Functions
386 Input Context Values
387 Input Method Callback Semantics
388 Event Filtering
389 Getting Keyboard Input
390 Input Method Conventions
391
392 String Constants
393
394 14. Inter-Client Communication Functions
395
396 Client to Window Manager Communication
397
398 Manipulating Top-Level Windows
399 Converting String Lists
400 Setting and Reading Text Properties
401 Setting and Reading the WM_NAME Property
402 Setting and Reading the WM_ICON_NAME Property
403 Setting and Reading the WM_HINTS Property
404 Setting and Reading the WM_NORMAL_HINTS Property
405 Setting and Reading the WM_CLASS Property
406 Setting and Reading the WM_TRANSIENT_FOR Property
407 Setting and Reading the WM_PROTOCOLS Property
408 Setting and Reading the WM_COLORMAP_WINDOWS Property
409 Setting and Reading the WM_ICON_SIZE Property
410 Using Window Manager Convenience Functions
411
412 Client to Session Manager Communication
413
414 Setting and Reading the WM_COMMAND Property
415 Setting and Reading the WM_CLIENT_MACHINE Property
416
417 Standard Colormaps
418
419 Standard Colormap Properties and Atoms
420 Setting and Obtaining Standard Colormaps
421
422 15. Resource Manager Functions
423
424 Resource File Syntax
425 Resource Manager Matching Rules
426 Quarks
427 Creating and Storing Databases
428 Merging Resource Databases
429 Looking Up Resources
430 Storing into a Resource Database
431 Enumerating Database Entries
432 Parsing Command Line Options
433
434 16. Application Utility Functions
435
436 Using Keyboard Utility Functions
437
438 KeySym Classification Macros
439
440 Using Latin-1 Keyboard Event Functions
441 Allocating Permanent Storage
442 Parsing the Window Geometry
443 Manipulating Regions
444
445 Creating, Copying, or Destroying Regions
446 Moving or Shrinking Regions
447 Computing with Regions
448 Determining if Regions Are Empty or Equal
449 Locating a Point or a Rectangle in a Region
450
451 Using Cut Buffers
452 Determining the Appropriate Visual Type
453 Manipulating Images
454 Manipulating Bitmaps
455 Using the Context Manager
456
457 A. Xlib Functions and Protocol Requests
458 B. X Font Cursors
459 C. Extensions
460
461 Basic Protocol Support Routines
462 Hooking into Xlib
463
464 Hooks into the Library
465 Hooks onto Xlib Data Structures
466
467 GC Caching
468 Graphics Batching
469 Writing Extension Stubs
470
471 Requests, Replies, and Xproto.h
472 Request Format
473 Starting to Write a Stub Procedure
474 Locking Data Structures
475 Sending the Protocol Request and Arguments
476 Variable Length Arguments
477 Replies
478 Synchronous Calling
479 Allocating and Deallocating Memory
480 Portability Considerations
481 Deriving the Correct Extension Opcode
482
483 D. Compatibility Functions
484
485 X Version 11 Compatibility Functions
486
487 Setting Standard Properties
488 Setting and Getting Window Sizing Hints
489 Getting and Setting an XStandardColormap Structure
490 Parsing Window Geometry
491 Getting the X Environment Defaults
492
493 X Version 10 Compatibility Functions
494
495 Drawing and Filling Polygons and Curves
496 Associating User Data with a Value
497
498 Glossary
499 Index
500
501 List of Tables
502
503 A.1. Protocol requests made by each Xlib function
504 A.2. Xlib functions which use each Protocol Request
505
506Acknowledgments
507
508 The design and implementation of the first 10 versions of X
509 were primarily the work of three individuals: Robert Scheifler
510 of the MIT Laboratory for Computer Science and Jim Gettys of
511 Digital Equipment Corporation and Ron Newman of MIT, both at
512 MIT Project Athena. X version 11, however, is the result of the
513 efforts of dozens of individuals at almost as many locations
514 and organizations. At the risk of offending some of the players
515 by exclusion, we would like to acknowledge some of the people
516 who deserve special credit and recognition for their work on
517 Xlib. Our apologies to anyone inadvertently overlooked.
518
519Release 1
520
521 Our thanks does to Ron Newman (MIT Project Athena), who
522 contributed substantially to the design and implementation of
523 the Version 11 Xlib interface.
524
525 Our thanks also goes to Ralph Swick (Project Athena and
526 Digital) who kept it all together for us during the early
527 releases. He handled literally thousands of requests from
528 people everywhere and saved the sanity of at least one of us.
529 His calm good cheer was a foundation on which we could build.
530
531 Our thanks also goes to Todd Brunhoff (Tektronix) who was
532 ``loaned'' to Project Athena at exactly the right moment to
533 provide very capable and much-needed assistance during the
534 alpha and beta releases. He was responsible for the successful
535 integration of sources from multiple sites; we would not have
536 had a release without him.
537
538 Our thanks also goes to Al Mento and Al Wojtas of Digital's
539 ULTRIX Documentation Group. With good humor and cheer, they
540 took a rough draft and made it an infinitely better and more
541 useful document. The work they have done will help many
542 everywhere. We also would like to thank Hal Murray (Digital
543 SRC) and Peter George (Digital VMS) who contributed much by
544 proofreading the early drafts of this document.
545
546 Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson,
547 Jackie Granfield, and Vince Orgovan (Digital VMS) who helped
548 with the library utilities implementation; to Hania Gajewska
549 (Digital UEG-WSL) who, along with Ellis Cohen (CMU and
550 Siemens), was instrumental in the semantic design of the window
551 manager properties; and to Dave Rosenthal (Sun Microsystems)
552 who also contributed to the protocol and provided the sample
553 generic color frame buffer device-dependent code.
554
555 The alpha and beta test participants deserve special
556 recognition and thanks as well. It is significant that the bug
557 reports (and many fixes) during alpha and beta test came almost
558 exclusively from just a few of the alpha testers, mostly
559 hardware vendors working on product implementations of X. The
560 continued public contribution of vendors and universities is
561 certainly to the benefit of the entire X community.
562
563 Our special thanks must go to Sam Fuller, Vice-President of
564 Corporate Research at Digital, who has remained committed to
565 the widest public availability of X and who made it possible to
566 greatly supplement MIT's resources with the Digital staff in
567 order to make version 11 a reality. Many of the people
568 mentioned here are part of the Western Software Laboratory
569 (Digital UEG-WSL) of the ULTRIX Engineering group and work for
570 Smokey Wallace, who has been vital to the project's success.
571 Others not mentioned here worked on the toolkit and are
572 acknowledged in the X Toolkit documentation.
573
574 Of course, we must particularly thank Paul Asente, formerly of
575 Stanford University and now of Digital UEG-WSL, who wrote W,
576 the predecessor to X, and Brian Reid, formerly of Stanford
577 University and now of Digital WRL, who had much to do with W's
578 design.
579
580 Finally, our thanks goes to MIT, Digital Equipment Corporation,
581 and IBM for providing the environment where it could happen.
582
583Release 4
584
585 Our thanks go to Jim Fulton (MIT X Consortium) for designing
586 and specifying the new Xlib functions for Inter-Client
587 Communication Conventions (ICCCM) support.
588
589 We also thank Al Mento of Digital for his continued effort in
590 maintaining this document and Jim Fulton and Donna Converse
591 (MIT X Consortium) for their much-appreciated efforts in
592 reviewing the changes.
593
594Release 5
595
596 The principal authors of the Input Method facilities are Vania
597 Joloboff (Open Software Foundation) and Bill McMahon
598 (Hewlett-Packard). The principal author of the rest of the
599 internationalization facilities is Glenn Widener (Tektronix).
600 Our thanks to them for keeping their sense of humor through a
601 long and sometimes difficult design process. Although the words
602 and much of the design are due to them, many others have
603 contributed substantially to the design and implementation. Tom
604 McFarland (HP) and Frank Rojas (IBM) deserve particular
605 recognition for their contributions. Other contributors were:
606 Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov
607 (HP), Chih-Chung Ko (III), Vera Cheng (III), Michael Collins
608 (Digital), Walt Daniels (IBM), Noritoshi Demizu (OMRON),
609 Keisuke Fukui (Fujitsu), Hitoshoi Fukumoto (Nihon Sun), Tim
610 Greenwood (Digital), John Harvey (IBM), Hideki Hiura (Sun),
611 Fred Horman (AT&T), Norikazu Kaiya (Fujitsu), Yuji Kamata
612 (IBM), Yutaka Kataoka (Waseda University), Ranee Khubchandani
613 (Sun), Akira Kon (NEC), Hiroshi Kuribayashi (OMRON), Teruhiko
614 Kurosaka (Sun), Seiji Kuwari (OMRON), Sandra Martin (OSF),
615 Narita Masahiko (Fujitsu), Masato Morisaki (NTT), Nelson Ng
616 (Sun), Takashi Nishimura (NTT America), Makato Nishino (IBM),
617 Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart
618 (AT&T), Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori
619 Mehring (Digital), Shoji Sugiyama (IBM), and Eiji Tosa (IBM).
620
621 We are deeply indebted to Tatsuya Kato (NTT), Hiroshi
622 Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki
623 (NTT), and Li Yuhong (OMRON) for producing one of the first
624 complete sample implementation of the internationalization
625 facilities, and Hiromu Inukai (Nihon Sun), Takashi Fujiwara
626 (Fujitsu), Hideki Hiura (Sun), Yasuhiro Kawai (Oki
627 Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox),
628 Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba), Makoto
629 Wakamatsu (Sony Corporation) for producing the another complete
630 sample implementation of the internationalization facilities.
631
632 The principal authors (design and implementation) of the Xcms
633 color management facilities are Al Tabayoyon (Tektronix) and
634 Chuck Adams (Tektronix). Joann Taylor (Tektronix), Bob Toole
635 (Tektronix), and Keith Packard (MIT X Consortium) also
636 contributed significantly to the design. Others who contributed
637 are: Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI),
638 Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron
639 Johnson (Sun), Jim King (Adobe), Ricardo Motta (HP), Chuck Peek
640 (IBM), Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium),
641 Kumar Talluri (AT&T), and Richard Verberg (IBM).
642
643 We also once again thank Al Mento of Digital for his work in
644 formatting and reformatting text for this manual, and for
645 producing man pages. Thanks also to Clive Feather (IXI) for
646 proof-reading and finding a number of small errors.
647
648Release 6
649
650 Stephen Gildea (X Consortium) authored the threads support.
651 Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed
652 substantially by testing the facilities and reporting bugs in a
653 timely fashion.
654
655 The principal authors of the internationalization facilities,
656 including Input and Output Methods, are Hideki Hiura (SunSoft)
657 and Shigeru Yamada (Fujitsu OSSI). Although the words and much
658 of the design are due to them, many others have contributed
659 substantially to the design and implementation. They are:
660 Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM), Makoto Inada
661 (Digital), Hiromu Inukai (Nihon SunSoft), Song JaeKyung
662 (KAIST), Franky Ling (Digital), Tom McFarland (HP), Hiroyuki
663 Miyamoto (Digital), Masahiko Narita (Fujitsu), Frank Rojas
664 (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony), Makoto
665 Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba)
666 and Jinsoo Yoon (KAIST).
667
668 The principal producers of the sample implementation of the
669 internationalization facilities are: Jeffrey Bloomfield
670 (Fujitsu OSSI), Takashi Fujiwara (Fujitsu), Hideki Hiura
671 (SunSoft), Yoshio Horiuchi (IBM), Makoto Inada (Digital),
672 Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Riki
673 Kawaguchi (Fujitsu), Franky Ling (Digital), Hiroyuki Miyamoto
674 (Digital), Hidetoshi Tajima (HP), Toshimitsu Terazono
675 (Fujitsu), Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Shigeru
676 Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba).
677
678 The coordinators of the integration, testing, and release of
679 this implementation of the internationalization facilities are
680 Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony).
681
682 Others who have contributed to the architectural design or
683 testing of the sample implementation of the
684 internationalization facilities are: Hector Chan (Digital),
685 Michael Kung (IBM), Joseph Kwok (Digital), Hiroyuki Machida
686 (Sony), Nelson Ng (SunSoft), Frank Rojas (IBM), Yoshiyuki
687 Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu), Shoji
688 Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony),
689 Jinsoo Yoon (KAIST) and Akiyasu Zen (HP).
690
691 Jim Gettys
692 Cambridge Research Laboratory
693 Digital Equipment Corporation
694 Robert W. Scheifler
695 Laboratory for Computer Science
696 Massachusetts Institute of Technology
697
698Release 7
699
700 This document is made available to you in modern formats such
701 as HTML and PDF thanks to the efforts of Matt Dew, who
702 converted the original troff sources to DocBook/XML and edited
703 them into shape; along with Gaetan Nadon and Alan Coopersmith,
704 who set up the formatting machinery in the libX11 builds and
705 performed further editing of the DocBook markup.
706
707Chapter 1. Introduction to Xlib
708
709 Table of Contents
710
711 Overview of the X Window System
712 Errors
713 Standard Header Files
714 Generic Values and Types
715 Naming and Argument Conventions within Xlib
716 Programming Considerations
717 Character Sets and Encodings
718 Formatting Conventions
719
720 The X Window System is a network-transparent window system that
721 was designed at MIT. X display servers run on computers with
722 either monochrome or color bitmap display hardware. The server
723 distributes user input to and accepts output requests from
724 various client programs located either on the same machine or
725 elsewhere in the network. Xlib is a C subroutine library that
726 application programs (clients) use to interface with the window
727 system by means of a stream connection. Although a client
728 usually runs on the same machine as the X server it is talking
729 to, this need not be the case.
730
731 Xlib - C Language X Interface is a reference guide to the
732 low-level C language interface to the X Window System protocol.
733 It is neither a tutorial nor a user's guide to programming the
734 X Window System. Rather, it provides a detailed description of
735 each function in the library as well as a discussion of the
736 related background information. Xlib - C Language X Interface
737 assumes a basic understanding of a graphics window system and
738 of the C programming language. Other higher-level abstractions
739 (for example, those provided by the toolkits for X) are built
740 on top of the Xlib library. For further information about these
741 higher-level libraries, see the appropriate toolkit
742 documentation. The X Window System Protocol provides the
743 definitive word on the behavior of X. Although additional
744 information appears here, the protocol document is the ruling
745 document.
746
747 To provide an introduction to X programming, this chapter
748 discusses:
749 * Overview of the X Window System
750 * Errors
751 * Standard header files
752 * Generic values and types
753 * Naming and argument conventions within Xlib
754 * Programming considerations
755 * Character sets and encodings
756 * Formatting conventions
757
758Overview of the X Window System
759
760 Some of the terms used in this book are unique to X, and other
761 terms that are common to other window systems have different
762 meanings in X. You may find it helpful to refer to the
763 glossary, which is located at the end of the book.
764
765 The X Window System supports one or more screens containing
766 overlapping windows or subwindows. A screen is a physical
767 monitor and hardware that can be color, grayscale, or
768 monochrome. There can be multiple screens for each display or
769 workstation. A single X server can provide display services for
770 any number of screens. A set of screens for a single user with
771 one keyboard and one pointer (usually a mouse) is called a
772 display.
773
774 All the windows in an X server are arranged in strict
775 hierarchies. At the top of each hierarchy is a root window,
776 which covers each of the display screens. Each root window is
777 partially or completely covered by child windows. All windows,
778 except for root windows, have parents. There is usually at
779 least one window for each application program. Child windows
780 may in turn have their own children. In this way, an
781 application program can create an arbitrarily deep tree on each
782 screen. X provides graphics, text, and raster operations for
783 windows.
784
785 A child window can be larger than its parent. That is, part or
786 all of the child window can extend beyond the boundaries of the
787 parent, but all output to a window is clipped by its parent. If
788 several children of a window have overlapping locations, one of
789 the children is considered to be on top of or raised over the
790 others, thus obscuring them. Output to areas covered by other
791 windows is suppressed by the window system unless the window
792 has backing store. If a window is obscured by a second window,
793 the second window obscures only those ancestors of the second
794 window that are also ancestors of the first window.
795
796 A window has a border zero or more pixels in width, which can
797 be any pattern (pixmap) or solid color you like. A window
798 usually but not always has a background pattern, which will be
799 repainted by the window system when uncovered. Child windows
800 obscure their parents, and graphic operations in the parent
801 window usually are clipped by the children.
802
803 Each window and pixmap has its own coordinate system. The
804 coordinate system has the X axis horizontal and the Y axis
805 vertical with the origin [0, 0] at the upper-left corner.
806 Coordinates are integral, in terms of pixels, and coincide with
807 pixel centers. For a window, the origin is inside the border at
808 the inside, upper-left corner.
809
810 X does not guarantee to preserve the contents of windows. When
811 part or all of a window is hidden and then brought back onto
812 the screen, its contents may be lost. The server then sends the
813 client program an Expose event to notify it that part or all of
814 the window needs to be repainted. Programs must be prepared to
815 regenerate the contents of windows on demand.
816
817 X also provides off-screen storage of graphics objects, called
818 pixmaps. Single plane (depth 1) pixmaps are sometimes referred
819 to as bitmaps. Pixmaps can be used in most graphics functions
820 interchangeably with windows and are used in various graphics
821 operations to define patterns or tiles. Windows and pixmaps
822 together are referred to as drawables.
823
824 Most of the functions in Xlib just add requests to an output
825 buffer. These requests later execute asynchronously on the X
826 server. Functions that return values of information stored in
827 the server do not return (that is, they block) until an
828 explicit reply is received or an error occurs. You can provide
829 an error handler, which will be called when the error is
830 reported.
831
832 If a client does not want a request to execute asynchronously,
833 it can follow the request with a call to XSync, which blocks
834 until all previously buffered asynchronous events have been
835 sent and acted on. As an important side effect, the output
836 buffer in Xlib is always flushed by a call to any function that
837 returns a value from the server or waits for input.
838
839 Many Xlib functions will return an integer resource ID, which
840 allows you to refer to objects stored on the X server. These
841 can be of type Window, Font, Pixmap, Colormap, Cursor, and
842 GContext, as defined in the file <X11/X.h>. These resources are
843 created by requests and are destroyed (or freed) by requests or
844 when connections are closed. Most of these resources are
845 potentially sharable between applications, and in fact, windows
846 are manipulated explicitly by window manager programs. Fonts
847 and cursors are shared automatically across multiple screens.
848 Fonts are loaded and unloaded as needed and are shared by
849 multiple clients. Fonts are often cached in the server. Xlib
850 provides no support for sharing graphics contexts between
851 applications.
852
853 Client programs are informed of events. Events may either be
854 side effects of a request (for example, restacking windows
855 generates Expose events) or completely asynchronous (for
856 example, from the keyboard). A client program asks to be
857 informed of events. Because other applications can send events
858 to your application, programs must be prepared to handle (or
859 ignore) events of all types.
860
861 Input events (for example, a key pressed or the pointer moved)
862 arrive asynchronously from the server and are queued until they
863 are requested by an explicit call (for example, XNextEvent or
864 XWindowEvent). In addition, some library functions (for
865 example, XRaiseWindow) generate Expose and ConfigureRequest
866 events. These events also arrive asynchronously, but the client
867 may wish to explicitly wait for them by calling XSync after
868 calling a function that can cause the server to generate
869 events.
870
871Errors
872
873 Some functions return Status, an integer error indication. If
874 the function fails, it returns a zero. If the function returns
875 a status of zero, it has not updated the return arguments.
876 Because C does not provide multiple return values, many
877 functions must return their results by writing into
878 client-passed storage. By default, errors are handled either by
879 a standard library function or by one that you provide.
880 Functions that return pointers to strings return NULL pointers
881 if the string does not exist.
882
883 The X server reports protocol errors at the time that it
884 detects them. If more than one error could be generated for a
885 given request, the server can report any of them.
886
887 Because Xlib usually does not transmit requests to the server
888 immediately (that is, it buffers them), errors can be reported
889 much later than they actually occur. For debugging purposes,
890 however, Xlib provides a mechanism for forcing synchronous
891 behavior (see section 11.8.1). When synchronization is enabled,
892 errors are reported as they are generated.
893
894 When Xlib detects an error, it calls an error handler, which
895 your program can provide. If you do not provide an error
896 handler, the error is printed, and your program terminates.
897
898Standard Header Files
899
900 The following include files are part of the Xlib standard:
901
902 <X11/Xlib.h>
903
904 This is the main header file for Xlib. The majority of all Xlib
905 symbols are declared by including this file. This file also
906 contains the preprocessor symbol XlibSpecificationRelease. This
907 symbol is defined to have the 6 in this release of the
908 standard. (Release 5 of Xlib was the first release to have this
909 symbol.)
910
911 <X11/X.h>
912
913 This file declares types and constants for the X protocol that
914 are to be used by applications. It is included automatically
915 from <X11/Xlib.h> so application code should never need to
916 reference this file directly.
917
918 <X11/Xcms.h>
919
920 This file contains symbols for much of the color management
921 facilities described in chapter 6. All functions, types, and
922 symbols with the prefix "Xcms", plus the Color Conversion
923 Contexts macros, are declared in this file. <X11/Xlib.h> must
924 be included before including this file.
925
926 <X11/Xutil.h>
927
928 This file declares various functions, types, and symbols used
929 for inter-client communication and application utility
930 functions, which are described in chapters 14 and 16.
931 <X11/Xlib.h> must be included before including this file.
932
933 <X11/Xresource.h>
934
935 This file declares all functions, types, and symbols for the
936 resource manager facilities, which are described in chapter 15.
937 <X11/Xlib.h> must be included before including this file.
938
939 <X11/Xatom.h>
940
941 This file declares all predefined atoms, which are symbols with
942 the prefix "XA_".
943
944 <X11/cursorfont.h>
945
946 This file declares the cursor symbols for the standard cursor
947 font, which are listed in Appendix B. All cursor symbols have
948 the prefix "XC_".
949
950 <X11/keysymdef.h>
951
952 This file declares all standard KeySym values, which are
953 symbols with the prefix "XK_". The KeySyms are arranged in
954 groups, and a preprocessor symbol controls inclusion of each
955 group. The preprocessor symbol must be defined prior to
956 inclusion of the file to obtain the associated values. The
957 preprocessor symbols are XK_MISCELLANY, XK_XKB_KEYS, XK_3270,
958 XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, XK_KATAKANA,
959 XK_ARABIC, XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL,
960 XK_PUBLISHING, XK_APL, XK_HEBREW, XK_THAI, and XK_KOREAN.
961
962 <X11/keysym.h>
963
964 This file defines the preprocessor symbols XK_MISCELLANY,
965 XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and
966 XK_GREEK and then includes <X11/keysymdef.h>.
967
968 <X11/Xlibint.h>
969
970 This file declares all the functions, types, and symbols used
971 for extensions, which are described in Appendix C. This file
972 automatically includes <X11/Xlib.h>.
973
974 <X11/Xproto.h>
975
976 This file declares types and symbols for the basic X protocol,
977 for use in implementing extensions. It is included
978 automatically from <X11/Xlibint.h>, so application and
979 extension code should never need to reference this file
980 directly.
981
982 <X11/Xprotostr.h>
983
984 This file declares types and symbols for the basic X protocol,
985 for use in implementing extensions. It is included
986 automatically from <X11/Xproto.h>, so application and extension
987 code should never need to reference this file directly.
988
989 <X11/X10.h>
990
991 This file declares all the functions, types, and symbols used
992 for the X10 compatibility functions, which are described in
993 Appendix D.
994
995Generic Values and Types
996
997 The following symbols are defined by Xlib and used throughout
998 the manual:
999 * Xlib defines the type Bool and the Boolean values True and
1000 False.
1001 * None is the universal null resource ID or atom.
1002 * The type XID is used for generic resource IDs.
1003 * The type XPointer is defined to be char* and is used as a
1004 generic opaque pointer to data.
1005
1006Naming and Argument Conventions within Xlib
1007
1008 Xlib follows a number of conventions for the naming and syntax
1009 of the functions. Given that you remember what information the
1010 function requires, these conventions are intended to make the
1011 syntax of the functions more predictable.
1012
1013 The major naming conventions are:
1014 * To differentiate the X symbols from the other symbols, the
1015 library uses mixed case for external symbols. It leaves
1016 lowercase for variables and all uppercase for user macros,
1017 as per existing convention.
1018 * All Xlib functions begin with a capital X.
1019 * The beginnings of all function names and symbols are
1020 capitalized.
1021 * All user-visible data structures begin with a capital X.
1022 More generally, anything that a user might dereference
1023 begins with a capital X.
1024 * Macros and other symbols do not begin with a capital X. To
1025 distinguish them from all user symbols, each word in the
1026 macro is capitalized.
1027 * All elements of or variables in a data structure are in
1028 lowercase. Compound words, where needed, are constructed
1029 with underscores (_).
1030 * The display argument, where used, is always first in the
1031 argument list.
1032 * All resource objects, where used, occur at the beginning of
1033 the argument list immediately after the display argument.
1034 * When a graphics context is present together with another
1035 type of resource (most commonly, a drawable), the graphics
1036 context occurs in the argument list after the other
1037 resource. Drawables outrank all other resources.
1038 * Source arguments always precede the destination arguments
1039 in the argument list.
1040 * The x argument always precedes the y argument in the
1041 argument list.
1042 * The width argument always precedes the height argument in
1043 the argument list.
1044 * Where the x, y, width, and height arguments are used
1045 together, the x and y arguments always precede the width
1046 and height arguments.
1047 * Where a mask is accompanied with a structure, the mask
1048 always precedes the pointer to the structure in the
1049 argument list.
1050
1051Programming Considerations
1052
1053 The major programming considerations are:
1054 * Coordinates and sizes in X are actually 16-bit quantities.
1055 This decision was made to minimize the bandwidth required
1056 for a given level of performance. Coordinates usually are
1057 declared as an int in the interface. Values larger than 16
1058 bits are truncated silently. Sizes (width and height) are
1059 declared as unsigned quantities.
1060 * Keyboards are the greatest variable between different
1061 manufacturers' workstations. If you want your program to be
1062 portable, you should be particularly conservative here.
1063 * Many display systems have limited amounts of off-screen
1064 memory. If you can, you should minimize use of pixmaps and
1065 backing store.
1066 * The user should have control of their screen real estate.
1067 Therefore, you should write your applications to react to
1068 window management rather than presume control of the entire
1069 screen. What you do inside of your top-level window,
1070 however, is up to your application. For further
1071 information, see chapter 14 and the Inter-Client
1072 Communication Conventions Manual.
1073
1074Character Sets and Encodings
1075
1076 Some of the Xlib functions make reference to specific character
1077 sets and character encodings. The following are the most
1078 common:
1079
1080 X Portable Character Set
1081
1082 A basic set of 97 characters, which are assumed to exist in all
1083 locales supported by Xlib. This set contains the following
1084 characters:
1085
1086 a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>, <tab>
1087 , and <newline>
1088
1089 This set is the left/lower half of the graphic character set of
1090 ISO8859-1 plus space, tab, and newline. It is also the set of
1091 graphic characters in 7-bit ASCII plus the same three control
1092 characters. The actual encoding of these characters on the host
1093 is system dependent.
1094
1095 Host Portable Character Encoding
1096
1097 The encoding of the X Portable Character Set on the host. The
1098 encoding itself is not defined by this standard, but the
1099 encoding must be the same in all locales supported by Xlib on
1100 the host. If a string is said to be in the Host Portable
1101 Character Encoding, then it only contains characters from the X
1102 Portable Character Set, in the host encoding.
1103
1104 Latin-1
1105
1106 The coded character set defined by the ISO8859-1 standard.
1107
1108 Latin Portable Character Encoding
1109
1110 The encoding of the X Portable Character Set using the Latin-1
1111 codepoints plus ASCII control characters. If a string is said
1112 to be in the Latin Portable Character Encoding, then it only
1113 contains characters from the X Portable Character Set, not all
1114 of Latin-1.
1115
1116 STRING Encoding
1117
1118 Latin-1, plus tab and newline.
1119
1120 POSIX Portable Filename Character Set
1121
1122 The set of 65 characters, which can be used in naming files on
1123 a POSIX-compliant host, that are correctly processed in all
1124 locales. The set is:
1125
1126 a..z A..Z 0..9 ._-
1127
1128Formatting Conventions
1129
1130 Xlib - C Language X Interface uses the following conventions:
1131 * Global symbols are printed in this special font. These can
1132 be either function names, symbols defined in include files,
1133 or structure names. When declared and defined, function
1134 arguments are printed in italics. In the explanatory text
1135 that follows, they usually are printed in regular type.
1136 * Each function is introduced by a general discussion that
1137 distinguishes it from other functions. The function
1138 declaration itself follows, and each argument is
1139 specifically explained. Although ANSI C function prototype
1140 syntax is not used, Xlib header files normally declare
1141 functions using function prototypes in ANSI C environments.
1142 General discussion of the function, if any is required,
1143 follows the arguments. Where applicable, the last paragraph
1144 of the explanation lists the possible Xlib error codes that
1145 the function can generate. For a complete discussion of the
1146 Xlib error codes, see section 11.8.2.
1147 * To eliminate any ambiguity between those arguments that you
1148 pass and those that a function returns to you, the
1149 explanations for all arguments that you pass start with the
1150 word specifies or, in the case of multiple arguments, the
1151 word specify. The explanations for all arguments that are
1152 returned to you start with the word returns or, in the case
1153 of multiple arguments, the word return. The explanations
1154 for all arguments that you can pass and are returned start
1155 with the words specifies and returns.
1156 * Any pointer to a structure that is used to return a value
1157 is designated as such by the _return suffix as part of its
1158 name. All other pointers passed to these functions are used
1159 for reading only. A few arguments use pointers to
1160 structures that are used for both input and output and are
1161 indicated by using the _in_out suffix.
1162
1163Chapter 2. Display Functions
1164
1165 Table of Contents
1166
1167 Opening the Display
1168 Obtaining Information about the Display, Image Formats, or
1169 Screens
1170
1171 Display Macros
1172 Image Format Functions and Macros
1173 Screen Information Macros
1174
1175 Generating a NoOperation Protocol Request
1176 Freeing Client-Created Data
1177 Closing the Display
1178 Using X Server Connection Close Operations
1179 Using Xlib with Threads
1180 Using Internal Connections
1181
1182 Before your program can use a display, you must establish a
1183 connection to the X server. Once you have established a
1184 connection, you then can use the Xlib macros and functions
1185 discussed in this chapter to return information about the
1186 display. This chapter discusses how to:
1187 * Open (connect to) the display
1188 * Obtain information about the display, image formats, or
1189 screens
1190 * Generate a NoOperation protocol request
1191 * Free client-created data
1192 * Close (disconnect from) a display
1193 * Use X Server connection close operations
1194 * Use Xlib with threads
1195 * Use internal connections
1196
1197Opening the Display
1198
1199 To open a connection to the X server that controls a display,
1200 use XOpenDisplay.
1201
1202 Display *XOpenDisplay(char *display_name);
1203
1204 display_name
1205
1206 Specifies the hardware display name, which determines the
1207 display and communications domain to be used. On a
1208 POSIX-conformant system, if the display_name is NULL, it
1209 defaults to the value of the DISPLAY environment variable.
1210
1211 The encoding and interpretation of the display name are
1212 implementation-dependent. Strings in the Host Portable
1213 Character Encoding are supported; support for other characters
1214 is implementation-dependent. On POSIX-conformant systems, the
1215 display name or DISPLAY environment variable can be a string in
1216 the format:
1217
1218
1219 protocol/hostname:number.screen_number
1220
1221 protocol
1222
1223 Specifies a protocol family or an alias for a protocol family.
1224 Supported protocol families are implementation dependent. The
1225 protocol entry is optional. If protocol is not specified, the /
1226 separating protocol and hostname must also not be specified.
1227
1228 hostname
1229
1230 Specifies the name of the host machine on which the display is
1231 physically attached. You follow the hostname with either a
1232 single colon (:) or a double colon (::).
1233
1234 number
1235
1236 Specifies the number of the display server on that host
1237 machine. You may optionally follow this display number with a
1238 period (.). A single CPU can have more than one display.
1239 Multiple displays are usually numbered starting with zero.
1240
1241 screen_number
1242
1243 Specifies the screen to be used on that server. Multiple
1244 screens can be controlled by a single X server. The
1245 screen_number sets an internal variable that can be accessed by
1246 using the DefaultScreen macro or the XDefaultScreen function if
1247 you are using languages other than C (see section 2.2.1).
1248
1249 For example, the following would specify screen 1 of display 0
1250 on the machine named ``dual-headed'':
1251
1252dual-headed:0.1
1253
1254 The XOpenDisplay function returns a Display structure that
1255 serves as the connection to the X server and that contains all
1256 the information about that X server. XOpenDisplay connects your
1257 application to the X server through TCP or DECnet
1258 communications protocols, or through some local inter-process
1259 communication protocol. If the protocol is specified as "tcp",
1260 "inet", or "inet6", or if no protocol is specified and the
1261 hostname is a host machine name and a single colon (:)
1262 separates the hostname and display number, XOpenDisplay
1263 connects using TCP streams. (If the protocol is specified as
1264 "inet", TCP over IPv4 is used. If the protocol is specified as
1265 "inet6", TCP over IPv6 is used. Otherwise, the implementation
1266 determines which IP version is used.) If the hostname and
1267 protocol are both not specified, Xlib uses whatever it believes
1268 is the fastest transport. If the hostname is a host machine
1269 name and a double colon (::) separates the hostname and display
1270 number, XOpenDisplay connects using DECnet. A single X server
1271 can support any or all of these transport mechanisms
1272 simultaneously. A particular Xlib implementation can support
1273 many more of these transport mechanisms.
1274
1275 If successful, XOpenDisplay returns a pointer to a Display
1276 structure, which is defined in <X11/Xlib.h>. If XOpenDisplay
1277 does not succeed, it returns NULL. After a successful call to
1278 XOpenDisplay, all of the screens in the display can be used by
1279 the client. The screen number specified in the display_name
1280 argument is returned by the DefaultScreen macro (or the
1281 XDefaultScreen function). You can access elements of the
1282 Display and Screen structures only by using the information
1283 macros or functions. For information about using macros and
1284 functions to obtain information from the Display structure, see
1285 section 2.2.1.
1286
1287 X servers may implement various types of access control
1288 mechanisms (see section 9.8).
1289
1290Obtaining Information about the Display, Image Formats, or Screens
1291
1292 The Xlib library provides a number of useful macros and
1293 corresponding functions that return data from the Display
1294 structure. The macros are used for C programming, and their
1295 corresponding function equivalents are for other language
1296 bindings. This section discusses the:
1297 * Display macros
1298 * Image format functions and macros
1299 * Screen information macros
1300
1301 All other members of the Display structure (that is, those for
1302 which no macros are defined) are private to Xlib and must not
1303 be used. Applications must never directly modify or inspect
1304 these private members of the Display structure. The
1305 XDisplayWidth, XDisplayHeight, XDisplayCells, XDisplayPlanes,
1306 XDisplayWidthMM, and XDisplayHeightMM functions in the next
1307 sections are misnamed. These functions really should be named
1308 Screenwhatever and XScreenwhatever, not Displaywhatever or
1309 XDisplaywhatever. Our apologies for the resulting confusion.
1310
1311Display Macros
1312
1313 Applications should not directly modify any part of the Display
1314 and Screen structures. The members should be considered
1315 read-only, although they may change as the result of other
1316 operations on the display.
1317
1318 The following lists the C language macros, their corresponding
1319 function equivalents that are for other language bindings, and
1320 what data both can return.
1321AllPlanes
1322
1323 unsigned long XAllPlanes(void);
1324
1325 Both return a value with all bits set to 1 suitable for use in
1326 a plane argument to a procedure.
1327
1328 Both BlackPixel and WhitePixel can be used in implementing a
1329 monochrome application. These pixel values are for permanently
1330 allocated entries in the default colormap. The actual RGB (red,
1331 green, and blue) values are settable on some screens and, in
1332 any case, may not actually be black or white. The names are
1333 intended to convey the expected relative intensity of the
1334 colors.
1335
1336 BlackPixel(display, screen_number);
1337
1338 unsigned long XBlackPixel(Display *display, int screen_number);
1339
1340 display
1341
1342 Specifies the connection to the X server.
1343
1344 screen_number
1345
1346 Specifies the appropriate screen number on the host server.
1347
1348 Both return the black pixel value for the specified screen.
1349
1350 WhitePixel(display, screen_number);
1351
1352 unsigned long XWhitePixel(Display *display, int screen_number);
1353
1354 display
1355
1356 Specifies the connection to the X server.
1357
1358 screen_number
1359
1360 Specifies the appropriate screen number on the host server.
1361
1362 Both return the white pixel value for the specified screen.
1363
1364 ConnectionNumber(display);
1365
1366 int XConnectionNumber(Display *display);
1367
1368 display
1369
1370 Specifies the connection to the X server.
1371
1372 Both return a connection number for the specified display. On a
1373 POSIX-conformant system, this is the file descriptor of the
1374 connection.
1375
1376 DefaultColormap(display, screen_number);
1377
1378 Colormap XDefaultColormap(Display *display, int screen_number);
1379
1380 display
1381
1382 Specifies the connection to the X server.
1383
1384 screen_number
1385
1386 Specifies the appropriate screen number on the host server.
1387
1388 Both return the default colormap ID for allocation on the
1389 specified screen. Most routine allocations of color should be
1390 made out of this colormap.
1391
1392 DefaultDepth(display, screen_number);
1393
1394 int XDefaultDepth(Display *display, int screen_number);
1395
1396 display
1397
1398 Specifies the connection to the X server.
1399
1400 screen_number
1401
1402 Specifies the appropriate screen number on the host server.
1403
1404 Both return the depth (number of planes) of the default root
1405 window for the specified screen. Other depths may also be
1406 supported on this screen (see XMatchVisualInfo).
1407
1408 To determine the number of depths that are available on a given
1409 screen, use XListDepths.
1410
1411 int *XListDepths(Display *display, int screen_number, int
1412 *count_return);
1413
1414 display
1415
1416 Specifies the connection to the X server.
1417
1418 screen_number
1419
1420 Specifies the appropriate screen number on the host server.
1421
1422 count_return
1423
1424 Returns the number of depths.
1425
1426 The XListDepths function returns the array of depths that are
1427 available on the specified screen. If the specified
1428 screen_number is valid and sufficient memory for the array can
1429 be allocated, XListDepths sets count_return to the number of
1430 available depths. Otherwise, it does not set count_return and
1431 returns NULL. To release the memory allocated for the array of
1432 depths, use XFree.
1433
1434 DefaultGC(display, screen_number);
1435
1436 GC XDefaultGC(Display *display, int screen_number);
1437
1438 display
1439
1440 Specifies the connection to the X server.
1441
1442 screen_number
1443
1444 Specifies the appropriate screen number on the host server.
1445
1446 Both return the default graphics context for the root window of
1447 the specified screen. This GC is created for the convenience of
1448 simple applications and contains the default GC components with
1449 the foreground and background pixel values initialized to the
1450 black and white pixels for the screen, respectively. You can
1451 modify its contents freely because it is not used in any Xlib
1452 function. This GC should never be freed.
1453
1454 DefaultRootWindow(display);
1455
1456 Window XDefaultRootWindow(Display *display);
1457
1458 display
1459
1460 Specifies the connection to the X server.
1461
1462 Both return the root window for the default screen.
1463
1464 DefaultScreenOfDisplay(display);
1465
1466 Screen *XDefaultScreenOfDisplay(Display *display);
1467
1468 display
1469
1470 Specifies the connection to the X server.
1471
1472 Both return a pointer to the default screen.
1473
1474 ScreenOfDisplay(display, screen_number);
1475
1476 Screen *XScreenOfDisplay(Display *display, int screen_number);
1477
1478 display
1479
1480 Specifies the connection to the X server.
1481
1482 screen_number
1483
1484 Specifies the appropriate screen number on the host server.
1485
1486 Both return a pointer to the indicated screen.
1487
1488 DefaultScreen(display);
1489
1490 int XDefaultScreen(Display *display);
1491
1492 display
1493
1494 Specifies the connection to the X server.
1495
1496 Both return the default screen number referenced by the
1497 XOpenDisplay function. This macro or function should be used to
1498 retrieve the screen number in applications that will use only a
1499 single screen.
1500
1501 DefaultVisual(display, screen_number);
1502
1503 Visual *XDefaultVisual(Display *display, int screen_number);
1504
1505 display
1506
1507 Specifies the connection to the X server.
1508
1509 screen_number
1510
1511 Specifies the appropriate screen number on the host server.
1512
1513 Both return the default visual type for the specified screen.
1514 For further information about visual types, see section 3.1.
1515
1516 DisplayCells(display, screen_number);
1517
1518 int XDisplayCells(Display *display, int screen_number);
1519
1520 display
1521
1522 Specifies the connection to the X server.
1523
1524 screen_number
1525
1526 Specifies the appropriate screen number on the host server.
1527
1528 Both return the number of entries in the default colormap.
1529
1530 DisplayPlanes(display, screen_number);
1531
1532 int XDisplayPlanes(Display *display, int screen_number);
1533
1534 display
1535
1536 Specifies the connection to the X server.
1537
1538 screen_number
1539
1540 Specifies the appropriate screen number on the host server.
1541
1542 Both return the depth of the root window of the specified
1543 screen. For an explanation of depth, see the glossary.
1544
1545 DisplayString(display);
1546
1547 char *XDisplayString(Display *display);
1548
1549 display
1550
1551 Specifies the connection to the X server.
1552
1553 Both return the string that was passed to XOpenDisplay when the
1554 current display was opened. On POSIX-conformant systems, if the
1555 passed string was NULL, these return the value of the DISPLAY
1556 environment variable when the current display was opened. These
1557 are useful to applications that invoke the fork system call and
1558 want to open a new connection to the same display from the
1559 child process as well as for printing error messages.
1560
1561 long XExtendedMaxRequestSize(Display *display);
1562
1563 display
1564
1565 Specifies the connection to the X server.
1566
1567 The XExtendedMaxRequestSize function returns zero if the
1568 specified display does not support an extended-length protocol
1569 encoding; otherwise, it returns the maximum request size (in
1570 4-byte units) supported by the server using the extended-length
1571 encoding. The Xlib functions XDrawLines, XDrawArcs,
1572 XFillPolygon, XChangeProperty, XSetClipRectangles, and
1573 XSetRegion will use the extended-length encoding as necessary,
1574 if supported by the server. Use of the extended-length encoding
1575 in other Xlib functions (for example, XDrawPoints,
1576 XDrawRectangles, XDrawSegments, XFillArcs, XFillRectangles,
1577 XPutImage) is permitted but not required; an Xlib
1578 implementation may choose to split the data across multiple
1579 smaller requests instead.
1580
1581 long XMaxRequestSize(Display *display);
1582
1583 display
1584
1585 Specifies the connection to the X server.
1586
1587 The XMaxRequestSize function returns the maximum request size
1588 (in 4-byte units) supported by the server without using an
1589 extended-length protocol encoding. Single protocol requests to
1590 the server can be no larger than this size unless an
1591 extended-length protocol encoding is supported by the server.
1592 The protocol guarantees the size to be no smaller than 4096
1593 units (16384 bytes). Xlib automatically breaks data up into
1594 multiple protocol requests as necessary for the following
1595 functions: XDrawPoints, XDrawRectangles, XDrawSegments,
1596 XFillArcs, XFillRectangles, and XPutImage.
1597
1598 LastKnownRequestProcessed(display);
1599
1600 unsigned long XLastKnownRequestProcessed(Display *display);
1601
1602 display
1603
1604 Specifies the connection to the X server.
1605
1606 Both extract the full serial number of the last request known
1607 by Xlib to have been processed by the X server. Xlib
1608 automatically sets this number when replies, events, and errors
1609 are received.
1610
1611 NextRequest(display);
1612
1613 unsigned long XNextRequest(Display *display);
1614
1615 display
1616
1617 Specifies the connection to the X server.
1618
1619 Both extract the full serial number that is to be used for the
1620 next request. Serial numbers are maintained separately for each
1621 display connection.
1622
1623 ProtocolVersion(display);
1624
1625 int XProtocolVersion(Display *display);
1626
1627 display
1628
1629 Specifies the connection to the X server.
1630
1631 Both return the major version number (11) of the X protocol
1632 associated with the connected display.
1633
1634 ProtocolRevision(display);
1635
1636 int XProtocolRevision(Display *display);
1637
1638 display
1639
1640 Specifies the connection to the X server.
1641
1642 Both return the minor protocol revision number of the X server.
1643
1644 QLength(display);
1645
1646 int XQLength(Display *display);
1647
1648 display
1649
1650 Specifies the connection to the X server.
1651
1652 Both return the length of the event queue for the connected
1653 display. Note that there may be more events that have not been
1654 read into the queue yet (see XEventsQueued).
1655
1656 RootWindow(display, screen_number);
1657
1658 Window XRootWindow(Display *display, int screen_number);
1659
1660 display
1661
1662 Specifies the connection to the X server.
1663
1664 screen_number
1665
1666 Specifies the appropriate screen number on the host server.
1667
1668 Both return the root window. These are useful with functions
1669 that need a drawable of a particular screen and for creating
1670 top-level windows.
1671
1672 ScreenCount(display);
1673
1674 int XScreenCount(Display *display);
1675
1676 display
1677
1678 Specifies the connection to the X server.
1679
1680 Both return the number of available screens.
1681
1682 ServerVendor(display);
1683
1684 char *XServerVendor(Display *display);
1685
1686 display
1687
1688 Specifies the connection to the X server.
1689
1690 Both return a pointer to a null-terminated string that provides
1691 some identification of the owner of the X server
1692 implementation. If the data returned by the server is in the
1693 Latin Portable Character Encoding, then the string is in the
1694 Host Portable Character Encoding. Otherwise, the contents of
1695 the string are implementation-dependent.
1696
1697 VendorRelease(display);
1698
1699 int XVendorRelease(Display *display);
1700
1701 display
1702
1703 Specifies the connection to the X server.
1704
1705 Both return a number related to a vendor's release of the X
1706 server.
1707
1708Image Format Functions and Macros
1709
1710 Applications are required to present data to the X server in a
1711 format that the server demands. To help simplify applications,
1712 most of the work required to convert the data is provided by
1713 Xlib (see sections 8.7 and 16.8).
1714
1715 The XPixmapFormatValues structure provides an interface to the
1716 pixmap format information that is returned at the time of a
1717 connection setup. It contains:
1718typedef struct {
1719 int depth;
1720 int bits_per_pixel;
1721 int scanline_pad;
1722} XPixmapFormatValues;
1723
1724 To obtain the pixmap format information for a given display,
1725 use XListPixmapFormats.
1726
1727 XPixmapFormatValues *XListPixmapFormats(Display *display, int
1728 *count_return);
1729
1730 display
1731
1732 Specifies the connection to the X server.
1733
1734 count_return
1735
1736 Returns the number of pixmap formats that are supported by the
1737 display.
1738
1739 The XListPixmapFormats function returns an array of
1740 XPixmapFormatValues structures that describe the types of Z
1741 format images supported by the specified display. If
1742 insufficient memory is available, XListPixmapFormats returns
1743 NULL. To free the allocated storage for the XPixmapFormatValues
1744 structures, use XFree.
1745
1746 The following lists the C language macros, their corresponding
1747 function equivalents that are for other language bindings, and
1748 what data they both return for the specified server and screen.
1749 These are often used by toolkits as well as by simple
1750 applications.
1751
1752 ImageByteOrder(display);
1753
1754 int XImageByteOrder(Display *display);
1755
1756 display
1757
1758 Specifies the connection to the X server.
1759
1760 Both specify the required byte order for images for each
1761 scanline unit in XY format (bitmap) or for each pixel value in
1762 Z format. The macro or function can return either LSBFirst or
1763 MSBFirst.
1764
1765 XBitmapUnit(display);
1766
1767 int XBitmapUnit(Display *display);
1768
1769 display
1770
1771 Specifies the connection to the X server.
1772
1773 Both return the size of a bitmap's scanline unit in bits. The
1774 scanline is calculated in multiples of this value.
1775
1776 BitmapBitOrder(display);
1777
1778 int XBitmapBitOrder(Display *display);
1779
1780 display
1781
1782 Specifies the connection to the X server.
1783
1784 Within each bitmap unit, the left-most bit in the bitmap as
1785 displayed on the screen is either the least significant or most
1786 significant bit in the unit. This macro or function can return
1787 LSBFirst or MSBFirst.
1788
1789 BitmapPad(display);
1790
1791 int XBitmapPad(Display *display);
1792
1793 display
1794
1795 Specifies the connection to the X server.
1796
1797 Each scanline must be padded to a multiple of bits returned by
1798 this macro or function.
1799
1800 DisplayHeight(display, screen_number);
1801
1802 int XDisplayHeight(Display *display, int screen_number);
1803
1804 display
1805
1806 Specifies the connection to the X server.
1807
1808 screen_number
1809
1810 Specifies the appropriate screen number on the host server.
1811
1812 Both return an integer that describes the height of the screen
1813 in pixels.
1814
1815 DisplayHeightMM(display, screen_number);
1816
1817 int XDisplayHeightMM(Display *display, int screen_number);
1818
1819 display
1820
1821 Specifies the connection to the X server.
1822
1823 screen_number
1824
1825 Specifies the appropriate screen number on the host server.
1826
1827 Both return the height of the specified screen in millimeters.
1828
1829 DisplayWidth(display, screen_number);
1830
1831 int XDisplayWidth(Display *display, int screen_number);
1832
1833 display
1834
1835 Specifies the connection to the X server.
1836
1837 screen_number
1838
1839 Specifies the appropriate screen number on the host server.
1840
1841 Both return the width of the screen in pixels.
1842
1843 DisplayWidthMM(display, screen_number);
1844
1845 int XDisplayWidthMM(Display *display, int screen_number);
1846
1847 display
1848
1849 Specifies the connection to the X server.
1850
1851 screen_number
1852
1853 Specifies the appropriate screen number on the host server.
1854
1855 Both return the width of the specified screen in millimeters.
1856
1857Screen Information Macros
1858
1859 The following lists the C language macros, their corresponding
1860 function equivalents that are for other language bindings, and
1861 what data they both can return. These macros or functions all
1862 take a pointer to the appropriate screen structure.
1863
1864 BlackPixelOfScreen(screen);
1865
1866 unsigned long XBlackPixelOfScreen(Screen *screen);
1867
1868 screen
1869
1870 Specifies the appropriate Screen structure.
1871
1872 Both return the black pixel value of the specified screen.
1873
1874 XWhitePixelOfScreen(screen);
1875
1876 unsigned long XWhitePixelOfScreen(Screen *screen);
1877
1878 screen
1879
1880 Specifies the appropriate Screen structure.
1881
1882 Both return the white pixel value of the specified screen.
1883
1884 CellsOfScreen(screen);
1885
1886 int XCellsOfScreen(Screen *screen);
1887
1888 screen
1889
1890 Specifies the appropriate Screen structure.
1891
1892 Both return the number of colormap cells in the default
1893 colormap of the specified screen.
1894
1895 DefaultColormapOfScreen(screen);
1896
1897 Colormap XDefaultColormapOfScreen(Screen *screen);
1898
1899 screen
1900
1901 Specifies the appropriate Screen structure.
1902
1903 Both return the default colormap of the specified screen.
1904
1905 DefaultDepthOfScreen(screen);
1906
1907 int XDefaultDepthOfScreen(Screen *screen);
1908
1909 screen
1910
1911 Specifies the appropriate Screen structure.
1912
1913 Both return the depth of the root window.
1914
1915 DefaultGCOfScreen(screen);
1916
1917 GC XDefaultGCOfScreen(Screen *screen);
1918
1919 screen
1920
1921 Specifies the appropriate Screen structure.
1922
1923 Both return a default graphics context (GC) of the specified
1924 screen, which has the same depth as the root window of the
1925 screen. The GC must never be freed.
1926
1927 XDefaultVisualOfScreen(screen);
1928
1929 Visual *XDefaultVisualOfScreen(Screen *screen);
1930
1931 screen
1932
1933 Specifies the appropriate Screen structure.
1934
1935 Both return the default visual of the specified screen. For
1936 information on visual types, see section 3.1.
1937
1938 DoesBackingStore(screen);
1939
1940 int XDoesBackingStore(Screen *screen);
1941
1942 screen
1943
1944 Specifies the appropriate Screen structure.
1945
1946 Both return a value indicating whether the screen supports
1947 backing stores. The value returned can be one of WhenMapped,
1948 NotUseful, or Always (see section 3.2.4).
1949
1950 DoesSaveUnders(screen);
1951
1952 Bool XDoesSaveUnders(Screen *screen);
1953
1954 screen
1955
1956 Specifies the appropriate Screen structure.
1957
1958 Both return a Boolean value indicating whether the screen
1959 supports save unders. If True, the screen supports save unders.
1960 If False, the screen does not support save unders (see section
1961 3.2.5).
1962
1963 DisplayOfScreen(screen);
1964
1965 Display *XDisplayOfScreen(Screen *screen);
1966
1967 screen
1968
1969 Specifies the appropriate Screen structure.
1970
1971 Both return the display of the specified screen.
1972
1973 ScreenNumberOfScreen(screen);
1974
1975 long XScreenNumberOfScreen(Screen *screen);
1976
1977 screen
1978
1979 Specifies the appropriate Screen structure.
1980
1981 The XScreenNumberOfScreen function returns the screen index
1982 number of the specified screen.
1983
1984 EventMaskOfScreen(screen);
1985
1986 long XEventMaskOfScreen(Screen *screen);
1987
1988 screen
1989
1990 Specifies the appropriate Screen structure.
1991
1992 Both return the event mask of the root window for the specified
1993 screen at connection setup time.
1994
1995 WidthOfScreen(screen);
1996
1997 int XWidthOfScreen(Screen *screen);
1998
1999 screen
2000
2001 Specifies the appropriate Screen structure.
2002
2003 Both return the width of the specified screen in pixels.
2004
2005 HeightOfScreen(screen);
2006
2007 int XHeightOfScreen(Screen *screen);
2008
2009 screen
2010
2011 Specifies the appropriate Screen structure.
2012
2013 Both return the height of the specified screen in pixels.
2014
2015 WidthMMOfScreen(screen);
2016
2017 int XWidthMMOfScreen(Screen *screen);
2018
2019 screen
2020
2021 Specifies the appropriate Screen structure.
2022
2023 Both return the width of the specified screen in millimeters.
2024
2025 HeightMMOfScreen(screen);
2026
2027 int XHeightMMOfScreen(Screen *screen);
2028
2029 screen
2030
2031 Specifies the appropriate Screen structure.
2032
2033 Both return the height of the specified screen in millimeters.
2034
2035 MaxCmapsOfScreen(screen);
2036
2037 int XMaxCmapsOfScreen(Screen *screen);
2038
2039 screen
2040
2041 Specifies the appropriate Screen structure.
2042
2043 Both return the maximum number of installed colormaps supported
2044 by the specified screen (see section 9.3).
2045
2046 MinCmapsOfScreen(screen);
2047
2048 int XMinCmapsOfScreen(Screen *screen);
2049
2050 screen
2051
2052 Specifies the appropriate Screen structure.
2053
2054 Both return the minimum number of installed colormaps supported
2055 by the specified screen (see section 9.3).
2056
2057 PlanesOfScreen(screen);
2058
2059 int XPlanesOfScreen(Screen *screen);
2060
2061 screen
2062
2063 Specifies the appropriate Screen structure.
2064
2065 Both return the depth of the root window.
2066
2067 RootWindowOfScreen(screen);
2068
2069 Window XRootWindowOfScreen(Screen *screen);
2070
2071 screen
2072
2073 Specifies the appropriate Screen structure.
2074
2075 Both return the root window of the specified screen.
2076
2077Generating a NoOperation Protocol Request
2078
2079 To execute a NoOperation protocol request, use XNoOp.
2080
2081 XNoOp(Display *display);
2082
2083 display
2084
2085 Specifies the connection to the X server.
2086
2087 The XNoOp function sends a NoOperation protocol request to the
2088 X server, thereby exercising the connection.
2089
2090Freeing Client-Created Data
2091
2092 To free in-memory data that was created by an Xlib function,
2093 use XFree.
2094
2095 XFree(void *data);
2096
2097 data
2098
2099 Specifies the data that is to be freed.
2100
2101 The XFree function is a general-purpose Xlib routine that frees
2102 the specified data. You must use it to free any objects that
2103 were allocated by Xlib, unless an alternate function is
2104 explicitly specified for the object. A NULL pointer cannot be
2105 passed to this function.
2106
2107Closing the Display
2108
2109 To close a display or disconnect from the X server, use
2110 XCloseDisplay.
2111
2112 XCloseDisplay(Display *display);
2113
2114 display
2115
2116 Specifies the connection to the X server.
2117
2118 The XCloseDisplay function closes the connection to the X
2119 server for the display specified in the Display structure and
2120 destroys all windows, resource IDs (Window, Font, Pixmap,
2121 Colormap, Cursor, and GContext), or other resources that the
2122 client has created on this display, unless the close-down mode
2123 of the client has been changed (see XSetCloseDownMode).
2124 Therefore, these windows, resource IDs, and other resources
2125 should never be referenced again or an error will be generated.
2126 Before exiting, you should call XCloseDisplay explicitly so
2127 that any pending errors are reported as XCloseDisplay performs
2128 a final XSync operation.
2129
2130 XCloseDisplay can generate a BadGC error.
2131
2132 Xlib provides a function to permit the resources owned by a
2133 client to survive after the client's connection is closed. To
2134 change a client's close-down mode, use XSetCloseDownMode.
2135
2136 XSetCloseDownMode(Display *display, int close_mode);
2137
2138 display
2139
2140 Specifies the connection to the X server.
2141
2142 close_mode
2143
2144 Specifies the client close-down mode. You can pass DestroyAll,
2145 RetainPermanent, or RetainTemporary.
2146
2147 The XSetCloseDownMode function defines what will happen to the
2148 client's resources at connection close. A connection starts in
2149 DestroyAll mode. For information on what happens to the
2150 client's resources when the close_mode argument is
2151 RetainPermanent or RetainTemporary, see section 2.6.
2152
2153 XSetCloseDownMode can generate a BadValue error.
2154
2155Using X Server Connection Close Operations
2156
2157 When the X server's connection to a client is closed either by
2158 an explicit call to XCloseDisplay or by a process that exits,
2159 the X server performs the following automatic operations:
2160 * It disowns all selections owned by the client (see
2161 XSetSelectionOwner).
2162 * It performs an XUngrabPointer and XUngrabKeyboard if the
2163 client has actively grabbed the pointer or the keyboard.
2164 * It performs an XUngrabServer if the client has grabbed the
2165 server.
2166 * It releases all passive grabs made by the client.
2167 * It marks all resources (including colormap entries)
2168 allocated by the client either as permanent or temporary,
2169 depending on whether the close-down mode is RetainPermanent
2170 or RetainTemporary. However, this does not prevent other
2171 client applications from explicitly destroying the
2172 resources (see XSetCloseDownMode).
2173
2174 When the close-down mode is DestroyAll, the X server destroys
2175 all of a client's resources as follows:
2176 * It examines each window in the client's save-set to
2177 determine if it is an inferior (subwindow) of a window
2178 created by the client. (The save-set is a list of other
2179 clients' windows that are referred to as save-set windows.)
2180 If so, the X server reparents the save-set window to the
2181 closest ancestor so that the save-set window is not an
2182 inferior of a window created by the client. The reparenting
2183 leaves unchanged the absolute coordinates (with respect to
2184 the root window) of the upper-left outer corner of the
2185 save-set window.
2186 * It performs a MapWindow request on the save-set window if
2187 the save-set window is unmapped. The X server does this
2188 even if the save-set window was not an inferior of a window
2189 created by the client.
2190 * It destroys all windows created by the client.
2191 * It performs the appropriate free request on each nonwindow
2192 resource created by the client in the server (for example,
2193 Font, Pixmap, Cursor, Colormap, and GContext).
2194 * It frees all colors and colormap entries allocated by a
2195 client application.
2196
2197 Additional processing occurs when the last connection to the X
2198 server closes. An X server goes through a cycle of having no
2199 connections and having some connections. When the last
2200 connection to the X server closes as a result of a connection
2201 closing with the close_mode of DestroyAll, the X server does
2202 the following:
2203 * It resets its state as if it had just been started. The X
2204 server begins by destroying all lingering resources from
2205 clients that have terminated in RetainPermanent or
2206 RetainTemporary mode.
2207 * It deletes all but the predefined atom identifiers.
2208 * It deletes all properties on all root windows (see section
2209 4.3).
2210 * It resets all device maps and attributes (for example, key
2211 click, bell volume, and acceleration) as well as the access
2212 control list.
2213 * It restores the standard root tiles and cursors.
2214 * It restores the default font path.
2215 * It restores the input focus to state PointerRoot.
2216
2217 However, the X server does not reset if you close a connection
2218 with a close-down mode set to RetainPermanent or
2219 RetainTemporary.
2220
2221Using Xlib with Threads
2222
2223 On systems that have threads, support may be provided to permit
2224 multiple threads to use Xlib concurrently.
2225
2226 To initialize support for concurrent threads, use XInitThreads.
2227
2228 Status XInitThreads(void);
2229
2230 The XInitThreads function initializes Xlib support for
2231 concurrent threads. This function must be the first Xlib
2232 function a multi-threaded program calls, and it must complete
2233 before any other Xlib call is made. This function returns a
2234 nonzero status if initialization was successful; otherwise, it
2235 returns zero. On systems that do not support threads, this
2236 function always returns zero.
2237
2238 It is only necessary to call this function if multiple threads
2239 might use Xlib concurrently. If all calls to Xlib functions are
2240 protected by some other access mechanism (for example, a mutual
2241 exclusion lock in a toolkit or through explicit client
2242 programming), Xlib thread initialization is not required. It is
2243 recommended that single-threaded programs not call this
2244 function.
2245
2246 To lock a display across several Xlib calls, use XLockDisplay.
2247
2248 XLockDisplay(Display *display);
2249
2250 display
2251
2252 Specifies the connection to the X server.
2253
2254 The XLockDisplay function locks out all other threads from
2255 using the specified display. Other threads attempting to use
2256 the display will block until the display is unlocked by this
2257 thread. Nested calls to XLockDisplay work correctly; the
2258 display will not actually be unlocked until XUnlockDisplay has
2259 been called the same number of times as XLockDisplay. This
2260 function has no effect unless Xlib was successfully initialized
2261 for threads using XInitThreads.
2262
2263 To unlock a display, use XUnlockDisplay.
2264
2265 XUnlockDisplay(Display *display);
2266
2267 display
2268
2269 Specifies the connection to the X server.
2270
2271 The XUnlockDisplay function allows other threads to use the
2272 specified display again. Any threads that have blocked on the
2273 display are allowed to continue. Nested locking works
2274 correctly; if XLockDisplay has been called multiple times by a
2275 thread, then XUnlockDisplay must be called an equal number of
2276 times before the display is actually unlocked. This function
2277 has no effect unless Xlib was successfully initialized for
2278 threads using XInitThreads.
2279
2280Using Internal Connections
2281
2282 In addition to the connection to the X server, an Xlib
2283 implementation may require connections to other kinds of
2284 servers (for example, to input method servers as described in
2285 chapter 13). Toolkits and clients that use multiple displays,
2286 or that use displays in combination with other inputs, need to
2287 obtain these additional connections to correctly block until
2288 input is available and need to process that input when it is
2289 available. Simple clients that use a single display and block
2290 for input in an Xlib event function do not need to use these
2291 facilities.
2292
2293 To track internal connections for a display, use
2294 XAddConnectionWatch.
2295
2296 typedef void (*XConnectionWatchProc)(Display *display, XPointer
2297 client_data, int fd, Bool opening, XPointer *watch_data);
2298
2299 Status XAddConnectionWatch(Display *display,
2300 XConnectionWatchProc procedure, XPointer client_data);
2301
2302 display
2303
2304 Specifies the connection to the X server.
2305
2306 procedure
2307
2308 Specifies the procedure to be called.
2309
2310 client_data
2311
2312 Specifies the additional client data.
2313
2314 The XAddConnectionWatch function registers a procedure to be
2315 called each time Xlib opens or closes an internal connection
2316 for the specified display. The procedure is passed the display,
2317 the specified client_data, the file descriptor for the
2318 connection, a Boolean indicating whether the connection is
2319 being opened or closed, and a pointer to a location for private
2320 watch data. If opening is True, the procedure can store a
2321 pointer to private data in the location pointed to by
2322 watch_data; when the procedure is later called for this same
2323 connection and opening is False, the location pointed to by
2324 watch_data will hold this same private data pointer.
2325
2326 This function can be called at any time after a display is
2327 opened. If internal connections already exist, the registered
2328 procedure will immediately be called for each of them, before
2329 XAddConnectionWatch returns. XAddConnectionWatch returns a
2330 nonzero status if the procedure is successfully registered;
2331 otherwise, it returns zero.
2332
2333 The registered procedure should not call any Xlib functions. If
2334 the procedure directly or indirectly causes the state of
2335 internal connections or watch procedures to change, the result
2336 is not defined. If Xlib has been initialized for threads, the
2337 procedure is called with the display locked and the result of a
2338 call by the procedure to any Xlib function that locks the
2339 display is not defined unless the executing thread has
2340 externally locked the display using XLockDisplay.
2341
2342 To stop tracking internal connections for a display, use
2343 XRemoveConnectionWatch.
2344
2345 Status XRemoveConnectionWatch(Display *display,
2346 XConnectionWatchProc procedure, XPointer client_data);
2347
2348 display
2349
2350 Specifies the connection to the X server.
2351
2352 procedure
2353
2354 Specifies the procedure to be called.
2355
2356 client_data
2357
2358 Specifies the additional client data.
2359
2360 The XRemoveConnectionWatch function removes a previously
2361 registered connection watch procedure. The client_data must
2362 match the client_data used when the procedure was initially
2363 registered.
2364
2365 To process input on an internal connection, use
2366 XProcessInternalConnection.
2367
2368 void XProcessInternalConnection(Display *display, int fd);
2369
2370 display
2371
2372 Specifies the connection to the X server.
2373
2374 fd
2375
2376 Specifies the file descriptor.
2377
2378 The XProcessInternalConnection function processes input
2379 available on an internal connection. This function should be
2380 called for an internal connection only after an operating
2381 system facility (for example, select or poll) has indicated
2382 that input is available; otherwise, the effect is not defined.
2383
2384 To obtain all of the current internal connections for a
2385 display, use XInternalConnectionNumbers.
2386
2387 Status XInternalConnectionNumbers(Display *display, int ** fd,
2388 int * count_return);
2389
2390 display
2391
2392 Specifies the connection to the X server.
2393
2394 fd_return
2395
2396 Returns the file descriptors.
2397
2398 count_return
2399
2400 Returns the number of file descriptors.
2401
2402 The XInternalConnectionNumbers function returns a list of the
2403 file descriptors for all internal connections currently open
2404 for the specified display. When the allocated list is no longer
2405 needed, free it by using XFree. This functions returns a
2406 nonzero status if the list is successfully allocated;
2407 otherwise, it returns zero.
2408
2409Chapter 3. Window Functions
2410
2411 Table of Contents
2412
2413 Visual Types
2414 Window Attributes
2415
2416 Background Attribute
2417 Border Attribute
2418 Gravity Attributes
2419 Backing Store Attribute
2420 Save Under Flag
2421 Backing Planes and Backing Pixel Attributes
2422 Event Mask and Do Not Propagate Mask Attributes
2423 Override Redirect Flag
2424 Colormap Attribute
2425 Cursor Attribute
2426
2427 Creating Windows
2428 Destroying Windows
2429 Mapping Windows
2430 Unmapping Windows
2431 Configuring Windows
2432 Changing Window Stacking Order
2433 Changing Window Attributes
2434
2435Visual Types
2436
2437 On some display hardware, it may be possible to deal with color
2438 resources in more than one way. For example, you may be able to
2439 deal with a screen of either 12-bit depth with arbitrary
2440 mapping of pixel to color (pseudo-color) or 24-bit depth with 8
2441 bits of the pixel dedicated to each of red, green, and blue.
2442 These different ways of dealing with the visual aspects of the
2443 screen are called visuals. For each screen of the display,
2444 there may be a list of valid visual types supported at
2445 different depths of the screen. Because default windows and
2446 visual types are defined for each screen, most simple
2447 applications need not deal with this complexity. Xlib provides
2448 macros and functions that return the default root window, the
2449 default depth of the default root window, and the default
2450 visual type (see sections 2.2.1 and 16.7).
2451
2452 Xlib uses an opaque Visual structure that contains information
2453 about the possible color mapping. The visual utility functions
2454 (see section 16.7) use an XVisualInfo structure to return this
2455 information to an application. The members of this structure
2456 pertinent to this discussion are class, red_mask, green_mask,
2457 blue_mask, bits_per_rgb, and colormap_size. The class member
2458 specifies one of the possible visual classes of the screen and
2459 can be StaticGray, StaticColor, TrueColor, GrayScale,
2460 PseudoColor, or DirectColor.
2461
2462 The following concepts may serve to make the explanation of
2463 visual types clearer. The screen can be color or grayscale, can
2464 have a colormap that is writable or read-only, and can also
2465 have a colormap whose indices are decomposed into separate RGB
2466 pieces, provided one is not on a grayscale screen. This leads
2467 to the following diagram:
2468 Color Gray-Scale
2469 R/O R/W R/O R/W
2470----------------------------------------------
2471 Undecomposed Static Pseudo Static Gray
2472 Colormap Color Color Gray Scale
2473
2474 Decomposed True Direct
2475 Colormap Color Color
2476----------------------------------------------
2477
2478 Conceptually, as each pixel is read out of video memory for
2479 display on the screen, it goes through a look-up stage by
2480 indexing into a colormap. Colormaps can be manipulated
2481 arbitrarily on some hardware, in limited ways on other
2482 hardware, and not at all on other hardware. The visual types
2483 affect the colormap and the RGB values in the following ways:
2484
2485 * For PseudoColor, a pixel value indexes a colormap to
2486 produce independent RGB values, and the RGB values can be
2487 changed dynamically.
2488 * GrayScale is treated the same way as PseudoColor except
2489 that the primary that drives the screen is undefined. Thus,
2490 the client should always store the same value for red,
2491 green, and blue in the colormaps.
2492 * For DirectColor, a pixel value is decomposed into separate
2493 RGB subfields, and each subfield separately indexes the
2494 colormap for the corresponding value. The RGB values can be
2495 changed dynamically.
2496 * TrueColor is treated the same way as DirectColor except
2497 that the colormap has predefined, read-only RGB values.
2498 These RGB values are server dependent but provide linear or
2499 near-linear ramps in each primary.
2500 * StaticColor is treated the same way as PseudoColor except
2501 that the colormap has predefined, read-only,
2502 server-dependent RGB values.
2503 * StaticGray is treated the same way as StaticColor except
2504 that the RGB values are equal for any single pixel value,
2505 thus resulting in shades of gray. StaticGray with a
2506 two-entry colormap can be thought of as monochrome.
2507
2508 The red_mask, green_mask, and blue_mask members are only
2509 defined for DirectColor and TrueColor. Each has one contiguous
2510 set of bits with no intersections. The bits_per_rgb member
2511 specifies the log base 2 of the number of distinct color values
2512 (individually) of red, green, and blue. Actual RGB values are
2513 unsigned 16-bit numbers. The colormap_size member defines the
2514 number of available colormap entries in a newly created
2515 colormap. For DirectColor and TrueColor, this is the size of an
2516 individual pixel subfield.
2517
2518 To obtain the visual ID from a Visual, use XVisualIDFromVisual.
2519
2520 VisualID XVisualIDFromVisual(Visual *visual);
2521
2522 visual
2523
2524 Specifies the visual type.
2525
2526 The XVisualIDFromVisual function returns the visual ID for the
2527 specified visual type.
2528
2529Window Attributes
2530
2531 All InputOutput windows have a border width of zero or more
2532 pixels, an optional background, an event suppression mask
2533 (which suppresses propagation of events from children), and a
2534 property list (see section 4.3). The window border and
2535 background can be a solid color or a pattern, called a tile.
2536 All windows except the root have a parent and are clipped by
2537 their parent. If a window is stacked on top of another window,
2538 it obscures that other window for the purpose of input. If a
2539 window has a background (almost all do), it obscures the other
2540 window for purposes of output. Attempts to output to the
2541 obscured area do nothing, and no input events (for example,
2542 pointer motion) are generated for the obscured area.
2543
2544 Windows also have associated property lists (see section 4.3).
2545
2546 Both InputOutput and InputOnly windows have the following
2547 common attributes, which are the only attributes of an
2548 InputOnly window:
2549 * win-gravity
2550 * event-mask
2551 * do-not-propagate-mask
2552 * override-redirect
2553 * cursor
2554
2555 If you specify any other attributes for an InputOnly window, a
2556 BadMatch error results.
2557
2558 InputOnly windows are used for controlling input events in
2559 situations where InputOutput windows are unnecessary. InputOnly
2560 windows are invisible; can only be used to control such things
2561 as cursors, input event generation, and grabbing; and cannot be
2562 used in any graphics requests. Note that InputOnly windows
2563 cannot have InputOutput windows as inferiors.
2564
2565 Windows have borders of a programmable width and pattern as
2566 well as a background pattern or tile. Pixel values can be used
2567 for solid colors. The background and border pixmaps can be
2568 destroyed immediately after creating the window if no further
2569 explicit references to them are to be made. The pattern can
2570 either be relative to the parent or absolute. If
2571 ParentRelative, the parent's background is used.
2572
2573 When windows are first created, they are not visible (not
2574 mapped) on the screen. Any output to a window that is not
2575 visible on the screen and that does not have backing store will
2576 be discarded. An application may wish to create a window long
2577 before it is mapped to the screen. When a window is eventually
2578 mapped to the screen (using XMapWindow), the X server generates
2579 an Expose event for the window if backing store has not been
2580 maintained.
2581
2582 A window manager can override your choice of size, border
2583 width, and position for a top-level window. Your program must
2584 be prepared to use the actual size and position of the top
2585 window. It is not acceptable for a client application to resize
2586 itself unless in direct response to a human command to do so.
2587 Instead, either your program should use the space given to it,
2588 or if the space is too small for any useful work, your program
2589 might ask the user to resize the window. The border of your
2590 top-level window is considered fair game for window managers.
2591
2592 To set an attribute of a window, set the appropriate member of
2593 the XSetWindowAttributes structure and OR in the corresponding
2594 value bitmask in your subsequent calls to XCreateWindow and
2595 XChangeWindowAttributes, or use one of the other convenience
2596 functions that set the appropriate attribute. The symbols for
2597 the value mask bits and the XSetWindowAttributes structure are:
2598
2599 /* Window attribute value mask bits */
2600/* Window attribute value mask bits */
2601#define CWBackPixmap (1L<<0)
2602#define CWBackPixel (1L<<1)
2603#define CWBorderPixmap (1L<<2)
2604#define CWBorderPixel (1L<<3)
2605#define CWBitGravity (1L<<4)
2606#define CWWinGravity (1L<<5)
2607#define CWBackingStore (1L<<6)
2608#define CWBackingPlanes (1L<<7)
2609#define CWBackingPixel (1L<<8)
2610#define CWOverrideRedirect (1L<<9)
2611#define CWSaveUnder (1L<<10)
2612#define CWEventMask (1L<<11)
2613#define CWDontPropagate (1L<<12)
2614#define CWColormap (1L<<13)
2615#define CWCursor (1L<<14)
2616
2617
2618
2619/* Values */
2620
2621typedef struct {
2622 Pixmap background_pixmap; /* background, None, or ParentRelativ
2623e */
2624 unsigned long background_pixel; /* background pixel */
2625 Pixmap border_pixmap; /* border of the window or CopyFromP
2626arent */
2627 unsigned long border_pixel; /* border pixel value */
2628 int bit_gravity; /* one of bit gravity values */
2629 int win_gravity; /* one of the window gravity values */
2630 int backing_store; /* NotUseful, WhenMapped, Always */
2631 unsigned long backing_planes; /* planes to be preserved if poss
2632ible */
2633 unsigned long backing_pixel; /* value to use in restoring plane
2634s */
2635 Bool save_under; /* should bits under be saved? (popups) */
2636 long event_mask; /* set of events that should be saved */
2637 long do_not_propagate_mask; /* set of events that should not pr
2638opagate */
2639 Bool override_redirect; /* boolean value for override_redirect
2640*/
2641 Colormap colormap; /* color map to be associated with window */
2642 Cursor cursor; /* cursor to be displayed (or None) */
2643} XSetWindowAttributes;
2644
2645 The following lists the defaults for each window attribute and
2646 indicates whether the attribute is applicable to InputOutput
2647 and InputOnly windows:
2648 Attribute Default InputOutput InputOnly
2649 background-pixmap None Yes No
2650 background-pixel Undefined Yes No
2651 border-pixmap CopyFromParent Yes No
2652 border-pixel Undefined Yes No
2653 bit-gravity ForgetGravity Yes No
2654 win-gravity NorthWestGravity Yes Yes
2655 backing-store NotUseful Yes No
2656 backing-planes All ones Yes No
2657 backing-pixel zero Yes No
2658 save-under False Yes No
2659 event-mask empty set Yes Yes
2660 do-not-propagate-mask empty set Yes Yes
2661 override-redirect False Yes Yes
2662 colormap CopyFromParent Yes No
2663 cursor None Yes Yes
2664
2665Background Attribute
2666
2667 Only InputOutput windows can have a background. You can set the
2668 background of an InputOutput window by using a pixel or a
2669 pixmap.
2670
2671 The background-pixmap attribute of a window specifies the
2672 pixmap to be used for a window's background. This pixmap can be
2673 of any size, although some sizes may be faster than others. The
2674 background-pixel attribute of a window specifies a pixel value
2675 used to paint a window's background in a single color.
2676
2677 You can set the background-pixmap to a pixmap, None (default),
2678 or ParentRelative. You can set the background-pixel of a window
2679 to any pixel value (no default). If you specify a
2680 background-pixel, it overrides either the default
2681 background-pixmap or any value you may have set in the
2682 background-pixmap. A pixmap of an undefined size that is filled
2683 with the background-pixel is used for the background. Range
2684 checking is not performed on the background pixel; it simply is
2685 truncated to the appropriate number of bits.
2686
2687 If you set the background-pixmap, it overrides the default. The
2688 background-pixmap and the window must have the same depth, or a
2689 BadMatch error results. If you set background-pixmap to None,
2690 the window has no defined background. If you set the
2691 background-pixmap to ParentRelative:
2692 * The parent window's background-pixmap is used. The child
2693 window, however, must have the same depth as its parent, or
2694 a BadMatch error results.
2695 * If the parent window has a background-pixmap of None, the
2696 window also has a background-pixmap of None.
2697 * A copy of the parent window's background-pixmap is not
2698 made. The parent's background-pixmap is examined each time
2699 the child window's background-pixmap is required.
2700 * The background tile origin always aligns with the parent
2701 window's background tile origin. If the background-pixmap
2702 is not ParentRelative, the background tile origin is the
2703 child window's origin.
2704
2705 Setting a new background, whether by setting background-pixmap
2706 or background-pixel, overrides any previous background. The
2707 background-pixmap can be freed immediately if no further
2708 explicit reference is made to it (the X server will keep a copy
2709 to use when needed). If you later draw into the pixmap used for
2710 the background, what happens is undefined because the X
2711 implementation is free to make a copy of the pixmap or to use
2712 the same pixmap.
2713
2714 When no valid contents are available for regions of a window
2715 and either the regions are visible or the server is maintaining
2716 backing store, the server automatically tiles the regions with
2717 the window's background unless the window has a background of
2718 None. If the background is None, the previous screen contents
2719 from other windows of the same depth as the window are simply
2720 left in place as long as the contents come from the parent of
2721 the window or an inferior of the parent. Otherwise, the initial
2722 contents of the exposed regions are undefined. Expose events
2723 are then generated for the regions, even if the
2724 background-pixmap is None (see section 10.9).
2725
2726Border Attribute
2727
2728 Only InputOutput windows can have a border. You can set the
2729 border of an InputOutput window by using a pixel or a pixmap.
2730
2731 The border-pixmap attribute of a window specifies the pixmap to
2732 be used for a window's border. The border-pixel attribute of a
2733 window specifies a pixmap of undefined size filled with that
2734 pixel be used for a window's border. Range checking is not
2735 performed on the background pixel; it simply is truncated to
2736 the appropriate number of bits. The border tile origin is
2737 always the same as the background tile origin.
2738
2739 You can also set the border-pixmap to a pixmap of any size
2740 (some may be faster than others) or to CopyFromParent
2741 (default). You can set the border-pixel to any pixel value (no
2742 default).
2743
2744 If you set a border-pixmap, it overrides the default. The
2745 border-pixmap and the window must have the same depth, or a
2746 BadMatch error results. If you set the border-pixmap to
2747 CopyFromParent, the parent window's border-pixmap is copied.
2748 Subsequent changes to the parent window's border attribute do
2749 not affect the child window. However, the child window must
2750 have the same depth as the parent window, or a BadMatch error
2751 results.
2752
2753 The border-pixmap can be freed immediately if no further
2754 explicit reference is made to it. If you later draw into the
2755 pixmap used for the border, what happens is undefined because
2756 the X implementation is free either to make a copy of the
2757 pixmap or to use the same pixmap. If you specify a
2758 border-pixel, it overrides either the default border-pixmap or
2759 any value you may have set in the border-pixmap. All pixels in
2760 the window's border will be set to the border-pixel. Setting a
2761 new border, whether by setting border-pixel or by setting
2762 border-pixmap, overrides any previous border.
2763
2764 Output to a window is always clipped to the inside of the
2765 window. Therefore, graphics operations never affect the window
2766 border.
2767
2768Gravity Attributes
2769
2770 The bit gravity of a window defines which region of the window
2771 should be retained when an InputOutput window is resized. The
2772 default value for the bit-gravity attribute is ForgetGravity.
2773 The window gravity of a window allows you to define how the
2774 InputOutput or InputOnly window should be repositioned if its
2775 parent is resized. The default value for the win-gravity
2776 attribute is NorthWestGravity.
2777
2778 If the inside width or height of a window is not changed and if
2779 the window is moved or its border is changed, then the contents
2780 of the window are not lost but move with the window. Changing
2781 the inside width or height of the window causes its contents to
2782 be moved or lost (depending on the bit-gravity of the window)
2783 and causes children to be reconfigured (depending on their
2784 win-gravity). For a change of width and height, the (x, y)
2785 pairs are defined:
2786
2787 Gravity Direction Coordinates
2788 NorthWestGravity (0, 0)
2789 NorthGravity (Width/2, 0)
2790 NorthEastGravity (Width, 0)
2791 WestGravity (0, Height/2)
2792 CenterGravity (Width/2, Height/2)
2793 EastGravity (Width, Height/2)
2794 SouthWestGravity (0, Height)
2795 SouthGravity (Width/2, Height)
2796 SouthEastGravity (Width, Height)
2797
2798 When a window with one of these bit-gravity values is resized,
2799 the corresponding pair defines the change in position of each
2800 pixel in the window. When a window with one of these
2801 win-gravities has its parent window resized, the corresponding
2802 pair defines the change in position of the window within the
2803 parent. When a window is so repositioned, a GravityNotify event
2804 is generated (see section 10.10.5).
2805
2806 A bit-gravity of StaticGravity indicates that the contents or
2807 origin should not move relative to the origin of the root
2808 window. If the change in size of the window is coupled with a
2809 change in position (x, y), then for bit-gravity the change in
2810 position of each pixel is (-x, -y), and for win-gravity the
2811 change in position of a child when its parent is so resized is
2812 (-x, -y). Note that StaticGravity still only takes effect when
2813 the width or height of the window is changed, not when the
2814 window is moved.
2815
2816 A bit-gravity of ForgetGravity indicates that the window's
2817 contents are always discarded after a size change, even if a
2818 backing store or save under has been requested. The window is
2819 tiled with its background and zero or more Expose events are
2820 generated. If no background is defined, the existing screen
2821 contents are not altered. Some X servers may also ignore the
2822 specified bit-gravity and always generate Expose events.
2823
2824 The contents and borders of inferiors are not affected by their
2825 parent's bit-gravity. A server is permitted to ignore the
2826 specified bit-gravity and use Forget instead.
2827
2828 A win-gravity of UnmapGravity is like NorthWestGravity (the
2829 window is not moved), except the child is also unmapped when
2830 the parent is resized, and an UnmapNotify event is generated.
2831
2832Backing Store Attribute
2833
2834 Some implementations of the X server may choose to maintain the
2835 contents of InputOutput windows. If the X server maintains the
2836 contents of a window, the off-screen saved pixels are known as
2837 backing store. The backing store advises the X server on what
2838 to do with the contents of a window. The backing-store
2839 attribute can be set to NotUseful (default), WhenMapped, or
2840 Always.
2841
2842 A backing-store attribute of NotUseful advises the X server
2843 that maintaining contents is unnecessary, although some X
2844 implementations may still choose to maintain contents and,
2845 therefore, not generate Expose events. A backing-store
2846 attribute of WhenMapped advises the X server that maintaining
2847 contents of obscured regions when the window is mapped would be
2848 beneficial. In this case, the server may generate an Expose
2849 event when the window is created. A backing-store attribute of
2850 Always advises the X server that maintaining contents even when
2851 the window is unmapped would be beneficial. Even if the window
2852 is larger than its parent, this is a request to the X server to
2853 maintain complete contents, not just the region within the
2854 parent window boundaries. While the X server maintains the
2855 window's contents, Expose events normally are not generated,
2856 but the X server may stop maintaining contents at any time.
2857
2858 When the contents of obscured regions of a window are being
2859 maintained, regions obscured by noninferior windows are
2860 included in the destination of graphics requests (and source,
2861 when the window is the source). However, regions obscured by
2862 inferior windows are not included.
2863
2864Save Under Flag
2865
2866 Some server implementations may preserve contents of
2867 InputOutput windows under other InputOutput windows. This is
2868 not the same as preserving the contents of a window for you.
2869 You may get better visual appeal if transient windows (for
2870 example, pop-up menus) request that the system preserve the
2871 screen contents under them, so the temporarily obscured
2872 applications do not have to repaint.
2873
2874 You can set the save-under flag to True or False (default). If
2875 save-under is True, the X server is advised that, when this
2876 window is mapped, saving the contents of windows it obscures
2877 would be beneficial.
2878
2879Backing Planes and Backing Pixel Attributes
2880
2881 You can set backing planes to indicate (with bits set to 1)
2882 which bit planes of an InputOutput window hold dynamic data
2883 that must be preserved in backing store and during save unders.
2884 The default value for the backing-planes attribute is all bits
2885 set to 1. You can set backing pixel to specify what bits to use
2886 in planes not covered by backing planes. The default value for
2887 the backing-pixel attribute is all bits set to 0. The X server
2888 is free to save only the specified bit planes in the backing
2889 store or the save under and is free to regenerate the remaining
2890 planes with the specified pixel value. Any extraneous bits in
2891 these values (that is, those bits beyond the specified depth of
2892 the window) may be simply ignored. If you request backing store
2893 or save unders, you should use these members to minimize the
2894 amount of off-screen memory required to store your window.
2895
2896Event Mask and Do Not Propagate Mask Attributes
2897
2898 The event mask defines which events the client is interested in
2899 for this InputOutput or InputOnly window (or, for some event
2900 types, inferiors of this window). The event mask is the bitwise
2901 inclusive OR of zero or more of the valid event mask bits. You
2902 can specify that no maskable events are reported by setting
2903 NoEventMask (default).
2904
2905 The do-not-propagate-mask attribute defines which events should
2906 not be propagated to ancestor windows when no client has the
2907 event type selected in this InputOutput or InputOnly window.
2908 The do-not-propagate-mask is the bitwise inclusive OR of zero
2909 or more of the following masks: KeyPress, KeyRelease,
2910 ButtonPress, ButtonRelease, PointerMotion, Button1Motion,
2911 Button2Motion, Button3Motion, Button4Motion, Button5Motion, and
2912 ButtonMotion. You can specify that all events are propagated by
2913 setting NoEventMask (default).
2914
2915Override Redirect Flag
2916
2917 To control window placement or to add decoration, a window
2918 manager often needs to intercept (redirect) any map or
2919 configure request. Pop-up windows, however, often need to be
2920 mapped without a window manager getting in the way. To control
2921 whether an InputOutput or InputOnly window is to ignore these
2922 structure control facilities, use the override-redirect flag.
2923
2924 The override-redirect flag specifies whether map and configure
2925 requests on this window should override a
2926 SubstructureRedirectMask on the parent. You can set the
2927 override-redirect flag to True or False (default). Window
2928 managers use this information to avoid tampering with pop-up
2929 windows (see also chapter 14).
2930
2931Colormap Attribute
2932
2933 The colormap attribute specifies which colormap best reflects
2934 the true colors of the InputOutput window. The colormap must
2935 have the same visual type as the window, or a BadMatch error
2936 results. X servers capable of supporting multiple hardware
2937 colormaps can use this information, and window managers can use
2938 it for calls to XInstallColormap. You can set the colormap
2939 attribute to a colormap or to CopyFromParent (default).
2940
2941 If you set the colormap to CopyFromParent, the parent window's
2942 colormap is copied and used by its child. However, the child
2943 window must have the same visual type as the parent, or a
2944 BadMatch error results. The parent window must not have a
2945 colormap of None, or a BadMatch error results. The colormap is
2946 copied by sharing the colormap object between the child and
2947 parent, not by making a complete copy of the colormap contents.
2948 Subsequent changes to the parent window's colormap attribute do
2949 not affect the child window.
2950
2951Cursor Attribute
2952
2953 The cursor attribute specifies which cursor is to be used when
2954 the pointer is in the InputOutput or InputOnly window. You can
2955 set the cursor to a cursor or None (default).
2956
2957 If you set the cursor to None, the parent's cursor is used when
2958 the pointer is in the InputOutput or InputOnly window, and any
2959 change in the parent's cursor will cause an immediate change in
2960 the displayed cursor. By calling XFreeCursor, the cursor can be
2961 freed immediately as long as no further explicit reference to
2962 it is made.
2963
2964Creating Windows
2965
2966 Xlib provides basic ways for creating windows, and toolkits
2967 often supply higher-level functions specifically for creating
2968 and placing top-level windows, which are discussed in the
2969 appropriate toolkit documentation. If you do not use a toolkit,
2970 however, you must provide some standard information or hints
2971 for the window manager by using the Xlib inter-client
2972 communication functions (see chapter 14).
2973
2974 If you use Xlib to create your own top-level windows (direct
2975 children of the root window), you must observe the following
2976 rules so that all applications interact reasonably across the
2977 different styles of window management:
2978 * You must never fight with the window manager for the size
2979 or placement of your top-level window.
2980 * You must be able to deal with whatever size window you get,
2981 even if this means that your application just prints a
2982 message like ``Please make me bigger'' in its window.
2983 * You should only attempt to resize or move top-level windows
2984 in direct response to a user request. If a request to
2985 change the size of a top-level window fails, you must be
2986 prepared to live with what you get. You are free to resize
2987 or move the children of top-level windows as necessary.
2988 (Toolkits often have facilities for automatic relayout.)
2989 * If you do not use a toolkit that automatically sets
2990 standard window properties, you should set these properties
2991 for top-level windows before mapping them.
2992
2993 For further information, see chapter 14 and the Inter-Client
2994 Communication Conventions Manual.
2995
2996 XCreateWindow is the more general function that allows you to
2997 set specific window attributes when you create a window.
2998 XCreateSimpleWindow creates a window that inherits its
2999 attributes from its parent window.
3000
3001 The X server acts as if InputOnly windows do not exist for the
3002 purposes of graphics requests, exposure processing, and
3003 VisibilityNotify events. An InputOnly window cannot be used as
3004 a drawable (that is, as a source or destination for graphics
3005 requests). InputOnly and InputOutput windows act identically in
3006 other respects (properties, grabs, input control, and so on).
3007 Extension packages can define other classes of windows.
3008
3009 To create an unmapped window and set its window attributes, use
3010 XCreateWindow.
3011
3012 Window XCreateWindow(Display *display, Window parent, int x,
3013 int y, unsigned int width, unsigned int height, unsigned int
3014 border_width, int depth, unsigned int class, Visual *visual,
3015 unsigned long valuemask, XSetWindowAttributes *attributes);
3016
3017 display
3018
3019 Specifies the connection to the X server.
3020
3021 parent
3022
3023 Specifies the parent window.
3024
3025 x
3026
3027 y
3028
3029 Specify the x and y coordinates, which are the top-left outside
3030 corner of the created window's borders and are relative to the
3031 inside of the parent window's borders.
3032
3033 width
3034
3035 height
3036
3037 Specify the width and height, which are the created window's
3038 inside dimensions and do not include the created window's
3039 borders. The dimensions must be nonzero, or a BadValue error
3040 results.
3041
3042 border_width
3043
3044 Specifies the width of the created window's border in pixels.
3045
3046 depth
3047
3048 Specifies the window's depth. A depth of CopyFromParent means
3049 the depth is taken from the parent.
3050
3051 class
3052
3053 Specifies the created window's class. You can pass InputOutput,
3054 InputOnly, or CopyFromParent. A class of CopyFromParent means
3055 the class is taken from the parent.
3056
3057 visual
3058
3059 Specifies the visual type. A visual of CopyFromParent means the
3060 visual type is taken from the parent.
3061
3062 valuemask
3063
3064 Specifies which window attributes are defined in the attributes
3065 argument. This mask is the bitwise inclusive OR of the valid
3066 attribute mask bits. If valuemask is zero, the attributes are
3067 ignored and are not referenced.
3068
3069 attributes
3070
3071 Specifies the structure from which the values (as specified by
3072 the value mask) are to be taken. The value mask should have the
3073 appropriate bits set to indicate which attributes have been set
3074 in the structure.
3075
3076 The XCreateWindow function creates an unmapped subwindow for a
3077 specified parent window, returns the window ID of the created
3078 window, and causes the X server to generate a CreateNotify
3079 event. The created window is placed on top in the stacking
3080 order with respect to siblings.
3081
3082 The coordinate system has the X axis horizontal and the Y axis
3083 vertical with the origin [0, 0] at the upper-left corner.
3084 Coordinates are integral, in terms of pixels, and coincide with
3085 pixel centers. Each window and pixmap has its own coordinate
3086 system. For a window, the origin is inside the border at the
3087 inside, upper-left corner.
3088
3089 The border_width for an InputOnly window must be zero, or a
3090 BadMatch error results. For class InputOutput, the visual type
3091 and depth must be a combination supported for the screen, or a
3092 BadMatch error results. The depth need not be the same as the
3093 parent, but the parent must not be a window of class InputOnly,
3094 or a BadMatch error results. For an InputOnly window, the depth
3095 must be zero, and the visual must be one supported by the
3096 screen. If either condition is not met, a BadMatch error
3097 results. The parent window, however, may have any depth and
3098 class. If you specify any invalid window attribute for a
3099 window, a BadMatch error results.
3100
3101 The created window is not yet displayed (mapped) on the user's
3102 display. To display the window, call XMapWindow. The new window
3103 initially uses the same cursor as its parent. A new cursor can
3104 be defined for the new window by calling XDefineCursor. The
3105 window will not be visible on the screen unless it and all of
3106 its ancestors are mapped and it is not obscured by any of its
3107 ancestors.
3108
3109 XCreateWindow can generate BadAlloc, BadColor, BadCursor,
3110 BadMatch, BadPixmap, BadValue, and BadWindow errors.
3111
3112 To create an unmapped InputOutput subwindow of a given parent
3113 window, use XCreateSimpleWindow.
3114
3115 Window XCreateSimpleWindow(Display *display, Window parent, int
3116 x, int y, unsigned int width, unsigned int height, unsigned int
3117 border_width, unsigned long border, unsigned long background);
3118
3119 display
3120
3121 Specifies the connection to the X server.
3122
3123 parent
3124
3125 Specifies the parent window.
3126
3127 x
3128
3129 y
3130
3131 Specify the x and y coordinates, which are the top-left outside
3132 corner of the new window's borders and are relative to the
3133 inside of the parent window's borders.
3134
3135 width
3136
3137 height
3138
3139 Specify the width and height, which are the created window's
3140 inside dimensions and do not include the created window's
3141 borders. The dimensions must be nonzero, or a BadValue error
3142 results.
3143
3144 border_width
3145
3146 Specifies the width of the created window's border in pixels.
3147
3148 border
3149
3150 Specifies the border pixel value of the window.
3151
3152 background
3153
3154 Specifies the background pixel value of the window.
3155
3156 The XCreateSimpleWindow function creates an unmapped
3157 InputOutput subwindow for a specified parent window, returns
3158 the window ID of the created window, and causes the X server to
3159 generate a CreateNotify event. The created window is placed on
3160 top in the stacking order with respect to siblings. Any part of
3161 the window that extends outside its parent window is clipped.
3162 The border_width for an InputOnly window must be zero, or a
3163 BadMatch error results. XCreateSimpleWindow inherits its depth,
3164 class, and visual from its parent. All other window attributes,
3165 except background and border, have their default values.
3166
3167 XCreateSimpleWindow can generate BadAlloc, BadMatch, BadValue,
3168 and BadWindow errors.
3169
3170Destroying Windows
3171
3172 Xlib provides functions that you can use to destroy a window or
3173 destroy all subwindows of a window.
3174
3175 To destroy a window and all of its subwindows, use
3176 XDestroyWindow.
3177
3178 XDestroyWindow(Display *display, Window w);
3179
3180 display
3181
3182 Specifies the connection to the X server.
3183
3184 w
3185
3186 Specifies the window.
3187
3188 The XDestroyWindow function destroys the specified window as
3189 well as all of its subwindows and causes the X server to
3190 generate a DestroyNotify event for each window. The window
3191 should never be referenced again. If the window specified by
3192 the w argument is mapped, it is unmapped automatically. The
3193 ordering of the DestroyNotify events is such that for any given
3194 window being destroyed, DestroyNotify is generated on any
3195 inferiors of the window before being generated on the window
3196 itself. The ordering among siblings and across subhierarchies
3197 is not otherwise constrained. If the window you specified is a
3198 root window, no windows are destroyed. Destroying a mapped
3199 window will generate Expose events on other windows that were
3200 obscured by the window being destroyed.
3201
3202 XDestroyWindow can generate a BadWindow error.
3203
3204 To destroy all subwindows of a specified window, use
3205 XDestroySubwindows.
3206
3207 XDestroySubwindows(Display *display, Window w);
3208
3209 display
3210
3211 Specifies the connection to the X server.
3212
3213 w
3214
3215 Specifies the window.
3216
3217 The XDestroySubwindows function destroys all inferior windows
3218 of the specified window, in bottom-to-top stacking order. It
3219 causes the X server to generate a DestroyNotify event for each
3220 window. If any mapped subwindows were actually destroyed,
3221 XDestroySubwindows causes the X server to generate Expose
3222 events on the specified window. This is much more efficient
3223 than deleting many windows one at a time because much of the
3224 work need be performed only once for all of the windows, rather
3225 than for each window. The subwindows should never be referenced
3226 again.
3227
3228 XDestroySubwindows can generate a BadWindow error.
3229
3230Mapping Windows
3231
3232 A window is considered mapped if an XMapWindow call has been
3233 made on it. It may not be visible on the screen for one of the
3234 following reasons:
3235 * It is obscured by another opaque window.
3236 * One of its ancestors is not mapped.
3237 * It is entirely clipped by an ancestor.
3238
3239 Expose events are generated for the window when part or all of
3240 it becomes visible on the screen. A client receives the Expose
3241 events only if it has asked for them. Windows retain their
3242 position in the stacking order when they are unmapped.
3243
3244 A window manager may want to control the placement of
3245 subwindows. If SubstructureRedirectMask has been selected by a
3246 window manager on a parent window (usually a root window), a
3247 map request initiated by other clients on a child window is not
3248 performed, and the window manager is sent a MapRequest event.
3249 However, if the override-redirect flag on the child had been
3250 set to True (usually only on pop-up menus), the map request is
3251 performed.
3252
3253 A tiling window manager might decide to reposition and resize
3254 other clients' windows and then decide to map the window to its
3255 final location. A window manager that wants to provide
3256 decoration might reparent the child into a frame first. For
3257 further information, see sections 3.2.8 and 10.10. Only a
3258 single client at a time can select for
3259 SubstructureRedirectMask.
3260
3261 Similarly, a single client can select for ResizeRedirectMask on
3262 a parent window. Then, any attempt to resize the window by
3263 another client is suppressed, and the client receives a
3264 ResizeRequest event.
3265
3266 To map a given window, use XMapWindow.
3267
3268 XMapWindow(Display *display, Window w);
3269
3270 display
3271
3272 Specifies the connection to the X server.
3273
3274 w
3275
3276 Specifies the window.
3277
3278 The XMapWindow function maps the window and all of its
3279 subwindows that have had map requests. Mapping a window that
3280 has an unmapped ancestor does not display the window but marks
3281 it as eligible for display when the ancestor becomes mapped.
3282 Such a window is called unviewable. When all its ancestors are
3283 mapped, the window becomes viewable and will be visible on the
3284 screen if it is not obscured by another window. This function
3285 has no effect if the window is already mapped.
3286
3287 If the override-redirect of the window is False and if some
3288 other client has selected SubstructureRedirectMask on the
3289 parent window, then the X server generates a MapRequest event,
3290 and the XMapWindow function does not map the window. Otherwise,
3291 the window is mapped, and the X server generates a MapNotify
3292 event.
3293
3294 If the window becomes viewable and no earlier contents for it
3295 are remembered, the X server tiles the window with its
3296 background. If the window's background is undefined, the
3297 existing screen contents are not altered, and the X server
3298 generates zero or more Expose events. If backing-store was
3299 maintained while the window was unmapped, no Expose events are
3300 generated. If backing-store will now be maintained, a
3301 full-window exposure is always generated. Otherwise, only
3302 visible regions may be reported. Similar tiling and exposure
3303 take place for any newly viewable inferiors.
3304
3305 If the window is an InputOutput window, XMapWindow generates
3306 Expose events on each InputOutput window that it causes to be
3307 displayed. If the client maps and paints the window and if the
3308 client begins processing events, the window is painted twice.
3309 To avoid this, first ask for Expose events and then map the
3310 window, so the client processes input events as usual. The
3311 event list will include Expose for each window that has
3312 appeared on the screen. The client's normal response to an
3313 Expose event should be to repaint the window. This method
3314 usually leads to simpler programs and to proper interaction
3315 with window managers.
3316
3317 XMapWindow can generate a BadWindow error.
3318
3319 To map and raise a window, use XMapRaised.
3320
3321 XMapRaised(Display *display, Window w);
3322
3323 display
3324
3325 Specifies the connection to the X server.
3326
3327 w
3328
3329 Specifies the window.
3330
3331 The XMapRaised function essentially is similar to XMapWindow in
3332 that it maps the window and all of its subwindows that have had
3333 map requests. However, it also raises the specified window to
3334 the top of the stack. For additional information, see
3335 XMapWindow.
3336
3337 XMapRaised can generate multiple BadWindow errors.
3338
3339 To map all subwindows for a specified window, use
3340 XMapSubwindows.
3341
3342 XMapSubwindows(Display *display, Window w);
3343
3344 display
3345
3346 Specifies the connection to the X server.
3347
3348 w
3349
3350 Specifies the window.
3351
3352 The XMapSubwindows function maps all subwindows for a specified
3353 window in top-to-bottom stacking order. The X server generates
3354 Expose events on each newly displayed window. This may be much
3355 more efficient than mapping many windows one at a time because
3356 the server needs to perform much of the work only once, for all
3357 of the windows, rather than for each window.
3358
3359 XMapSubwindows can generate a BadWindow error.
3360
3361Unmapping Windows
3362
3363 Xlib provides functions that you can use to unmap a window or
3364 all subwindows.
3365
3366 To unmap a window, use XUnmapWindow.
3367
3368 XUnmapWindow(Display *display, Window w);
3369
3370 display
3371
3372 Specifies the connection to the X server.
3373
3374 w
3375
3376 Specifies the window.
3377
3378 The XUnmapWindow function unmaps the specified window and
3379 causes the X server to generate an UnmapNotify event. If the
3380 specified window is already unmapped, XUnmapWindow has no
3381 effect. Normal exposure processing on formerly obscured windows
3382 is performed. Any child window will no longer be visible until
3383 another map call is made on the parent. In other words, the
3384 subwindows are still mapped but are not visible until the
3385 parent is mapped. Unmapping a window will generate Expose
3386 events on windows that were formerly obscured by it.
3387
3388 XUnmapWindow can generate a BadWindow error.
3389
3390 To unmap all subwindows for a specified window, use
3391 XUnmapSubwindows.
3392
3393 XUnmapSubwindows(Display *display, Window w);
3394
3395 display
3396
3397 Specifies the connection to the X server.
3398
3399 w
3400
3401 Specifies the window.
3402
3403 The XUnmapSubwindows function unmaps all subwindows for the
3404 specified window in bottom-to-top stacking order. It causes the
3405 X server to generate an UnmapNotify event on each subwindow and
3406 Expose events on formerly obscured windows. Using this function
3407 is much more efficient than unmapping multiple windows one at a
3408 time because the server needs to perform much of the work only
3409 once, for all of the windows, rather than for each window.
3410
3411 XUnmapSubwindows can generate a BadWindow error.
3412
3413Configuring Windows
3414
3415 Xlib provides functions that you can use to move a window,
3416 resize a window, move and resize a window, or change a window's
3417 border width. To change one of these parameters, set the
3418 appropriate member of the XWindowChanges structure and OR in
3419 the corresponding value mask in subsequent calls to
3420 XConfigureWindow. The symbols for the value mask bits and the
3421 XWindowChanges structure are:
3422
3423/* Configure window value mask bits */
3424#define CWX (1<<0)
3425#define CWY (1<<1)
3426#define CWWidth (1<<2)
3427#define CWHeight (1<<3)
3428#define CWBorderWidth (1<<4)
3429#define CWSibling (1<<5)
3430#define CWStackMode (1<<6)
3431
3432/* Values */
3433
3434typedef struct {
3435 int x, y;
3436 int width, height;
3437 int border_width;
3438 Window sibling;
3439 int stack_mode;
3440} XWindowChanges;
3441
3442 The x and y members are used to set the window's x and y
3443 coordinates, which are relative to the parent's origin and
3444 indicate the position of the upper-left outer corner of the
3445 window. The width and height members are used to set the inside
3446 size of the window, not including the border, and must be
3447 nonzero, or a BadValue error results. Attempts to configure a
3448 root window have no effect.
3449
3450 The border_width member is used to set the width of the border
3451 in pixels. Note that setting just the border width leaves the
3452 outer-left corner of the window in a fixed position but moves
3453 the absolute position of the window's origin. If you attempt to
3454 set the border-width attribute of an InputOnly window nonzero,
3455 a BadMatch error results.
3456
3457 The sibling member is used to set the sibling window for
3458 stacking operations. The stack_mode member is used to set how
3459 the window is to be restacked and can be set to Above, Below,
3460 TopIf, BottomIf, or Opposite.
3461
3462 If the override-redirect flag of the window is False and if
3463 some other client has selected SubstructureRedirectMask on the
3464 parent, the X server generates a ConfigureRequest event, and no
3465 further processing is performed. Otherwise, if some other
3466 client has selected ResizeRedirectMask on the window and the
3467 inside width or height of the window is being changed, a
3468 ResizeRequest event is generated, and the current inside width
3469 and height are used instead. Note that the override-redirect
3470 flag of the window has no effect on ResizeRedirectMask and that
3471 SubstructureRedirectMask on the parent has precedence over
3472 ResizeRedirectMask on the window.
3473
3474 When the geometry of the window is changed as specified, the
3475 window is restacked among siblings, and a ConfigureNotify event
3476 is generated if the state of the window actually changes.
3477 GravityNotify events are generated after ConfigureNotify
3478 events. If the inside width or height of the window has
3479 actually changed, children of the window are affected as
3480 specified.
3481
3482 If a window's size actually changes, the window's subwindows
3483 move according to their window gravity. Depending on the
3484 window's bit gravity, the contents of the window also may be
3485 moved (see section 3.2.3).
3486
3487 If regions of the window were obscured but now are not,
3488 exposure processing is performed on these formerly obscured
3489 windows, including the window itself and its inferiors. As a
3490 result of increasing the width or height, exposure processing
3491 is also performed on any new regions of the window and any
3492 regions where window contents are lost.
3493
3494 The restack check (specifically, the computation for BottomIf,
3495 TopIf, and Opposite) is performed with respect to the window's
3496 final size and position (as controlled by the other arguments
3497 of the request), not its initial position. If a sibling is
3498 specified without a stack_mode, a BadMatch error results.
3499
3500 If a sibling and a stack_mode are specified, the window is
3501 restacked as follows:
3502 Above The window is placed just above the sibling.
3503 Below The window is placed just below the sibling.
3504 TopIf If the sibling occludes the window, the window is placed
3505 at the top of the stack.
3506 BottomIf If the window occludes the sibling, the window is
3507 placed at the bottom of the stack.
3508 Opposite If the sibling occludes the window, the window is
3509 placed at the top of the stack. If the window occludes the
3510 sibling, the window is placed at the bottom of the stack.
3511
3512 If a stack_mode is specified but no sibling is specified, the
3513 window is restacked as follows:
3514 Above The window is placed at the top of the stack.
3515 Below The window is placed at the bottom of the stack.
3516 TopIf If any sibling occludes the window, the window is placed
3517 at the top of the stack.
3518 BottomIf If the window occludes any sibling, the window is
3519 placed at the bottom of the stack.
3520 Opposite If any sibling occludes the window, the window is
3521 placed at the top of the stack. If the window occludes any
3522 sibling, the window is placed at the bottom of the stack.
3523
3524 Attempts to configure a root window have no effect.
3525
3526 To configure a window's size, location, stacking, or border,
3527 use XConfigureWindow.
3528
3529 XConfigureWindow(Display *display, Window w, unsigned int
3530 value_mask, XWindowChanges *values);
3531
3532 display
3533
3534 Specifies the connection to the X server.
3535
3536 w
3537
3538 Specifies the window to be reconfigured.
3539
3540 value_mask
3541
3542 Specifies which values are to be set using information in the
3543 values structure. This mask is the bitwise inclusive OR of the
3544 valid configure window values bits.
3545
3546 values
3547
3548 Specifies the XWindowChanges structure.
3549
3550 The XConfigureWindow function uses the values specified in the
3551 XWindowChanges structure to reconfigure a window's size,
3552 position, border, and stacking order. Values not specified are
3553 taken from the existing geometry of the window.
3554
3555 If a sibling is specified without a stack_mode or if the window
3556 is not actually a sibling, a BadMatch error results. Note that
3557 the computations for BottomIf, TopIf, and Opposite are
3558 performed with respect to the window's final geometry (as
3559 controlled by the other arguments passed to XConfigureWindow),
3560 not its initial geometry. Any backing store contents of the
3561 window, its inferiors, and other newly visible windows are
3562 either discarded or changed to reflect the current screen
3563 contents (depending on the implementation).
3564
3565 XConfigureWindow can generate BadMatch, BadValue, and BadWindow
3566 errors.
3567
3568 To move a window without changing its size, use XMoveWindow.
3569
3570 XMoveWindow(Display *display, Window w, int x, int y);
3571
3572 display
3573
3574 Specifies the connection to the X server.
3575
3576 w
3577
3578 Specifies the window to be moved.
3579
3580 x
3581
3582 y
3583
3584 Specify the x and y coordinates, which define the new location
3585 of the top-left pixel of the window's border or the window
3586 itself if it has no border.
3587
3588 The XMoveWindow function moves the specified window to the
3589 specified x and y coordinates, but it does not change the
3590 window's size, raise the window, or change the mapping state of
3591 the window. Moving a mapped window may or may not lose the
3592 window's contents depending on if the window is obscured by
3593 nonchildren and if no backing store exists. If the contents of
3594 the window are lost, the X server generates Expose events.
3595 Moving a mapped window generates Expose events on any formerly
3596 obscured windows.
3597
3598 If the override-redirect flag of the window is False and some
3599 other client has selected SubstructureRedirectMask on the
3600 parent, the X server generates a ConfigureRequest event, and no
3601 further processing is performed. Otherwise, the window is
3602 moved.
3603
3604 XMoveWindow can generate a BadWindow error.
3605
3606 To change a window's size without changing the upper-left
3607 coordinate, use XResizeWindow.
3608
3609 XResizeWindow(Display *display, Window w, unsigned int width,
3610 unsigned int height);
3611
3612 display
3613
3614 Specifies the connection to the X server.
3615
3616 w
3617
3618 Specifies the window.
3619
3620 width
3621
3622 height
3623
3624 Specify the width and height, which are the interior dimensions
3625 of the window after the call completes.
3626
3627 The XResizeWindow function changes the inside dimensions of the
3628 specified window, not including its borders. This function does
3629 not change the window's upper-left coordinate or the origin and
3630 does not restack the window. Changing the size of a mapped
3631 window may lose its contents and generate Expose events. If a
3632 mapped window is made smaller, changing its size generates
3633 Expose events on windows that the mapped window formerly
3634 obscured.
3635
3636 If the override-redirect flag of the window is False and some
3637 other client has selected SubstructureRedirectMask on the
3638 parent, the X server generates a ConfigureRequest event, and no
3639 further processing is performed. If either width or height is
3640 zero, a BadValue error results.
3641
3642 XResizeWindow can generate BadValue and BadWindow errors.
3643
3644 To change the size and location of a window, use
3645 XMoveResizeWindow.
3646
3647 XMoveResizeWindow(Display *display, Window w, int x, int y,
3648 unsigned int width, unsigned int height);
3649
3650 display
3651
3652 Specifies the connection to the X server.
3653
3654 w
3655
3656 Specifies the window to be reconfigured.
3657
3658 x
3659
3660 y
3661
3662 Specify the x and y coordinates, which define the new position
3663 of the window relative to its parent.
3664
3665 width
3666
3667 height
3668
3669 Specify the width and height, which define the interior size of
3670 the window.
3671
3672 The XMoveResizeWindow function changes the size and location of
3673 the specified window without raising it. Moving and resizing a
3674 mapped window may generate an Expose event on the window.
3675 Depending on the new size and location parameters, moving and
3676 resizing a window may generate Expose events on windows that
3677 the window formerly obscured.
3678
3679 If the override-redirect flag of the window is False and some
3680 other client has selected SubstructureRedirectMask on the
3681 parent, the X server generates a ConfigureRequest event, and no
3682 further processing is performed. Otherwise, the window size and
3683 location are changed.
3684
3685 XMoveResizeWindow can generate BadValue and BadWindow errors.
3686
3687 To change the border width of a given window, use
3688 XSetWindowBorderWidth.
3689
3690 XSetWindowBorderWidth(Display *display, Window w, unsigned int
3691 width);
3692
3693 display
3694
3695 Specifies the connection to the X server.
3696
3697 w
3698
3699 Specifies the window.
3700
3701 width
3702
3703 Specifies the width of the window border.
3704
3705 The XSetWindowBorderWidth function sets the specified window's
3706 border width to the specified width.
3707
3708 XSetWindowBorderWidth can generate a BadWindow error.
3709
3710Changing Window Stacking Order
3711
3712 Xlib provides functions that you can use to raise, lower,
3713 circulate, or restack windows.
3714
3715 To raise a window so that no sibling window obscures it, use
3716 XRaiseWindow.
3717
3718 XRaiseWindow(Display *display, Window w);
3719
3720 display
3721
3722 Specifies the connection to the X server.
3723
3724 w
3725
3726 Specifies the window.
3727
3728 The XRaiseWindow function raises the specified window to the
3729 top of the stack so that no sibling window obscures it. If the
3730 windows are regarded as overlapping sheets of paper stacked on
3731 a desk, then raising a window is analogous to moving the sheet
3732 to the top of the stack but leaving its x and y location on the
3733 desk constant. Raising a mapped window may generate Expose
3734 events for the window and any mapped subwindows that were
3735 formerly obscured.
3736
3737 If the override-redirect attribute of the window is False and
3738 some other client has selected SubstructureRedirectMask on the
3739 parent, the X server generates a ConfigureRequest event, and no
3740 processing is performed. Otherwise, the window is raised.
3741
3742 XRaiseWindow can generate a BadWindow error.
3743
3744 To lower a window so that it does not obscure any sibling
3745 windows, use XLowerWindow.
3746
3747 XLowerWindow(Display *display, Window w);
3748
3749 display
3750
3751 Specifies the connection to the X server.
3752
3753 w
3754
3755 Specifies the window.
3756
3757 The XLowerWindow function lowers the specified window to the
3758 bottom of the stack so that it does not obscure any sibling
3759 windows. If the windows are regarded as overlapping sheets of
3760 paper stacked on a desk, then lowering a window is analogous to
3761 moving the sheet to the bottom of the stack but leaving its x
3762 and y location on the desk constant. Lowering a mapped window
3763 will generate Expose events on any windows it formerly
3764 obscured.
3765
3766 If the override-redirect attribute of the window is False and
3767 some other client has selected SubstructureRedirectMask on the
3768 parent, the X server generates a ConfigureRequest event, and no
3769 processing is performed. Otherwise, the window is lowered to
3770 the bottom of the stack.
3771
3772 XLowerWindow can generate a BadWindow error.
3773
3774 To circulate a subwindow up or down, use XCirculateSubwindows.
3775
3776 XCirculateSubwindows(Display *display, Window w, int
3777 direction);
3778
3779 display
3780
3781 Specifies the connection to the X server.
3782
3783 w
3784
3785 Specifies the window.
3786
3787 direction
3788
3789 Specifies the direction (up or down) that you want to circulate
3790 the window. You can pass RaiseLowest or LowerHighest.
3791
3792 The XCirculateSubwindows function circulates children of the
3793 specified window in the specified direction. If you specify
3794 RaiseLowest, XCirculateSubwindows raises the lowest mapped
3795 child (if any) that is occluded by another child to the top of
3796 the stack. If you specify LowerHighest, XCirculateSubwindows
3797 lowers the highest mapped child (if any) that occludes another
3798 child to the bottom of the stack. Exposure processing is then
3799 performed on formerly obscured windows. If some other client
3800 has selected SubstructureRedirectMask on the window, the X
3801 server generates a CirculateRequest event, and no further
3802 processing is performed. If a child is actually restacked, the
3803 X server generates a CirculateNotify event.
3804
3805 XCirculateSubwindows can generate BadValue and BadWindow
3806 errors.
3807
3808 To raise the lowest mapped child of a window that is partially
3809 or completely occluded by another child, use
3810 XCirculateSubwindowsUp.
3811
3812 XCirculateSubwindowsUp(Display *display, Window w);
3813
3814 display
3815
3816 Specifies the connection to the X server.
3817
3818 w
3819
3820 Specifies the window.
3821
3822 The XCirculateSubwindowsUp function raises the lowest mapped
3823 child of the specified window that is partially or completely
3824 occluded by another child. Completely unobscured children are
3825 not affected. This is a convenience function equivalent to
3826 XCirculateSubwindows with RaiseLowest specified.
3827
3828 XCirculateSubwindowsUp can generate a BadWindow error.
3829
3830 To lower the highest mapped child of a window that partially or
3831 completely occludes another child, use
3832 XCirculateSubwindowsDown.
3833
3834 XCirculateSubwindowsDown(Display *display, Window w);
3835
3836 display
3837
3838 Specifies the connection to the X server.
3839
3840 w
3841
3842 Specifies the window.
3843
3844 The XCirculateSubwindowsDown function lowers the highest mapped
3845 child of the specified window that partially or completely
3846 occludes another child. Completely unobscured children are not
3847 affected. This is a convenience function equivalent to
3848 XCirculateSubwindows with LowerHighest specified.
3849
3850 XCirculateSubwindowsDown can generate a BadWindow error.
3851
3852 To restack a set of windows from top to bottom, use
3853 XRestackWindows.
3854
3855 XRestackWindows(Display *display, Window windows[], int
3856 nwindows);
3857
3858 display
3859
3860 Specifies the connection to the X server.
3861
3862 windows
3863
3864 Specifies an array containing the windows to be restacked.
3865
3866 nwindows
3867
3868 Specifies the number of windows to be restacked.
3869
3870 The XRestackWindows function restacks the windows in the order
3871 specified, from top to bottom. The stacking order of the first
3872 window in the windows array is unaffected, but the other
3873 windows in the array are stacked underneath the first window,
3874 in the order of the array. The stacking order of the other
3875 windows is not affected. For each window in the window array
3876 that is not a child of the specified window, a BadMatch error
3877 results.
3878
3879 If the override-redirect attribute of a window is False and
3880 some other client has selected SubstructureRedirectMask on the
3881 parent, the X server generates ConfigureRequest events for each
3882 window whose override-redirect flag is not set, and no further
3883 processing is performed. Otherwise, the windows will be
3884 restacked in top-to-bottom order.
3885
3886 XRestackWindows can generate a BadWindow error.
3887
3888Changing Window Attributes
3889
3890 Xlib provides functions that you can use to set window
3891 attributes. XChangeWindowAttributes is the more general
3892 function that allows you to set one or more window attributes
3893 provided by the XSetWindowAttributes structure. The other
3894 functions described in this section allow you to set one
3895 specific window attribute, such as a window's background.
3896
3897 To change one or more attributes for a given window, use
3898 XChangeWindowAttributes.
3899
3900 XChangeWindowAttributes(Display *display, Window w, unsigned
3901 long valuemask, XSetWindowAttributes *attributes);
3902
3903 display
3904
3905 Specifies the connection to the X server.
3906
3907 w
3908
3909 Specifies the window.
3910
3911 valuemask
3912
3913 Specifies which window attributes are defined in the attributes
3914 argument. This mask is the bitwise inclusive OR of the valid
3915 attribute mask bits. If valuemask is zero, the attributes are
3916 ignored and are not referenced. The values and restrictions are
3917 the same as for XCreateWindow.
3918
3919 attributes
3920
3921 Specifies the structure from which the values (as specified by
3922 the value mask) are to be taken. The value mask should have the
3923 appropriate bits set to indicate which attributes have been set
3924 in the structure (see section 3.2).
3925
3926 Depending on the valuemask, the XChangeWindowAttributes
3927 function uses the window attributes in the XSetWindowAttributes
3928 structure to change the specified window attributes. Changing
3929 the background does not cause the window contents to be
3930 changed. To repaint the window and its background, use
3931 XClearWindow. Setting the border or changing the background
3932 such that the border tile origin changes causes the border to
3933 be repainted. Changing the background of a root window to None
3934 or ParentRelative restores the default background pixmap.
3935 Changing the border of a root window to CopyFromParent restores
3936 the default border pixmap. Changing the win-gravity does not
3937 affect the current position of the window. Changing the
3938 backing-store of an obscured window to WhenMapped or Always, or
3939 changing the backing-planes, backing-pixel, or save-under of a
3940 mapped window may have no immediate effect. Changing the
3941 colormap of a window (that is, defining a new map, not changing
3942 the contents of the existing map) generates a ColormapNotify
3943 event. Changing the colormap of a visible window may have no
3944 immediate effect on the screen because the map may not be
3945 installed (see XInstallColormap). Changing the cursor of a root
3946 window to None restores the default cursor. Whenever possible,
3947 you are encouraged to share colormaps.
3948
3949 Multiple clients can select input on the same window. Their
3950 event masks are maintained separately. When an event is
3951 generated, it is reported to all interested clients. However,
3952 only one client at a time can select for
3953 SubstructureRedirectMask, ResizeRedirectMask, and
3954 ButtonPressMask. If a client attempts to select any of these
3955 event masks and some other client has already selected one, a
3956 BadAccess error results. There is only one
3957 do-not-propagate-mask for a window, not one per client.
3958
3959 XChangeWindowAttributes can generate BadAccess, BadColor,
3960 BadCursor, BadMatch, BadPixmap, BadValue, and BadWindow errors.
3961
3962 To set the background of a window to a given pixel, use
3963 XSetWindowBackground.
3964
3965 XSetWindowBackground(Display *display, Window w, unsigned long
3966 background_pixel);
3967
3968 display
3969
3970 Specifies the connection to the X server.
3971
3972 w
3973
3974 Specifies the window.
3975
3976 background_pixel
3977
3978 Specifies the pixel that is to be used for the background.
3979
3980 The XSetWindowBackground function sets the background of the
3981 window to the specified pixel value. Changing the background
3982 does not cause the window contents to be changed.
3983 XSetWindowBackground uses a pixmap of undefined size filled
3984 with the pixel value you passed. If you try to change the
3985 background of an InputOnly window, a BadMatch error results.
3986
3987 XSetWindowBackground can generate BadMatch and BadWindow
3988 errors.
3989
3990 To set the background of a window to a given pixmap, use
3991 XSetWindowBackgroundPixmap.
3992
3993 XSetWindowBackgroundPixmap(Display *display, Window w, Pixmap
3994 background_pixmap);
3995
3996 display
3997
3998 Specifies the connection to the X server.
3999
4000 w
4001
4002 Specifies the window.
4003
4004 background_pixmap
4005
4006 Specifies the background pixmap, ParentRelative, or None.
4007
4008 The XSetWindowBackgroundPixmap function sets the background
4009 pixmap of the window to the specified pixmap. The background
4010 pixmap can immediately be freed if no further explicit
4011 references to it are to be made. If ParentRelative is
4012 specified, the background pixmap of the window's parent is
4013 used, or on the root window, the default background is
4014 restored. If you try to change the background of an InputOnly
4015 window, a BadMatch error results. If the background is set to
4016 None, the window has no defined background.
4017
4018 XSetWindowBackgroundPixmap can generate BadMatch, BadPixmap,
4019 and BadWindow errors. XSetWindowBackground and
4020 XSetWindowBackgroundPixmap do not change the current contents
4021 of the window.
4022
4023 To change and repaint a window's border to a given pixel, use
4024 XSetWindowBorder.
4025
4026 XSetWindowBorder(Display *display, Window w, unsigned long
4027 border_pixel);
4028
4029 display
4030
4031 Specifies the connection to the X server.
4032
4033 w
4034
4035 Specifies the window.
4036
4037 border_pixel
4038
4039 Specifies the entry in the colormap.
4040
4041 The XSetWindowBorder function sets the border of the window to
4042 the pixel value you specify. If you attempt to perform this on
4043 an InputOnly window, a BadMatch error results.
4044
4045 XSetWindowBorder can generate BadMatch and BadWindow errors.
4046
4047 To change and repaint the border tile of a given window, use
4048 XSetWindowBorderPixmap.
4049
4050 XSetWindowBorderPixmap(Display *display, Window w, Pixmap
4051 border_pixmap);
4052
4053 display
4054
4055 Specifies the connection to the X server.
4056
4057 w
4058
4059 Specifies the window.
4060
4061 border_pixmap
4062
4063 Specifies the border pixmap or CopyFromParent.
4064
4065 The XSetWindowBorderPixmap function sets the border pixmap of
4066 the window to the pixmap you specify. The border pixmap can be
4067 freed immediately if no further explicit references to it are
4068 to be made. If you specify CopyFromParent, a copy of the parent
4069 window's border pixmap is used. If you attempt to perform this
4070 on an InputOnly window, a BadMatch error results.
4071
4072 XSetWindowBorderPixmap can generate BadMatch, BadPixmap, and
4073 BadWindow errors.
4074
4075 To set the colormap of a given window, use XSetWindowColormap.
4076
4077 XSetWindowColormap(Display *display, Window w, Colormap
4078 colormap);
4079
4080 display
4081
4082 Specifies the connection to the X server.
4083
4084 w
4085
4086 Specifies the window.
4087
4088 colormap
4089
4090 Specifies the colormap.
4091
4092 The XSetWindowColormap function sets the specified colormap of
4093 the specified window. The colormap must have the same visual
4094 type as the window, or a BadMatch error results.
4095
4096 XSetWindowColormap can generate BadColor, BadMatch, and
4097 BadWindow errors.
4098
4099 To define which cursor will be used in a window, use
4100 XDefineCursor.
4101
4102 XDefineCursor(Display *display, Window w, Cursor cursor);
4103
4104 display
4105
4106 Specifies the connection to the X server.
4107
4108 w
4109
4110 Specifies the window.
4111
4112 cursor
4113
4114 Specifies the cursor that is to be displayed or None.
4115
4116 If a cursor is set, it will be used when the pointer is in the
4117 window. If the cursor is None, it is equivalent to
4118 XUndefineCursor.
4119
4120 XDefineCursor can generate BadCursor and BadWindow errors.
4121
4122 To undefine the cursor in a given window, use XUndefineCursor.
4123
4124 XUndefineCursor(Display *display, Window w);
4125
4126 display
4127
4128 Specifies the connection to the X server.
4129
4130 w
4131
4132 Specifies the window.
4133
4134 The XUndefineCursor function undoes the effect of a previous
4135 XDefineCursor for this window. When the pointer is in the
4136 window, the parent's cursor will now be used. On the root
4137 window, the default cursor is restored.
4138
4139 XUndefineCursor can generate a BadWindow error.
4140
4141Chapter 4. Window Information Functions
4142
4143 Table of Contents
4144
4145 Obtaining Window Information
4146 Translating Screen Coordinates
4147 Properties and Atoms
4148 Obtaining and Changing Window Properties
4149 Selections
4150
4151 After you connect the display to the X server and create a
4152 window, you can use the Xlib window information functions to:
4153 * Obtain information about a window
4154 * Translate screen coordinates
4155 * Manipulate property lists
4156 * Obtain and change window properties
4157 * Manipulate selections
4158
4159Obtaining Window Information
4160
4161 Xlib provides functions that you can use to obtain information
4162 about the window tree, the window's current attributes, the
4163 window's current geometry, or the current pointer coordinates.
4164 Because they are most frequently used by window managers, these
4165 functions all return a status to indicate whether the window
4166 still exists.
4167
4168 To obtain the parent, a list of children, and number of
4169 children for a given window, use XQueryTree.
4170
4171 Status XQueryTree(Display *display, Window w, Window
4172 *root_return, Window *parent_return, Window **children_return,
4173 unsigned int *nchildren_return);
4174
4175 display
4176
4177 Specifies the connection to the X server.
4178
4179 w
4180
4181 Specifies the window whose list of children, root, parent, and
4182 number of children you want to obtain.
4183
4184 root_return
4185
4186 Returns the root window.
4187
4188 parent_return
4189
4190 Returns the parent window.
4191
4192 children_return
4193
4194 Returns the list of children.
4195
4196 nchildren_return
4197
4198 Returns the number of children.
4199
4200 The XQueryTree function returns the root ID, the parent window
4201 ID, a pointer to the list of children windows (NULL when there
4202 are no children), and the number of children in the list for
4203 the specified window. The children are listed in current
4204 stacking order, from bottom-most (first) to top-most (last).
4205 XQueryTree returns zero if it fails and nonzero if it succeeds.
4206 To free a non-NULL children list when it is no longer needed,
4207 use XFree.
4208
4209 XQueryTree can generate a BadWindow error.
4210
4211 To obtain the current attributes of a given window, use
4212 XGetWindowAttributes.
4213
4214 Status XGetWindowAttributes(Display *display, Window w,
4215 XWindowAttributes *window_attributes_return);
4216
4217 display
4218
4219 Specifies the connection to the X server.
4220
4221 w
4222
4223 Specifies the window whose current attributes you want to
4224 obtain.
4225
4226 window_attributes_return
4227
4228 Returns the specified window's attributes in the
4229 XWindowAttributes structure.
4230
4231 The XGetWindowAttributes function returns the current
4232 attributes for the specified window to an XWindowAttributes
4233 structure.
4234
4235
4236
4237typedef struct {
4238 int x, y; /* location of window */
4239 int width, height; /* width and height of window */
4240 int border_width; /* border width of window */
4241 int depth; /* depth of window */
4242 Visual *visual; /* the associated visual structure */
4243 Window root; /* root of screen containing window *
4244/
4245 int class; /* InputOutput, InputOnly*/
4246 int bit_gravity; /* one of the bit gravity values */
4247 int win_gravity; /* one of the window gravity values *
4248/
4249 int backing_store; /* NotUseful, WhenMapped, Always */
4250 unsigned long backing_planes; /* planes to be preserved if possible
4251 */
4252 unsigned long backing_pixel; /* value to be used when restoring pl
4253anes */
4254 Bool save_under; /* boolean, should bits under be save
4255d? */
4256 Colormap colormap; /* color map to be associated with wi
4257ndow */
4258 Bool map_installed; /* boolean, is color map currently in
4259stalled*/
4260 int map_state; /* IsUnmapped, IsUnviewable, IsViewab
4261le */
4262 long all_event_masks; /* set of events all people have inte
4263rest in*/
4264 long your_event_mask; /* my event mask */
4265 long do_not_propagate_mask; /* set of events that should not prop
4266agate */
4267 Bool override_redirect; /* boolean value for override-redirec
4268t */
4269 Screen *screen; /* back pointer to correct screen */
4270} XWindowAttributes;
4271
4272 The x and y members are set to the upper-left outer corner
4273 relative to the parent window's origin. The width and height
4274 members are set to the inside size of the window, not including
4275 the border. The border_width member is set to the window's
4276 border width in pixels. The depth member is set to the depth of
4277 the window (that is, bits per pixel for the object). The visual
4278 member is a pointer to the screen's associated Visual
4279 structure. The root member is set to the root window of the
4280 screen containing the window. The class member is set to the
4281 window's class and can be either InputOutput or InputOnly.
4282
4283 The bit_gravity member is set to the window's bit gravity and
4284 can be one of the following:
4285 ForgetGravity EastGravity
4286 NorthWestGravity SouthWestGravity
4287 NorthGravity SouthGravity
4288 NorthEastGravity SouthEastGravity
4289 WestGravity StaticGravity
4290
4291 The win_gravity member is set to the window's window gravity
4292 and can be one of the following:
4293 UnmapGravity SouthWestGravity
4294 NorthWestGravity SouthGravity
4295 NorthGravity SouthEastGravity
4296 NorthEastGravity StaticGravity
4297 WestGravity CenterGravity
4298 EastGravity
4299
4300 For additional information on gravity, see section 3.2.3.
4301
4302 The backing_store member is set to indicate how the X server
4303 should maintain the contents of a window and can be WhenMapped,
4304 Always, or NotUseful. The backing_planes member is set to
4305 indicate (with bits set to 1) which bit planes of the window
4306 hold dynamic data that must be preserved in backing_stores and
4307 during save_unders. The backing_pixel member is set to indicate
4308 what values to use for planes not set in backing_planes.
4309
4310 The save_under member is set to True or False. The colormap
4311 member is set to the colormap for the specified window and can
4312 be a colormap ID or None. The map_installed member is set to
4313 indicate whether the colormap is currently installed and can be
4314 True or False. The map_state member is set to indicate the
4315 state of the window and can be IsUnmapped, IsUnviewable, or
4316 IsViewable. IsUnviewable is used if the window is mapped but
4317 some ancestor is unmapped.
4318
4319 The all_event_masks member is set to the bitwise inclusive OR
4320 of all event masks selected on the window by all clients. The
4321 your_event_mask member is set to the bitwise inclusive OR of
4322 all event masks selected by the querying client. The
4323 do_not_propagate_mask member is set to the bitwise inclusive OR
4324 of the set of events that should not propagate.
4325
4326 The override_redirect member is set to indicate whether this
4327 window overrides structure control facilities and can be True
4328 or False. Window manager clients should ignore the window if
4329 this member is True.
4330
4331 The screen member is set to a screen pointer that gives you a
4332 back pointer to the correct screen. This makes it easier to
4333 obtain the screen information without having to loop over the
4334 root window fields to see which field matches.
4335
4336 XGetWindowAttributes can generate BadDrawable and BadWindow
4337 errors.
4338
4339 To obtain the current geometry of a given drawable, use
4340 XGetGeometry.
4341
4342 Status XGetGeometry(Display *display, Drawable d, Window
4343 *root_return, int *x_return, int *y_return, unsigned int
4344 *width_return, unsigned int *height_return, unsigned int
4345 *border_width_return, unsigned int *depth_return);
4346
4347 display
4348
4349 Specifies the connection to the X server.
4350
4351 d
4352
4353 Specifies the drawable, which can be a window or a pixmap.
4354
4355 root_return
4356
4357 Returns the root window.
4358
4359 x_return
4360
4361 y_return
4362
4363 Return the x and y coordinates that define the location of the
4364 drawable. For a window, these coordinates specify the
4365 upper-left outer corner relative to its parent's origin. For
4366 pixmaps, these coordinates are always zero.
4367
4368 width_return
4369
4370 height_return
4371
4372 Return the drawable's dimensions (width and height). For a
4373 window, these dimensions specify the inside size, not including
4374 the border.
4375
4376 border_width_return
4377
4378 Returns the border width in pixels. If the drawable is a
4379 pixmap, it returns zero.
4380
4381 depth_return
4382
4383 Returns the depth of the drawable (bits per pixel for the
4384 object).
4385
4386 The XGetGeometry function returns the root window and the
4387 current geometry of the drawable. The geometry of the drawable
4388 includes the x and y coordinates, width and height, border
4389 width, and depth. These are described in the argument list. It
4390 is legal to pass to this function a window whose class is
4391 InputOnly.
4392
4393 XGetGeometry can generate a BadDrawable error.
4394
4395Translating Screen Coordinates
4396
4397 Applications sometimes need to perform a coordinate
4398 transformation from the coordinate space of one window to
4399 another window or need to determine which window the pointing
4400 device is in. XTranslateCoordinates and XQueryPointer fulfill
4401 these needs (and avoid any race conditions) by asking the X
4402 server to perform these operations.
4403
4404 To translate a coordinate in one window to the coordinate space
4405 of another window, use XTranslateCoordinates.
4406
4407 Bool XTranslateCoordinates(Display *display, Window src_w,
4408 Window dest_w, int src_x, int src_y, int *dest_x_return, int
4409 *dest_y_return, Window *child_return);
4410
4411 display
4412
4413 Specifies the connection to the X server.
4414
4415 src_w
4416
4417 Specifies the source window.
4418
4419 dest_w
4420
4421 Specifies the destination window.
4422
4423 src_x
4424
4425 src_y
4426
4427 Specify the x and y coordinates within the source window.
4428
4429 dest_x_return
4430
4431 dest_y_return
4432
4433 Return the x and y coordinates within the destination window.
4434
4435 child_return
4436
4437 Returns the child if the coordinates are contained in a mapped
4438 child of the destination window.
4439
4440 If XTranslateCoordinates returns True, it takes the src_x and
4441 src_y coordinates relative to the source window's origin and
4442 returns these coordinates to dest_x_return and dest_y_return
4443 relative to the destination window's origin. If
4444 XTranslateCoordinates returns False, src_w and dest_w are on
4445 different screens, and dest_x_return and dest_y_return are
4446 zero. If the coordinates are contained in a mapped child of
4447 dest_w, that child is returned to child_return. Otherwise,
4448 child_return is set to None.
4449
4450 XTranslateCoordinates can generate a BadWindow error.
4451
4452 To obtain the screen coordinates of the pointer or to determine
4453 the pointer coordinates relative to a specified window, use
4454 XQueryPointer.
4455
4456 Bool XQueryPointer(Display *display, Window w, Window
4457 *root_return, Window *child_return, int *root_x_return, int
4458 *root_y_return, int *win_x_return, int *win_y_return, unsigned
4459 int *mask_return);
4460
4461 display
4462
4463 Specifies the connection to the X server.
4464
4465 w
4466
4467 Specifies the window.
4468
4469 root_return
4470
4471 Returns the root window that the pointer is in.
4472
4473 child_return
4474
4475 Returns the child window that the pointer is located in, if
4476 any.
4477
4478 root_x_return
4479
4480 root_y_return
4481
4482 Return the pointer coordinates relative to the root window's
4483 origin.
4484
4485 win_x_return
4486
4487 win_y_return
4488
4489 Return the pointer coordinates relative to the specified
4490 window.
4491
4492 mask_return
4493
4494 Returns the current state of the modifier keys and pointer
4495 buttons.
4496
4497 The XQueryPointer function returns the root window the pointer
4498 is logically on and the pointer coordinates relative to the
4499 root window's origin. If XQueryPointer returns False, the
4500 pointer is not on the same screen as the specified window, and
4501 XQueryPointer returns None to child_return and zero to
4502 win_x_return and win_y_return. If XQueryPointer returns True,
4503 the pointer coordinates returned to win_x_return and
4504 win_y_return are relative to the origin of the specified
4505 window. In this case, XQueryPointer returns the child that
4506 contains the pointer, if any, or else None to child_return.
4507
4508 XQueryPointer returns the current logical state of the keyboard
4509 buttons and the modifier keys in mask_return. It sets
4510 mask_return to the bitwise inclusive OR of one or more of the
4511 button or modifier key bitmasks to match the current state of
4512 the mouse buttons and the modifier keys.
4513
4514 Note that the logical state of a device (as seen through Xlib)
4515 may lag the physical state if device event processing is frozen
4516 (see section 12.1).
4517
4518 XQueryPointer can generate a BadWindow error.
4519
4520Properties and Atoms
4521
4522 A property is a collection of named, typed data. The window
4523 system has a set of predefined properties (for example, the
4524 name of a window, size hints, and so on), and users can define
4525 any other arbitrary information and associate it with windows.
4526 Each property has a name, which is an ISO Latin-1 string. For
4527 each named property, a unique identifier (atom) is associated
4528 with it. A property also has a type, for example, string or
4529 integer. These types are also indicated using atoms, so
4530 arbitrary new types can be defined. Data of only one type may
4531 be associated with a single property name. Clients can store
4532 and retrieve properties associated with windows. For efficiency
4533 reasons, an atom is used rather than a character string.
4534 XInternAtom can be used to obtain the atom for property names.
4535
4536 A property is also stored in one of several possible formats.
4537 The X server can store the information as 8-bit quantities,
4538 16-bit quantities, or 32-bit quantities. This permits the X
4539 server to present the data in the byte order that the client
4540 expects. If you define further properties of complex type, you
4541 must encode and decode them yourself. These functions must be
4542 carefully written if they are to be portable. For further
4543 information about how to write a library extension, see
4544 appendix C. The type of a property is defined by an atom, which
4545 allows for arbitrary extension in this type scheme.
4546
4547 Certain property names are predefined in the server for
4548 commonly used functions. The atoms for these properties are
4549 defined in <X11/Xatom.h>. To avoid name clashes with user
4550 symbols, the #define name for each atom has the XA_ prefix. For
4551 an explanation of the functions that let you get and set much
4552 of the information stored in these predefined properties, see
4553 chapter 14.
4554
4555 The core protocol imposes no semantics on these property names,
4556 but semantics are specified in other X Consortium standards,
4557 such as the Inter-Client Communication Conventions Manual and
4558 the X Logical Font Description Conventions.
4559
4560 You can use properties to communicate other information between
4561 applications. The functions described in this section let you
4562 define new properties and get the unique atom IDs in your
4563 applications.
4564
4565 Although any particular atom can have some client
4566 interpretation within each of the name spaces, atoms occur in
4567 five distinct name spaces within the protocol:
4568 * Selections
4569 * Property names
4570 * Property types
4571 * Font properties
4572 * Type of a ClientMessage event (none are built into the X
4573 server)
4574
4575 The built-in selection property names are:
4576 PRIMARY SECONDARY
4577
4578 The built-in property names are:
4579 CUT_BUFFER0 RESOURCE_MANAGER
4580 CUT_BUFFER1 WM_CLASS
4581 CUT_BUFFER2 WM_CLIENT_MACHINE
4582 CUT_BUFFER3 WM_COLORMAP_WINDOWS
4583 CUT_BUFFER4 WM_COMMAND
4584 CUT_BUFFER5 WM_HINTS
4585 CUT_BUFFER6 WM_ICON_NAME
4586 CUT_BUFFER7 WM_ICON_SIZE
4587 RGB_BEST_MAP WM_NAME
4588 RGB_BLUE_MAP WM_NORMAL_HINTS
4589 RGB_DEFAULT_MAP WM_PROTOCOLS
4590 RGB_GRAY_MAP WM_STATE
4591 RGB_GREEN_MAP WM_TRANSIENT_FOR
4592 RGB_RED_MAP WM_ZOOM_HINTS
4593
4594 The built-in property types are:
4595 ARC PIXMAP
4596 ATOM POINT
4597 BITMAP RGB_COLOR_MAP
4598 CARDINAL RECTANGLE
4599 COLORMAP STRING
4600 CURSOR VISUALID
4601 DRAWABLE WINDOW
4602 FONT WM_HINTS
4603 INTEGER WM_SIZE_HINTS
4604
4605 The built-in font property names are:
4606 MIN_SPACE STRIKEOUT_DESCENT
4607 NORM_SPACE STRIKEOUT_ASCENT
4608 MAX_SPACE ITALIC_ANGLE
4609 END_SPACE X_HEIGHT
4610 SUPERSCRIPT_X QUAD_WIDTH
4611 SUPERSCRIPT_Y WEIGHT
4612 SUBSCRIPT_X POINT_SIZE
4613 SUBSCRIPT_Y RESOLUTION
4614 UNDERLINE_POSITION COPYRIGHT
4615 UNDERLINE_THICKNESS NOTICE
4616 FONT_NAME FAMILY_NAME
4617 FULL_NAME CAP_HEIGHT
4618
4619 For further information about font properties, see section 8.5.
4620
4621 To return an atom for a given name, use XInternAtom.
4622
4623 Atom XInternAtom(Display *display, char *atom_name, Bool
4624 only_if_exists);
4625
4626 display
4627
4628 Specifies the connection to the X server.
4629
4630 atom_name
4631
4632 Specifies the name associated with the atom you want returned.
4633
4634 only_if_exists
4635
4636 Specifies a Boolean value that indicates whether the atom must
4637 be created.
4638
4639 The XInternAtom function returns the atom identifier associated
4640 with the specified atom_name string. If only_if_exists is
4641 False, the atom is created if it does not exist. Therefore,
4642 XInternAtom can return None. If the atom name is not in the
4643 Host Portable Character Encoding, the result is
4644 implementation-dependent. Uppercase and lowercase matter; the
4645 strings ``thing'', ``Thing'', and ``thinG'' all designate
4646 different atoms. The atom will remain defined even after the
4647 client's connection closes. It will become undefined only when
4648 the last connection to the X server closes.
4649
4650 XInternAtom can generate BadAlloc and BadValue errors.
4651
4652 To return atoms for an array of names, use XInternAtoms.
4653
4654 Status XInternAtoms(Display *display, char **names, int count,
4655 Bool only_if_exists, Atom *atoms_return);
4656
4657 display
4658
4659 Specifies the connection to the X server.
4660
4661 names
4662
4663 Specifies the array of atom names.
4664
4665 count
4666
4667 Specifies the number of atom names in the array.
4668
4669 only_if_exists
4670
4671 Specifies a Boolean value that indicates whether the atom must
4672 be created.
4673
4674 atoms_return
4675
4676 Returns the atoms.
4677
4678 The XInternAtoms function returns the atom identifiers
4679 associated with the specified names. The atoms are stored in
4680 the atoms_return array supplied by the caller. Calling this
4681 function is equivalent to calling XInternAtom for each of the
4682 names in turn with the specified value of only_if_exists, but
4683 this function minimizes the number of round-trip protocol
4684 exchanges between the client and the X server.
4685
4686 This function returns a nonzero status if atoms are returned
4687 for all of the names; otherwise, it returns zero.
4688
4689 XInternAtoms can generate BadAlloc and BadValue errors.
4690
4691 To return a name for a given atom identifier, use XGetAtomName.
4692
4693 char *XGetAtomName(Display *display, Atom atom);
4694
4695 display
4696
4697 Specifies the connection to the X server.
4698
4699 atom
4700
4701 Specifies the atom for the property name you want returned.
4702
4703 The XGetAtomName function returns the name associated with the
4704 specified atom. If the data returned by the server is in the
4705 Latin Portable Character Encoding, then the returned string is
4706 in the Host Portable Character Encoding. Otherwise, the result
4707 is implementation-dependent. To free the resulting string, call
4708 XFree.
4709
4710 XGetAtomName can generate a BadAtom error.
4711
4712 To return the names for an array of atom identifiers, use
4713 XGetAtomNames.
4714
4715 Status XGetAtomNames(Display *display, Atom *atoms, int count,
4716 char **names_return);
4717
4718 display
4719
4720 Specifies the connection to the X server.
4721
4722 atoms
4723
4724 Specifies the array of atoms.
4725
4726 count
4727
4728 Specifies the number of atoms in the array.
4729
4730 names_return
4731
4732 Returns the atom names.
4733
4734 The XGetAtomNames function returns the names associated with
4735 the specified atoms. The names are stored in the names_return
4736 array supplied by the caller. Calling this function is
4737 equivalent to calling XGetAtomName for each of the atoms in
4738 turn, but this function minimizes the number of round-trip
4739 protocol exchanges between the client and the X server.
4740
4741 This function returns a nonzero status if names are returned
4742 for all of the atoms; otherwise, it returns zero.
4743
4744 XGetAtomNames can generate a BadAtom error.
4745
4746Obtaining and Changing Window Properties
4747
4748 You can attach a property list to every window. Each property
4749 has a name, a type, and a value (see section 4.3). The value is
4750 an array of 8-bit, 16-bit, or 32-bit quantities, whose
4751 interpretation is left to the clients. The type char is used to
4752 represent 8-bit quantities, the type short is used to represent
4753 16-bit quantities, and the type long is used to represent
4754 32-bit quantities.
4755
4756 Xlib provides functions that you can use to obtain, change,
4757 update, or interchange window properties. In addition, Xlib
4758 provides other utility functions for inter-client communication
4759 (see chapter 14).
4760
4761 To obtain the type, format, and value of a property of a given
4762 window, use XGetWindowProperty.
4763
4764 int XGetWindowProperty(Display *display, Window w, Atom
4765 property, long long_offset, long long_length, Bool delete, Atom
4766 req_type, Atom *actual_type_return, int *actual_format_return,
4767 unsigned long *nitems_return, unsigned long
4768 *bytes_after_return, unsigned char **prop_return);
4769
4770 display
4771
4772 Specifies the connection to the X server.
4773
4774 w
4775
4776 Specifies the window whose property you want to obtain.
4777
4778 property
4779
4780 Specifies the property name.
4781
4782 long_offset
4783
4784 Specifies the offset in the specified property (in 32-bit
4785 quantities) where the data is to be retrieved.
4786
4787 long_length
4788
4789 Specifies the length in 32-bit multiples of the data to be
4790 retrieved.
4791
4792 delete
4793
4794 Specifies a Boolean value that determines whether the property
4795 is deleted.
4796
4797 req_type
4798
4799 Specifies the atom identifier associated with the property type
4800 or AnyPropertyType.
4801
4802 actual_type_return
4803
4804 Returns the atom identifier that defines the actual type of the
4805 property.
4806
4807 actual_format_return
4808
4809 Returns the actual format of the property.
4810
4811 nitems_return
4812
4813 Returns the actual number of 8-bit, 16-bit, or 32-bit items
4814 stored in the prop_return data.
4815
4816 bytes_after_return
4817
4818 Returns the number of bytes remaining to be read in the
4819 property if a partial read was performed.
4820
4821 prop_return
4822
4823 Returns the data in the specified format.
4824
4825 The XGetWindowProperty function returns the actual type of the
4826 property; the actual format of the property; the number of
4827 8-bit, 16-bit, or 32-bit items transferred; the number of bytes
4828 remaining to be read in the property; and a pointer to the data
4829 actually returned. XGetWindowProperty sets the return arguments
4830 as follows:
4831 * If the specified property does not exist for the specified
4832 window, XGetWindowProperty returns None to
4833 actual_type_return and the value zero to
4834 actual_format_return and bytes_after_return. The
4835 nitems_return argument is empty. In this case, the delete
4836 argument is ignored.
4837 * If the specified property exists but its type does not
4838 match the specified type, XGetWindowProperty returns the
4839 actual property type to actual_type_return, the actual
4840 property format (never zero) to actual_format_return, and
4841 the property length in bytes (even if the
4842 actual_format_return is 16 or 32) to bytes_after_return. It
4843 also ignores the delete argument. The nitems_return
4844 argument is empty.
4845 * If the specified property exists and either you assign
4846 AnyPropertyType to the req_type argument or the specified
4847 type matches the actual property type, XGetWindowProperty
4848 returns the actual property type to actual_type_return and
4849 the actual property format (never zero) to
4850 actual_format_return. It also returns a value to
4851 bytes_after_return and nitems_return, by defining the
4852 following values:
4853 * N = actual length of the stored property in bytes (even if
4854 the format is 16 or 32) I = 4 * long_offset T = N - I L =
4855 MINIMUM(T, 4 * long_length) A = N - (I + L)
4856 * The returned value starts at byte index I in the property
4857 (indexing from zero), and its length in bytes is L. If the
4858 value for long_offset causes L to be negative, a BadValue
4859 error results. The value of bytes_after_return is A, giving
4860 the number of trailing unread bytes in the stored property.
4861
4862 If the returned format is 8, the returned data is represented
4863 as a char array. If the returned format is 16, the returned
4864 data is represented as a short array and should be cast to that
4865 type to obtain the elements. If the returned format is 32, the
4866 returned data is represented as a long array and should be cast
4867 to that type to obtain the elements.
4868
4869 XGetWindowProperty always allocates one extra byte in
4870 prop_return (even if the property is zero length) and sets it
4871 to zero so that simple properties consisting of characters do
4872 not have to be copied into yet another string before use.
4873
4874 If delete is True and bytes_after_return is zero,
4875 XGetWindowProperty deletes the property from the window and
4876 generates a PropertyNotify event on the window.
4877
4878 The function returns Success if it executes successfully. To
4879 free the resulting data, use XFree.
4880
4881 XGetWindowProperty can generate BadAtom, BadValue, and
4882 BadWindow errors.
4883
4884 To obtain a given window's property list, use XListProperties.
4885
4886 Atom *XListProperties(Display *display, Window w, int
4887 *num_prop_return);
4888
4889 display
4890
4891 Specifies the connection to the X server.
4892
4893 w
4894
4895 Specifies the window whose property list you want to obtain.
4896
4897 num_prop_return
4898
4899 Returns the length of the properties array.
4900
4901 The XListProperties function returns a pointer to an array of
4902 atom properties that are defined for the specified window or
4903 returns NULL if no properties were found. To free the memory
4904 allocated by this function, use XFree.
4905
4906 XListProperties can generate a BadWindow error.
4907
4908 To change a property of a given window, use XChangeProperty.
4909
4910 XChangeProperty(Display *display, Window w, Atom property, Atom
4911 type, int format, int mode, unsignedchar *data, int nelements);
4912
4913 display
4914
4915 Specifies the connection to the X server.
4916
4917 w
4918
4919 Specifies the window whose property you want to change.
4920
4921 property
4922
4923 Specifies the property name.
4924
4925 type
4926
4927 Specifies the type of the property. The X server does not
4928 interpret the type but simply passes it back to an application
4929 that later calls XGetWindowProperty.
4930
4931 format
4932
4933 Specifies whether the data should be viewed as a list of 8-bit,
4934 16-bit, or 32-bit quantities. Possible values are 8, 16, and
4935 32. This information allows the X server to correctly perform
4936 byte-swap operations as necessary. If the format is 16-bit or
4937 32-bit, you must explicitly cast your data pointer to an
4938 (unsigned char *) in the call to XChangeProperty.
4939
4940 mode
4941
4942 Specifies the mode of the operation. You can pass
4943 PropModeReplace, PropModePrepend, or PropModeAppend.
4944
4945 data
4946
4947 Specifies the property data.
4948
4949 nelements
4950
4951 Specifies the number of elements of the specified data format.
4952
4953 The XChangeProperty function alters the property for the
4954 specified window and causes the X server to generate a
4955 PropertyNotify event on that window. XChangeProperty performs
4956 the following:
4957 * If mode is PropModeReplace, XChangeProperty discards the
4958 previous property value and stores the new data.
4959 * If mode is PropModePrepend or PropModeAppend,
4960 XChangeProperty inserts the specified data before the
4961 beginning of the existing data or onto the end of the
4962 existing data, respectively. The type and format must match
4963 the existing property value, or a BadMatch error results.
4964 If the property is undefined, it is treated as defined with
4965 the correct type and format with zero-length data.
4966
4967 If the specified format is 8, the property data must be a char
4968 array. If the specified format is 16, the property data must be
4969 a short array. If the specified format is 32, the property data
4970 must be a long array.
4971
4972 The lifetime of a property is not tied to the storing client.
4973 Properties remain until explicitly deleted, until the window is
4974 destroyed, or until the server resets. For a discussion of what
4975 happens when the connection to the X server is closed, see
4976 section 2.6. The maximum size of a property is server dependent
4977 and can vary dynamically depending on the amount of memory the
4978 server has available. (If there is insufficient space, a
4979 BadAlloc error results.)
4980
4981 XChangeProperty can generate BadAlloc, BadAtom, BadMatch,
4982 BadValue, and BadWindow errors.
4983
4984 To rotate a window's property list, use
4985 XRotateWindowProperties.
4986
4987 XRotateWindowProperties(Display *display, Window w, Atom
4988 properties[], int num_prop, int npositions);
4989
4990 display
4991
4992 Specifies the connection to the X server.
4993
4994 w
4995
4996 Specifies the window.
4997
4998 properties
4999
5000 Specifies the array of properties that are to be rotated.
5001
5002 num_prop
5003
5004 Specifies the length of the properties array.
5005
5006 npositions
5007
5008 Specifies the rotation amount.
5009
5010 The XRotateWindowProperties function allows you to rotate
5011 properties on a window and causes the X server to generate
5012 PropertyNotify events. If the property names in the properties
5013 array are viewed as being numbered starting from zero and if
5014 there are num_prop property names in the list, then the value
5015 associated with property name I becomes the value associated
5016 with property name (I + npositions) mod N for all I from zero
5017 to N - 1. The effect is to rotate the states by npositions
5018 places around the virtual ring of property names (right for
5019 positive npositions, left for negative npositions). If
5020 npositions mod N is nonzero, the X server generates a
5021 PropertyNotify event for each property in the order that they
5022 are listed in the array. If an atom occurs more than once in
5023 the list or no property with that name is defined for the
5024 window, a BadMatch error results. If a BadAtom or BadMatch
5025 error results, no properties are changed.
5026
5027 XRotateWindowProperties can generate BadAtom, BadMatch, and
5028 BadWindow errors.
5029
5030 To delete a property on a given window, use XDeleteProperty.
5031
5032 XDeleteProperty(Display *display, Window w, Atom property);
5033
5034 display
5035
5036 Specifies the connection to the X server.
5037
5038 w
5039
5040 Specifies the window whose property you want to delete.
5041
5042 property
5043
5044 Specifies the property name.
5045
5046 The XDeleteProperty function deletes the specified property
5047 only if the property was defined on the specified window and
5048 causes the X server to generate a PropertyNotify event on the
5049 window unless the property does not exist.
5050
5051 XDeleteProperty can generate BadAtom and BadWindow errors.
5052
5053Selections
5054
5055 Selections are one method used by applications to exchange
5056 data. By using the property mechanism, applications can
5057 exchange data of arbitrary types and can negotiate the type of
5058 the data. A selection can be thought of as an indirect property
5059 with a dynamic type. That is, rather than having the property
5060 stored in the X server, the property is maintained by some
5061 client (the owner). A selection is global in nature (considered
5062 to belong to the user but be maintained by clients) rather than
5063 being private to a particular window subhierarchy or a
5064 particular set of clients.
5065
5066 Xlib provides functions that you can use to set, get, or
5067 request conversion of selections. This allows applications to
5068 implement the notion of current selection, which requires that
5069 notification be sent to applications when they no longer own
5070 the selection. Applications that support selection often
5071 highlight the current selection and so must be informed when
5072 another application has acquired the selection so that they can
5073 unhighlight the selection.
5074
5075 When a client asks for the contents of a selection, it
5076 specifies a selection target type. This target type can be used
5077 to control the transmitted representation of the contents. For
5078 example, if the selection is ``the last thing the user clicked
5079 on'' and that is currently an image, then the target type might
5080 specify whether the contents of the image should be sent in XY
5081 format or Z format.
5082
5083 The target type can also be used to control the class of
5084 contents transmitted, for example, asking for the ``looks''
5085 (fonts, line spacing, indentation, and so forth) of a paragraph
5086 selection, not the text of the paragraph. The target type can
5087 also be used for other purposes. The protocol does not
5088 constrain the semantics.
5089
5090 To set the selection owner, use XSetSelectionOwner.
5091
5092 XSetSelectionOwner(Display *display, Atom selection, Window
5093 owner, Time time);
5094
5095 display
5096
5097 Specifies the connection to the X server.
5098
5099 selection
5100
5101 Specifies the selection atom.
5102
5103 owner
5104
5105 Specifies the owner of the specified selection atom. You can
5106 pass a window or None.
5107
5108 time
5109
5110 Specifies the time. You can pass either a timestamp or
5111 CurrentTime.
5112
5113 The XSetSelectionOwner function changes the owner and
5114 last-change time for the specified selection and has no effect
5115 if the specified time is earlier than the current last-change
5116 time of the specified selection or is later than the current X
5117 server time. Otherwise, the last-change time is set to the
5118 specified time, with CurrentTime replaced by the current server
5119 time. If the owner window is specified as None, then the owner
5120 of the selection becomes None (that is, no owner). Otherwise,
5121 the owner of the selection becomes the client executing the
5122 request.
5123
5124 If the new owner (whether a client or None) is not the same as
5125 the current owner of the selection and the current owner is not
5126 None, the current owner is sent a SelectionClear event. If the
5127 client that is the owner of a selection is later terminated
5128 (that is, its connection is closed) or if the owner window it
5129 has specified in the request is later destroyed, the owner of
5130 the selection automatically reverts to None, but the
5131 last-change time is not affected. The selection atom is
5132 uninterpreted by the X server. XGetSelectionOwner returns the
5133 owner window, which is reported in SelectionRequest and
5134 SelectionClear events. Selections are global to the X server.
5135
5136 XSetSelectionOwner can generate BadAtom and BadWindow errors.
5137
5138 To return the selection owner, use XGetSelectionOwner.
5139
5140 Window XGetSelectionOwner(Display *display, Atom selection);
5141
5142 display
5143
5144 Specifies the connection to the X server.
5145
5146 selection
5147
5148 Specifies the selection atom whose owner you want returned.
5149
5150 The XGetSelectionOwner function returns the window ID
5151 associated with the window that currently owns the specified
5152 selection. If no selection was specified, the function returns
5153 the constant None. If None is returned, there is no owner for
5154 the selection.
5155
5156 XGetSelectionOwner can generate a BadAtom error.
5157
5158 To request conversion of a selection, use XConvertSelection.
5159
5160 XConvertSelection(Display *display, Atom selection, Atom
5161 target, Atom property, Window requestor, Time time);
5162
5163 display
5164
5165 Specifies the connection to the X server.
5166
5167 selection
5168
5169 Specifies the selection atom.
5170
5171 target
5172
5173 Specifies the target atom.
5174
5175 property
5176
5177 Specifies the property name. You also can pass None.
5178
5179 requestor
5180
5181 Specifies the requestor.
5182
5183 time
5184
5185 Specifies the time. You can pass either a timestamp or
5186 CurrentTime.
5187
5188 XConvertSelection requests that the specified selection be
5189 converted to the specified target type:
5190 * If the specified selection has an owner, the X server sends
5191 a SelectionRequest event to that owner.
5192 * If no owner for the specified selection exists, the X
5193 server generates a SelectionNotify event to the requestor
5194 with property None.
5195
5196 The arguments are passed on unchanged in either of the events.
5197 There are two predefined selection atoms: PRIMARY and
5198 SECONDARY.
5199
5200 XConvertSelection can generate BadAtom and BadWindow errors.
5201
5202Chapter 5. Pixmap and Cursor Functions
5203
5204 Table of Contents
5205
5206 Creating and Freeing Pixmaps
5207 Creating, Recoloring, and Freeing Cursors
5208
5209Creating and Freeing Pixmaps
5210
5211 Pixmaps can only be used on the screen on which they were
5212 created. Pixmaps are off-screen resources that are used for
5213 various operations, such as defining cursors as tiling patterns
5214 or as the source for certain raster operations. Most graphics
5215 requests can operate either on a window or on a pixmap. A
5216 bitmap is a single bit-plane pixmap.
5217
5218 To create a pixmap of a given size, use XCreatePixmap.
5219
5220 Pixmap XCreatePixmap(Display *display, Drawable d, unsigned int
5221 width, unsigned int height, unsigned int depth);
5222
5223 display
5224
5225 Specifies the connection to the X server.
5226
5227 d
5228
5229 Specifies which screen the pixmap is created on.
5230
5231 width
5232
5233 height
5234
5235 Specify the width and height, which define the dimensions of
5236 the pixmap.
5237
5238 depth
5239
5240 Specifies the depth of the pixmap.
5241
5242 The XCreatePixmap function creates a pixmap of the width,
5243 height, and depth you specified and returns a pixmap ID that
5244 identifies it. It is valid to pass an InputOnly window to the
5245 drawable argument. The width and height arguments must be
5246 nonzero, or a BadValue error results. The depth argument must
5247 be one of the depths supported by the screen of the specified
5248 drawable, or a BadValue error results.
5249
5250 The server uses the specified drawable to determine on which
5251 screen to create the pixmap. The pixmap can be used only on
5252 this screen and only with other drawables of the same depth
5253 (see XCopyPlane for an exception to this rule). The initial
5254 contents of the pixmap are undefined.
5255
5256 XCreatePixmap can generate BadAlloc, BadDrawable, and BadValue
5257 errors.
5258
5259 To free all storage associated with a specified pixmap, use
5260 XFreePixmap.
5261
5262 XFreePixmap(Display *display, Pixmap pixmap);
5263
5264 display
5265
5266 Specifies the connection to the X server.
5267
5268 pixmap
5269
5270 Specifies the pixmap.
5271
5272 The XFreePixmap function first deletes the association between
5273 the pixmap ID and the pixmap. Then, the X server frees the
5274 pixmap storage when there are no references to it. The pixmap
5275 should never be referenced again.
5276
5277 XFreePixmap can generate a BadPixmap error.
5278
5279Creating, Recoloring, and Freeing Cursors
5280
5281 Each window can have a different cursor defined for it.
5282 Whenever the pointer is in a visible window, it is set to the
5283 cursor defined for that window. If no cursor was defined for
5284 that window, the cursor is the one defined for the parent
5285 window.
5286
5287 From X's perspective, a cursor consists of a cursor source,
5288 mask, colors, and a hotspot. The mask pixmap determines the
5289 shape of the cursor and must be a depth of one. The source
5290 pixmap must have a depth of one, and the colors determine the
5291 colors of the source. The hotspot defines the point on the
5292 cursor that is reported when a pointer event occurs. There may
5293 be limitations imposed by the hardware on cursors as to size
5294 and whether a mask is implemented. XQueryBestCursor can be used
5295 to find out what sizes are possible. There is a standard font
5296 for creating cursors, but Xlib provides functions that you can
5297 use to create cursors from an arbitrary font or from bitmaps.
5298
5299 To create a cursor from the standard cursor font, use
5300 XCreateFontCursor.
5301
5302 #include <X11/cursorfont.h>
5303
5304 Cursor XCreateFontCursor(Display *display, unsigned int shape);
5305
5306 display
5307
5308 Specifies the connection to the X server.
5309
5310 shape
5311
5312 Specifies the shape of the cursor.
5313
5314 X provides a set of standard cursor shapes in a special font
5315 named cursor. Applications are encouraged to use this interface
5316 for their cursors because the font can be customized for the
5317 individual display type. The shape argument specifies which
5318 glyph of the standard fonts to use.
5319
5320 The hotspot comes from the information stored in the cursor
5321 font. The initial colors of a cursor are a black foreground and
5322 a white background (see XRecolorCursor). For further
5323 information about cursor shapes, see appendix B.
5324
5325 XCreateFontCursor can generate BadAlloc and BadValue errors.
5326
5327 To create a cursor from font glyphs, use XCreateGlyphCursor.
5328
5329 Cursor XCreateGlyphCursor(Display *display, Font source_font,
5330 Font mask_font, unsigned int source_char, unsigned int
5331 mask_char, XColor *foreground_color, XColor *background_color);
5332
5333 display
5334
5335 Specifies the connection to the X server.
5336
5337 source_font
5338
5339 Specifies the font for the source glyph.
5340
5341 mask_font
5342
5343 Specifies the font for the mask glyph or None.
5344
5345 source_char
5346
5347 Specifies the character glyph for the source.
5348
5349 mask_char
5350
5351 Specifies the glyph character for the mask.
5352
5353 foreground_color
5354
5355 Specifies the RGB values for the foreground of the source.
5356
5357 background_color
5358
5359 Specifies the RGB values for the background of the source.
5360
5361 The XCreateGlyphCursor function is similar to
5362 XCreatePixmapCursor except that the source and mask bitmaps are
5363 obtained from the specified font glyphs. The source_char must
5364 be a defined glyph in source_font, or a BadValue error results.
5365 If mask_font is given, mask_char must be a defined glyph in
5366 mask_font, or a BadValue error results. The mask_font and
5367 character are optional. The origins of the source_char and
5368 mask_char (if defined) glyphs are positioned coincidently and
5369 define the hotspot. The source_char and mask_char need not have
5370 the same bounding box metrics, and there is no restriction on
5371 the placement of the hotspot relative to the bounding boxes. If
5372 no mask_char is given, all pixels of the source are displayed.
5373 You can free the fonts immediately by calling XFreeFont if no
5374 further explicit references to them are to be made.
5375
5376 For 2-byte matrix fonts, the 16-bit value should be formed with
5377 the byte1 member in the most significant byte and the byte2
5378 member in the least significant byte.
5379
5380 XCreateGlyphCursor can generate BadAlloc, BadFont, and BadValue
5381 errors.
5382
5383 To create a cursor from two bitmaps, use XCreatePixmapCursor.
5384
5385 Cursor XCreatePixmapCursor(Display *display, Pixmap source,
5386 Pixmap mask, XColor *foreground_color, XColor
5387 *background_color, unsigned int x, unsigned int y);
5388
5389 display
5390
5391 Specifies the connection to the X server.
5392
5393 source
5394
5395 Specifies the shape of the source cursor.
5396
5397 mask
5398
5399 Specifies the cursor's source bits to be displayed or None.
5400
5401 foreground_color
5402
5403 Specifies the RGB values for the foreground of the source.
5404
5405 background_color
5406
5407 Specifies the RGB values for the background of the source.
5408
5409 x
5410
5411 y
5412
5413 Specify the x and y coordinates, which indicate the hotspot
5414 relative to the source's origin.
5415
5416 The XCreatePixmapCursor function creates a cursor and returns
5417 the cursor ID associated with it. The foreground and background
5418 RGB values must be specified using foreground_color and
5419 background_color, even if the X server only has a StaticGray or
5420 GrayScale screen. The foreground color is used for the pixels
5421 set to 1 in the source, and the background color is used for
5422 the pixels set to 0. Both source and mask, if specified, must
5423 have depth one (or a BadMatch error results) but can have any
5424 root. The mask argument defines the shape of the cursor. The
5425 pixels set to 1 in the mask define which source pixels are
5426 displayed, and the pixels set to 0 define which pixels are
5427 ignored. If no mask is given, all pixels of the source are
5428 displayed. The mask, if present, must be the same size as the
5429 pixmap defined by the source argument, or a BadMatch error
5430 results. The hotspot must be a point within the source, or a
5431 BadMatch error results.
5432
5433 The components of the cursor can be transformed arbitrarily to
5434 meet display limitations. The pixmaps can be freed immediately
5435 if no further explicit references to them are to be made.
5436 Subsequent drawing in the source or mask pixmap has an
5437 undefined effect on the cursor. The X server might or might not
5438 make a copy of the pixmap.
5439
5440 XCreatePixmapCursor can generate BadAlloc and BadPixmap errors.
5441
5442 To determine useful cursor sizes, use XQueryBestCursor.
5443
5444 Status XQueryBestCursor(Display *display, Drawable d, unsigned
5445 int width, unsigned int height, unsigned int *width_return,
5446 unsigned int *height_return);
5447
5448 display
5449
5450 Specifies the connection to the X server.
5451
5452 d
5453
5454 Specifies the drawable, which indicates the screen.
5455
5456 width
5457
5458 height
5459
5460 Specify the width and height of the cursor that you want the
5461 size information for.
5462
5463 width_return
5464
5465 height_return
5466
5467 Return the best width and height that is closest to the
5468 specified width and height.
5469
5470 Some displays allow larger cursors than other displays. The
5471 XQueryBestCursor function provides a way to find out what size
5472 cursors are actually possible on the display. It returns the
5473 largest size that can be displayed. Applications should be
5474 prepared to use smaller cursors on displays that cannot support
5475 large ones.
5476
5477 XQueryBestCursor can generate a BadDrawable error.
5478
5479 To change the color of a given cursor, use XRecolorCursor.
5480
5481 XRecolorCursor(Display *display, Cursor cursor, XColor
5482 *foreground_color, XColor *background_color);
5483
5484 display
5485
5486 Specifies the connection to the X server.
5487
5488 cursor
5489
5490 Specifies the cursor.
5491
5492 foreground_color
5493
5494 Specifies the RGB values for the foreground of the source.
5495
5496 background_color
5497
5498 Specifies the RGB values for the background of the source.
5499
5500 The XRecolorCursor function changes the color of the specified
5501 cursor, and if the cursor is being displayed on a screen, the
5502 change is visible immediately. The pixel members of the XColor
5503 structures are ignored; only the RGB values are used.
5504
5505 XRecolorCursor can generate a BadCursor error.
5506
5507 To free (destroy) a given cursor, use XFreeCursor.
5508
5509 XFreeCursor(Display *display, Cursor cursor);
5510
5511 display
5512
5513 Specifies the connection to the X server.
5514
5515 cursor
5516
5517 Specifies the cursor.
5518
5519 The XFreeCursor function deletes the association between the
5520 cursor resource ID and the specified cursor. The cursor storage
5521 is freed when no other resource references it. The specified
5522 cursor ID should not be referred to again.
5523
5524 XFreeCursor can generate a BadCursor error.
5525
5526Chapter 6. Color Management Functions
5527
5528 Table of Contents
5529
5530 Color Structures
5531 Color Strings
5532
5533 RGB Device String Specification
5534 RGB Intensity String Specification
5535 Device-Independent String Specifications
5536
5537 Color Conversion Contexts and Gamut Mapping
5538 Creating, Copying, and Destroying Colormaps
5539 Mapping Color Names to Values
5540 Allocating and Freeing Color Cells
5541 Modifying and Querying Colormap Cells
5542 Color Conversion Context Functions
5543
5544 Getting and Setting the Color Conversion Context of a
5545 Colormap
5546
5547 Obtaining the Default Color Conversion Context
5548 Color Conversion Context Macros
5549 Modifying Attributes of a Color Conversion Context
5550 Creating and Freeing a Color Conversion Context
5551
5552 Converting between Color Spaces
5553 Callback Functions
5554
5555 Prototype Gamut Compression Procedure
5556 Supplied Gamut Compression Procedures
5557 Prototype White Point Adjustment Procedure
5558 Supplied White Point Adjustment Procedures
5559
5560 Gamut Querying Functions
5561
5562 Red, Green, and Blue Queries
5563 CIELab Queries
5564 CIELuv Queries
5565 TekHVC Queries
5566
5567 Color Management Extensions
5568
5569 Color Spaces
5570 Adding Device-Independent Color Spaces
5571 Querying Color Space Format and Prefix
5572 Creating Additional Color Spaces
5573 Parse String Callback
5574 Color Specification Conversion Callback
5575 Function Sets
5576 Adding Function Sets
5577 Creating Additional Function Sets
5578
5579 Each X window always has an associated colormap that provides a
5580 level of indirection between pixel values and colors displayed
5581 on the screen. Xlib provides functions that you can use to
5582 manipulate a colormap. The X protocol defines colors using
5583 values in the RGB color space. The RGB color space is device
5584 dependent; rendering an RGB value on differing output devices
5585 typically results in different colors. Xlib also provides a
5586 means for clients to specify color using device-independent
5587 color spaces for consistent results across devices. Xlib
5588 supports device-independent color spaces derivable from the CIE
5589 XYZ color space. This includes the CIE XYZ, xyY, L*u*v*, and
5590 L*a*b* color spaces as well as the TekHVC color space.
5591
5592 This chapter discusses how to:
5593 * Create, copy, and destroy a colormap
5594 * Specify colors by name or value
5595 * Allocate, modify, and free color cells
5596 * Read entries in a colormap
5597 * Convert between color spaces
5598 * Control aspects of color conversion
5599 * Query the color gamut of a screen
5600 * Add new color spaces
5601
5602 All functions, types, and symbols in this chapter with the
5603 prefix ``Xcms'' are defined in <X11/Xcms.h>. The remaining
5604 functions and types are defined in <X11/Xlib.h>.
5605
5606 Functions in this chapter manipulate the representation of
5607 color on the screen. For each possible value that a pixel can
5608 take in a window, there is a color cell in the colormap. For
5609 example, if a window is 4 bits deep, pixel values 0 through 15
5610 are defined. A colormap is a collection of color cells. A color
5611 cell consists of a triple of red, green, and blue (RGB) values.
5612 The hardware imposes limits on the number of significant bits
5613 in these values. As each pixel is read out of display memory,
5614 the pixel is looked up in a colormap. The RGB value of the cell
5615 determines what color is displayed on the screen. On a
5616 grayscale display with a black-and-white monitor, the values
5617 are combined to determine the brightness on the screen.
5618
5619 Typically, an application allocates color cells or sets of
5620 color cells to obtain the desired colors. The client can
5621 allocate read-only cells. In which case, the pixel values for
5622 these colors can be shared among multiple applications, and the
5623 RGB value of the cell cannot be changed. If the client
5624 allocates read/write cells, they are exclusively owned by the
5625 client, and the color associated with the pixel value can be
5626 changed at will. Cells must be allocated (and, if read/write,
5627 initialized with an RGB value) by a client to obtain desired
5628 colors. The use of pixel value for an unallocated cell results
5629 in an undefined color.
5630
5631 Because colormaps are associated with windows, X supports
5632 displays with multiple colormaps and, indeed, different types
5633 of colormaps. If there are insufficient colormap resources in
5634 the display, some windows will display in their true colors,
5635 and others will display with incorrect colors. A window manager
5636 usually controls which windows are displayed in their true
5637 colors if more than one colormap is required for the color
5638 resources the applications are using. At any time, there is a
5639 set of installed colormaps for a screen. Windows using one of
5640 the installed colormaps display with true colors, and windows
5641 using other colormaps generally display with incorrect colors.
5642 You can control the set of installed colormaps by using
5643 XInstallColormap and XUninstallColormap.
5644
5645 Colormaps are local to a particular screen. Screens always have
5646 a default colormap, and programs typically allocate cells out
5647 of this colormap. Generally, you should not write applications
5648 that monopolize color resources. Although some hardware
5649 supports multiple colormaps installed at one time, many of the
5650 hardware displays built today support only a single installed
5651 colormap, so the primitives are written to encourage sharing of
5652 colormap entries between applications.
5653
5654 The DefaultColormap macro returns the default colormap. The
5655 DefaultVisual macro returns the default visual type for the
5656 specified screen. Possible visual types are StaticGray,
5657 GrayScale, StaticColor, PseudoColor, TrueColor, or DirectColor
5658 (see section 3.1).
5659
5660Color Structures
5661
5662 Functions that operate only on RGB color space values use an
5663 XColor structure, which contains:
5664
5665
5666
5667typedef struct {
5668 unsigned long pixel; /* pixel value */
5669 unsigned short red, green, blue; /* rgb values */
5670 char flags; /* DoRed, DoGreen, DoBlue */
5671 char pad;
5672} XColor;
5673
5674 The red, green, and blue values are always in the range 0 to
5675 65535 inclusive, independent of the number of bits actually
5676 used in the display hardware. The server scales these values
5677 down to the range used by the hardware. Black is represented by
5678 (0,0,0), and white is represented by (65535,65535,65535). In
5679 some functions, the flags member controls which of the red,
5680 green, and blue members is used and can be the inclusive OR of
5681 zero or more of DoRed, DoGreen, and DoBlue.
5682
5683 Functions that operate on all color space values use an
5684 XcmsColor structure. This structure contains a union of
5685 substructures, each supporting color specification encoding for
5686 a particular color space. Like the XColor structure, the
5687 XcmsColor structure contains pixel and color specification
5688 information (the spec member in the XcmsColor structure).
5689
5690
5691
5692typedef unsigned long XcmsColorFormat; /* Color Specifi
5693cation Format */
5694
5695typedef struct {
5696 union {
5697 XcmsRGB RGB;
5698 XcmsRGBi RGBi;
5699 XcmsCIEXYZ CIEXYZ;
5700 XcmsCIEuvY CIEuvY;
5701 XcmsCIExyY CIExyY;
5702 XcmsCIELab CIELab;
5703 XcmsCIELuv CIELuv;
5704 XcmsTekHVC TekHVC;
5705 XcmsPad Pad;
5706 } spec;
5707 unsigned long pixel;
5708 XcmsColorFormat format;
5709} XcmsColor; /* Xcms Color Structure */
5710
5711 Because the color specification can be encoded for the various
5712 color spaces, encoding for the spec member is identified by the
5713 format member, which is of type XcmsColorFormat. The following
5714 macros define standard formats.
5715#define XcmsUndefinedFormat 0x00000000
5716#define XcmsCIEXYZFormat 0x00000001 /* CIE XYZ */
5717#define XcmsCIEuvYFormat 0x00000002 /* CIE u'v'Y */
5718#define XcmsCIExyYFormat 0x00000003 /* CIE xyY */
5719#define XcmsCIELabFormat 0x00000004 /* CIE L*a*b* */
5720#define XcmsCIELuvFormat 0x00000005 /* CIE L*u*v* */
5721#define XcmsTekHVCFormat 0x00000006 /* TekHVC */
5722#define XcmsRGBFormat 0x80000000 /* RGB Device */
5723#define XcmsRGBiFormat 0x80000001 /* RGB Intensity */
5724
5725 Formats for device-independent color spaces are distinguishable
5726 from those for device-dependent spaces by the 32nd bit. If this
5727 bit is set, it indicates that the color specification is in a
5728 device-dependent form; otherwise, it is in a device-independent
5729 form. If the 31st bit is set, this indicates that the color
5730 space has been added to Xlib at run time (see section 6.12.4).
5731 The format value for a color space added at run time may be
5732 different each time the program is executed. If references to
5733 such a color space must be made outside the client (for
5734 example, storing a color specification in a file), then
5735 reference should be made by color space string prefix (see
5736 XcmsFormatOfPrefix and XcmsPrefixOfFormat).
5737
5738 Data types that describe the color specification encoding for
5739 the various color spaces are defined as follows:
5740
5741
5742
5743typedef double XcmsFloat;
5744
5745typedef struct {
5746 unsigned short red; /* 0x0000 to 0xffff */
5747 unsigned short green; /* 0x0000 to 0xffff */
5748 unsigned short blue; /* 0x0000 to 0xffff */
5749} XcmsRGB; /* RGB Device */
5750
5751
5752
5753typedef struct {
5754 XcmsFloat red; /* 0.0 to 1.0 */
5755 XcmsFloat green; /* 0.0 to 1.0 */
5756 XcmsFloat blue; /* 0.0 to 1.0 */
5757} XcmsRGBi; /* RGB Intensity */
5758
5759
5760
5761typedef struct {
5762 XcmsFloat X;
5763 XcmsFloat Y; /* 0.0 to 1.0 */
5764 XcmsFloat Z;
5765} XcmsCIEXYZ; /* CIE XYZ */
5766
5767
5768
5769typedef struct {
5770 XcmsFloat u_prime; /* 0.0 to ~0.6 */
5771 XcmsFloat v_prime; /* 0.0 to ~0.6 */
5772 XcmsFloat Y; /* 0.0 to 1.0 */
5773} XcmsCIEuvY; /* CIE u'v'Y */
5774
5775
5776
5777typedef struct {
5778 XcmsFloat x; /* 0.0 to ~.75 */
5779 XcmsFloat y; /* 0.0 to ~.85 */
5780 XcmsFloat Y; /* 0.0 to 1.0 */
5781} XcmsCIExyY; /* CIE xyY */
5782
5783
5784
5785typedef struct {
5786 XcmsFloat L_star; /* 0.0 to 100.0 */
5787 XcmsFloat a_star;
5788 XcmsFloat b_star;
5789} XcmsCIELab; /* CIE L*a*b* */
5790
5791
5792
5793typedef struct {
5794 XcmsFloat L_star; /* 0.0 to 100.0 */
5795 XcmsFloat u_star;
5796 XcmsFloat v_star;
5797} XcmsCIELuv; /* CIE L*u*v* */
5798
5799
5800
5801typedef struct {
5802 XcmsFloat H; /* 0.0 to 360.0 */
5803 XcmsFloat V; /* 0.0 to 100.0 */
5804 XcmsFloat C; /* 0.0 to 100.0 */
5805} XcmsTekHVC; /* TekHVC */
5806
5807
5808
5809typedef struct {
5810 XcmsFloat pad0;
5811 XcmsFloat pad1;
5812 XcmsFloat pad2;
5813 XcmsFloat pad3;
5814} XcmsPad; /* four doubles */
5815
5816 The device-dependent formats provided allow color specification
5817 in:
5818 * RGB Intensity (XcmsRGBi)
5819 * Red, green, and blue linear intensity values,
5820 floating-point values from 0.0 to 1.0, where 1.0 indicates
5821 full intensity, 0.5 half intensity, and so on.
5822 * RGB Device (XcmsRGB)
5823 * Red, green, and blue values appropriate for the specified
5824 output device. XcmsRGB values are of type unsigned short,
5825 scaled from 0 to 65535 inclusive, and are interchangeable
5826 with the red, green, and blue values in an XColor
5827 structure.
5828
5829 It is important to note that RGB Intensity values are not gamma
5830 corrected values. In contrast, RGB Device values generated as a
5831 result of converting color specifications are always gamma
5832 corrected, and RGB Device values acquired as a result of
5833 querying a colormap or passed in by the client are assumed by
5834 Xlib to be gamma corrected. The term RGB value in this manual
5835 always refers to an RGB Device value.
5836
5837Color Strings
5838
5839 Xlib provides a mechanism for using string names for colors. A
5840 color string may either contain an abstract color name or a
5841 numerical color specification. Color strings are
5842 case-insensitive.
5843
5844 Color strings are used in the following functions:
5845 * XAllocNamedColor
5846 * XcmsAllocNamedColor
5847 * XLookupColor
5848 * XcmsLookupColor
5849 * XParseColor
5850 * XStoreNamedColor
5851
5852 Xlib supports the use of abstract color names, for example, red
5853 or blue. A value for this abstract name is obtained by
5854 searching one or more color name databases. Xlib first searches
5855 zero or more client-side databases; the number, location, and
5856 content of these databases is implementation-dependent and
5857 might depend on the current locale. If the name is not found,
5858 Xlib then looks for the color in the X server's database. If
5859 the color name is not in the Host Portable Character Encoding,
5860 the result is implementation-dependent.
5861
5862 A numerical color specification consists of a color space name
5863 and a set of values in the following syntax:
5864
5865<color_space_name>:<value>/.../<value>
5866
5867 The following are examples of valid color strings.
5868
5869"CIEXYZ:0.3227/0.28133/0.2493"
5870"RGBi:1.0/0.0/0.0"
5871"rgb:00/ff/00"
5872"CIELuv:50.0/0.0/0.0"
5873
5874 The syntax and semantics of numerical specifications are given
5875 for each standard color space in the following sections.
5876
5877RGB Device String Specification
5878
5879 An RGB Device specification is identified by the prefix
5880 ``rgb:'' and conforms to the following syntax:
5881
5882rgb:<red>/<green>/<blue>
5883
5884 <red>, <green>, <blue> := h | hh | hhh | hhhh
5885 h := single hexadecimal digits (case insignificant)
5886
5887 Note that h indicates the value scaled in 4 bits, hh the value
5888 scaled in 8 bits, hhh the value scaled in 12 bits, and hhhh the
5889 value scaled in 16 bits, respectively.
5890
5891 Typical examples are the strings ``rgb:ea/75/52'' and
5892 ``rgb:ccc/320/320'', but mixed numbers of hexadecimal digit
5893 strings (``rgb:ff/a5/0'' and ``rgb:ccc/32/0'') are also
5894 allowed.
5895
5896 For backward compatibility, an older syntax for RGB Device is
5897 supported, but its continued use is not encouraged. The syntax
5898 is an initial sharp sign character followed by a numeric
5899 specification, in one of the following formats:
5900
5901
5902
5903#RGB (4 bits each)
5904#RRGGBB (8 bits each)
5905#RRRGGGBBB (12 bits each)
5906#RRRRGGGGBBBB (16 bits each)
5907
5908 The R, G, and B represent single hexadecimal digits. When fewer
5909 than 16 bits each are specified, they represent the most
5910 significant bits of the value (unlike the ``rgb:'' syntax, in
5911 which values are scaled). For example, the string ``#3a7'' is
5912 the same as ``#3000a0007000''.
5913
5914RGB Intensity String Specification
5915
5916 An RGB intensity specification is identified by the prefix
5917 ``rgbi:'' and conforms to the following syntax:
5918
5919rgbi:<red>/<green>/<blue>
5920
5921 Note that red, green, and blue are floating-point values
5922 between 0.0 and 1.0, inclusive. The input format for these
5923 values is an optional sign, a string of numbers possibly
5924 containing a decimal point, and an optional exponent field
5925 containing an E or e followed by a possibly signed integer
5926 string.
5927
5928Device-Independent String Specifications
5929
5930 The standard device-independent string specifications have the
5931 following syntax:
5932
5933CIEXYZ:<X>/<Y>/<Z>
5934CIEuvY:<u>/<v>/<Y>
5935CIExyY:<x>/<y>/<Y>
5936CIELab:<L>/<a>/<b>
5937CIELuv:<L>/<u>/<v>
5938TekHVC:<H>/<V>/<C>
5939
5940 All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
5941 floating-point values. The syntax for these values is an
5942 optional plus or minus sign, a string of digits possibly
5943 containing a decimal point, and an optional exponent field
5944 consisting of an ``E'' or ``e'' followed by an optional plus or
5945 minus followed by a string of digits.
5946
5947Color Conversion Contexts and Gamut Mapping
5948
5949 When Xlib converts device-independent color specifications into
5950 device-dependent specifications and vice versa, it uses
5951 knowledge about the color limitations of the screen hardware.
5952 This information, typically called the device profile, is
5953 available in a Color Conversion Context (CCC).
5954
5955 Because a specified color may be outside the color gamut of the
5956 target screen and the white point associated with the color
5957 specification may differ from the white point inherent to the
5958 screen, Xlib applies gamut mapping when it encounters certain
5959 conditions:
5960 * Gamut compression occurs when conversion of
5961 device-independent color specifications to device-dependent
5962 color specifications results in a color out of the target
5963 screen's gamut.
5964 * White adjustment occurs when the inherent white point of
5965 the screen differs from the white point assumed by the
5966 client.
5967
5968 Gamut handling methods are stored as callbacks in the CCC,
5969 which in turn are used by the color space conversion routines.
5970 Client data is also stored in the CCC for each callback. The
5971 CCC also contains the white point the client assumes to be
5972 associated with color specifications (that is, the Client White
5973 Point). The client can specify the gamut handling callbacks and
5974 client data as well as the Client White Point. Xlib does not
5975 preclude the X client from performing other forms of gamut
5976 handling (for example, gamut expansion); however, Xlib does not
5977 provide direct support for gamut handling other than white
5978 adjustment and gamut compression.
5979
5980 Associated with each colormap is an initial CCC transparently
5981 generated by Xlib. Therefore, when you specify a colormap as an
5982 argument to an Xlib function, you are indirectly specifying a
5983 CCC. There is a default CCC associated with each screen. Newly
5984 created CCCs inherit attributes from the default CCC, so the
5985 default CCC attributes can be modified to affect new CCCs.
5986
5987 Xcms functions in which gamut mapping can occur return Status
5988 and have specific status values defined for them, as follows:
5989 * XcmsFailure indicates that the function failed.
5990 * XcmsSuccess indicates that the function succeeded. In
5991 addition, if the function performed any color conversion,
5992 the colors did not need to be compressed.
5993 * XcmsSuccessWithCompression indicates the function performed
5994 color conversion and at least one of the colors needed to
5995 be compressed. The gamut compression method is determined
5996 by the gamut compression procedure in the CCC that is
5997 specified directly as a function argument or in the CCC
5998 indirectly specified by means of the colormap argument.
5999
6000Creating, Copying, and Destroying Colormaps
6001
6002 To create a colormap for a screen, use XCreateColormap.
6003
6004 Colormap XCreateColormap(Display *display, Window w, Visual
6005 *visual, int alloc);
6006
6007 display
6008
6009 Specifies the connection to the X server.
6010
6011 w
6012
6013 Specifies the window on whose screen you want to create a
6014 colormap.
6015
6016 visual
6017
6018 Specifies a visual type supported on the screen. If the visual
6019 type is not one supported by the screen, a BadMatch error
6020 results.
6021
6022 alloc
6023
6024 Specifies the colormap entries to be allocated. You can pass
6025 AllocNone or AllocAll.
6026
6027 The XCreateColormap function creates a colormap of the
6028 specified visual type for the screen on which the specified
6029 window resides and returns the colormap ID associated with it.
6030 Note that the specified window is only used to determine the
6031 screen.
6032
6033 The initial values of the colormap entries are undefined for
6034 the visual classes GrayScale, PseudoColor, and DirectColor. For
6035 StaticGray, StaticColor, and TrueColor, the entries have
6036 defined values, but those values are specific to the visual and
6037 are not defined by X. For StaticGray, StaticColor, and
6038 TrueColor, alloc must be AllocNone, or a BadMatch error
6039 results. For the other visual classes, if alloc is AllocNone,
6040 the colormap initially has no allocated entries, and clients
6041 can allocate them. For information about the visual types, see
6042 section 3.1.
6043
6044 If alloc is AllocAll, the entire colormap is allocated
6045 writable. The initial values of all allocated entries are
6046 undefined. For GrayScale and PseudoColor, the effect is as if
6047 an XAllocColorCells call returned all pixel values from zero to
6048 N - 1, where N is the colormap entries value in the specified
6049 visual. For DirectColor, the effect is as if an
6050 XAllocColorPlanes call returned a pixel value of zero and
6051 red_mask, green_mask, and blue_mask values containing the same
6052 bits as the corresponding masks in the specified visual.
6053 However, in all cases, none of these entries can be freed by
6054 using XFreeColors.
6055
6056 XCreateColormap can generate BadAlloc, BadMatch, BadValue, and
6057 BadWindow errors.
6058
6059 To create a new colormap when the allocation out of a
6060 previously shared colormap has failed because of resource
6061 exhaustion, use XCopyColormapAndFree.
6062
6063 Colormap XCopyColormapAndFree(Display *display, Colormap
6064 colormap);
6065
6066 display
6067
6068 Specifies the connection to the X server.
6069
6070 colormap
6071
6072 Specifies the colormap.
6073
6074 The XCopyColormapAndFree function creates a colormap of the
6075 same visual type and for the same screen as the specified
6076 colormap and returns the new colormap ID. It also moves all of
6077 the client's existing allocation from the specified colormap to
6078 the new colormap with their color values intact and their
6079 read-only or writable characteristics intact and frees those
6080 entries in the specified colormap. Color values in other
6081 entries in the new colormap are undefined. If the specified
6082 colormap was created by the client with alloc set to AllocAll,
6083 the new colormap is also created with AllocAll, all color
6084 values for all entries are copied from the specified colormap,
6085 and then all entries in the specified colormap are freed. If
6086 the specified colormap was not created by the client with
6087 AllocAll, the allocations to be moved are all those pixels and
6088 planes that have been allocated by the client using
6089 XAllocColor, XAllocNamedColor, XAllocColorCells, or
6090 XAllocColorPlanes and that have not been freed since they were
6091 allocated.
6092
6093 XCopyColormapAndFree can generate BadAlloc and BadColor errors.
6094
6095 To destroy a colormap, use XFreeColormap.
6096
6097 XFreeColormap(Display *display, Colormap colormap);
6098
6099 display
6100
6101 Specifies the connection to the X server.
6102
6103 colormap
6104
6105 Specifies the colormap that you want to destroy.
6106
6107 The XFreeColormap function deletes the association between the
6108 colormap resource ID and the colormap and frees the colormap
6109 storage. However, this function has no effect on the default
6110 colormap for a screen. If the specified colormap is an
6111 installed map for a screen, it is uninstalled (see
6112 XUninstallColormap). If the specified colormap is defined as
6113 the colormap for a window (by XCreateWindow,
6114 XSetWindowColormap, or XChangeWindowAttributes), XFreeColormap
6115 changes the colormap associated with the window to None and
6116 generates a ColormapNotify event. X does not define the colors
6117 displayed for a window with a colormap of None.
6118
6119 XFreeColormap can generate a BadColor error.
6120
6121Mapping Color Names to Values
6122
6123 To map a color name to an RGB value, use XLookupColor.
6124
6125 Status XLookupColor(Display *display, Colormap colormap, char
6126 *color_name, XColor *exact_def_return, XColor
6127 *screen_def_return);
6128
6129 display
6130
6131 Specifies the connection to the X server.
6132
6133 colormap
6134
6135 Specifies the colormap.
6136
6137 color_name
6138
6139 Specifies the color name string (for example, red) whose color
6140 definition structure you want returned.
6141
6142 exact_def_return
6143
6144 Returns the exact RGB values.
6145
6146 screen_def_return
6147
6148 Returns the closest RGB values provided by the hardware.
6149
6150 The XLookupColor function looks up the string name of a color
6151 with respect to the screen associated with the specified
6152 colormap. It returns both the exact color values and the
6153 closest values provided by the screen with respect to the
6154 visual type of the specified colormap. If the color name is not
6155 in the Host Portable Character Encoding, the result is
6156 implementation-dependent. Use of uppercase or lowercase does
6157 not matter. XLookupColor returns nonzero if the name is
6158 resolved; otherwise, it returns zero.
6159
6160 XLookupColor can generate a BadColor error.
6161
6162 To map a color name to the exact RGB value, use XParseColor.
6163
6164 Status XParseColor(Display *display, Colormap colormap, char
6165 *spec, XColor *exact_def_return);
6166
6167 display
6168
6169 Specifies the connection to the X server.
6170
6171 colormap
6172
6173 Specifies the colormap.
6174
6175 spec
6176
6177 Specifies the color name string; case is ignored.
6178
6179 exact_def_return
6180
6181 Returns the exact color value for later use and sets the DoRed,
6182 DoGreen, and DoBlue flags.
6183
6184 The XParseColor function looks up the string name of a color
6185 with respect to the screen associated with the specified
6186 colormap. It returns the exact color value. If the color name
6187 is not in the Host Portable Character Encoding, the result is
6188 implementation-dependent. Use of uppercase or lowercase does
6189 not matter. XParseColor returns nonzero if the name is
6190 resolved; otherwise, it returns zero.
6191
6192 XParseColor can generate a BadColor error.
6193
6194 To map a color name to a value in an arbitrary color space, use
6195 XcmsLookupColor.
6196
6197 Status XcmsLookupColor(Display *display, Colormap colormap,
6198 char *color_string, XcmsColor *color_exact_return, XcmsColor
6199 *color_screen_return, XcmsColorFormat result_format);
6200
6201 display
6202
6203 Specifies the connection to the X server.
6204
6205 colormap
6206
6207 Specifies the colormap.
6208
6209 color_string
6210
6211 Specifies the color string(St.
6212
6213 color_exact_return
6214
6215 Returns the color specification parsed from the color string or
6216 parsed from the corresponding string found in a color-name
6217 database.
6218
6219 color_screen_return
6220
6221 Returns the color that can be reproduced on the screen.
6222
6223 result_format
6224
6225 Specifies the color format for the returned color
6226 specifications (color_screen_return and color_exact_return
6227 arguments). If the format is XcmsUndefinedFormat and the color
6228 string contains a numerical color specification, the
6229 specification is returned in the format used in that numerical
6230 color specification. If the format is XcmsUndefinedFormat and
6231 the color string contains a color name, the specification is
6232 returned in the format used to store the color in the database.
6233
6234 The XcmsLookupColor function looks up the string name of a
6235 color with respect to the screen associated with the specified
6236 colormap. It returns both the exact color values and the
6237 closest values provided by the screen with respect to the
6238 visual type of the specified colormap. The values are returned
6239 in the format specified by result_format. If the color name is
6240 not in the Host Portable Character Encoding, the result is
6241 implementation-dependent. Use of uppercase or lowercase does
6242 not matter. XcmsLookupColor returns XcmsSuccess or
6243 XcmsSuccessWithCompression if the name is resolved; otherwise,
6244 it returns XcmsFailure. If XcmsSuccessWithCompression is
6245 returned, the color specification returned in
6246 color_screen_return is the result of gamut compression.
6247
6248Allocating and Freeing Color Cells
6249
6250 There are two ways of allocating color cells: explicitly as
6251 read-only entries, one pixel value at a time, or read/write,
6252 where you can allocate a number of color cells and planes
6253 simultaneously. A read-only cell has its RGB value set by the
6254 server. Read/write cells do not have defined colors initially;
6255 functions described in the next section must be used to store
6256 values into them. Although it is possible for any client to
6257 store values into a read/write cell allocated by another
6258 client, read/write cells normally should be considered private
6259 to the client that allocated them.
6260
6261 Read-only colormap cells are shared among clients. The server
6262 counts each allocation and freeing of the cell by clients. When
6263 the last client frees a shared cell, the cell is finally
6264 deallocated. If a single client allocates the same read-only
6265 cell multiple times, the server counts each such allocation,
6266 not just the first one.
6267
6268 To allocate a read-only color cell with an RGB value, use
6269 XAllocColor.
6270
6271 Status XAllocColor(Display *display, Colormap colormap, XColor
6272 *screen_in_out);
6273
6274 display
6275
6276 Specifies the connection to the X server.
6277
6278 colormap
6279
6280 Specifies the colormap.
6281
6282 screen_in_out
6283
6284 Specifies and returns the values actually used in the colormap.
6285
6286 The XAllocColor function allocates a read-only colormap entry
6287 corresponding to the closest RGB value supported by the
6288 hardware. XAllocColor returns the pixel value of the color
6289 closest to the specified RGB elements supported by the hardware
6290 and returns the RGB value actually used. The corresponding
6291 colormap cell is read-only. In addition, XAllocColor returns
6292 nonzero if it succeeded or zero if it failed. Multiple clients
6293 that request the same effective RGB value can be assigned the
6294 same read-only entry, thus allowing entries to be shared. When
6295 the last client deallocates a shared cell, it is deallocated.
6296 XAllocColor does not use or affect the flags in the XColor
6297 structure.
6298
6299 XAllocColor can generate a BadColor error. delim %%
6300
6301 To allocate a read-only color cell with a color in arbitrary
6302 format, use XcmsAllocColor.
6303
6304 Status XcmsAllocColor(Display *display, Colormap colormap,
6305 XcmsColor *color_in_out, XcmsColorFormat result_format);
6306
6307 display
6308
6309 Specifies the connection to the X server.
6310
6311 colormap
6312
6313 Specifies the colormap.
6314
6315 color_in_out
6316
6317 Specifies the color to allocate and returns the pixel and color
6318 that is actually used in the colormap.
6319
6320 result_format
6321
6322 Specifies the color format for the returned color
6323 specification.
6324
6325 The XcmsAllocColor function is similar to XAllocColor except
6326 the color can be specified in any format. The XcmsAllocColor
6327 function ultimately calls XAllocColor to allocate a read-only
6328 color cell (colormap entry) with the specified color.
6329 XcmsAllocColor first converts the color specified to an RGB
6330 value and then passes this to XAllocColor. XcmsAllocColor
6331 returns the pixel value of the color cell and the color
6332 specification actually allocated. This returned color
6333 specification is the result of converting the RGB value
6334 returned by XAllocColor into the format specified with the
6335 result_format argument. If there is no interest in a returned
6336 color specification, unnecessary computation can be bypassed if
6337 result_format is set to XcmsRGBFormat. The corresponding
6338 colormap cell is read-only. If this routine returns
6339 XcmsFailure, the color_in_out color specification is left
6340 unchanged.
6341
6342 XcmsAllocColor can generate a BadColor error.
6343
6344 To allocate a read-only color cell using a color name and
6345 return the closest color supported by the hardware in RGB
6346 format, use XAllocNamedColor.
6347
6348 Status XAllocNamedColor(Display *display, Colormap colormap,
6349 char *color_name, XColor *screen_def_return, XColor
6350 *exact_def_return);
6351
6352 display
6353
6354 Specifies the connection to the X server.
6355
6356 colormap
6357
6358 Specifies the colormap.
6359
6360 color_name
6361
6362 Specifies the color name string (for example, red) whose color
6363 definition structure you want returned.
6364
6365 screen_def_return
6366
6367 Returns the closest RGB values provided by the hardware.
6368
6369 exact_def_return
6370
6371 Returns the exact RGB values.
6372
6373 The XAllocNamedColor function looks up the named color with
6374 respect to the screen that is associated with the specified
6375 colormap. It returns both the exact database definition and the
6376 closest color supported by the screen. The allocated color cell
6377 is read-only. The pixel value is returned in screen_def_return.
6378 If the color name is not in the Host Portable Character
6379 Encoding, the result is implementation-dependent. Use of
6380 uppercase or lowercase does not matter. If screen_def_return
6381 and exact_def_return point to the same structure, the pixel
6382 field will be set correctly, but the color values are
6383 undefined. XAllocNamedColor returns nonzero if a cell is
6384 allocated; otherwise, it returns zero.
6385
6386 XAllocNamedColor can generate a BadColor error.
6387
6388 To allocate a read-only color cell using a color name and
6389 return the closest color supported by the hardware in an
6390 arbitrary format, use XcmsAllocNamedColor.
6391
6392 Status XcmsAllocNamedColor(Display *display, Colormap colormap,
6393 char *color_string, XcmsColor *color_screen_return, XcmsColor
6394 *color_exact_return, XcmsColorFormat result_format);
6395
6396 display
6397
6398 Specifies the connection to the X server.
6399
6400 colormap
6401
6402 Specifies the colormap.
6403
6404 color_string
6405
6406 Specifies the color string whose color definition structure is
6407 to be returned.
6408
6409 color_screen_return
6410
6411 Returns the pixel value of the color cell and color
6412 specification that actually is stored for that cell.
6413
6414 color_exact_return
6415
6416 Returns the color specification parsed from the color string or
6417 parsed from the corresponding string found in a color-name
6418 database.
6419
6420 result_format
6421
6422 Specifies the color format for the returned color
6423 specifications (color_screen_return and color_exact_return
6424 arguments). If the format is XcmsUndefinedFormat and the color
6425 string contains a numerical color specification, the
6426 specification is returned in the format used in that numerical
6427 color specification. If the format is XcmsUndefinedFormat and
6428 the color string contains a color name, the specification is
6429 returned in the format used to store the color in the database.
6430
6431 The XcmsAllocNamedColor function is similar to XAllocNamedColor
6432 except that the color returned can be in any format specified.
6433 This function ultimately calls XAllocColor to allocate a
6434 read-only color cell with the color specified by a color
6435 string. The color string is parsed into an XcmsColor structure
6436 (see XcmsLookupColor), converted to an RGB value, and finally
6437 passed to XAllocColor. If the color name is not in the Host
6438 Portable Character Encoding, the result is
6439 implementation-dependent. Use of uppercase or lowercase does
6440 not matter.
6441
6442 This function returns both the color specification as a result
6443 of parsing (exact specification) and the actual color
6444 specification stored (screen specification). This screen
6445 specification is the result of converting the RGB value
6446 returned by XAllocColor into the format specified in
6447 result_format. If there is no interest in a returned color
6448 specification, unnecessary computation can be bypassed if
6449 result_format is set to XcmsRGBFormat. If color_screen_return
6450 and color_exact_return point to the same structure, the pixel
6451 field will be set correctly, but the color values are
6452 undefined.
6453
6454 XcmsAllocNamedColor can generate a BadColor error.
6455
6456 To allocate read/write color cell and color plane combinations
6457 for a PseudoColor model, use XAllocColorCells.
6458
6459 Status XAllocColorCells(Display *display, Colormap colormap,
6460 Bool contig, unsigned long plane_masks_return[], unsigned int
6461 nplanes, unsigned long pixels_return[], unsigned int npixels);
6462
6463 display
6464
6465 Specifies the connection to the X server.
6466
6467 colormap
6468
6469 Specifies the colormap.
6470
6471 contig
6472
6473 Specifies a Boolean value that indicates whether the planes
6474 must be contiguous.
6475
6476 plane_mask_return
6477
6478 Returns an array of plane masks.
6479
6480 nplanes
6481
6482 Specifies the number of plane masks that are to be returned in
6483 the plane masks array.
6484
6485 pixels_return
6486
6487 Returns an array of pixel values.
6488
6489 npixels
6490
6491 Specifies the number of pixel values that are to be returned in
6492 the pixels_return array.
6493
6494 The XAllocColorCells function allocates read/write color cells.
6495 The number of colors must be positive and the number of planes
6496 nonnegative, or a BadValue error results. If ncolors and
6497 nplanes are requested, then ncolors pixels and nplane plane
6498 masks are returned. No mask will have any bits set to 1 in
6499 common with any other mask or with any of the pixels. By ORing
6500 together each pixel with zero or more masks, ncolors ×
6501 2^nplanes distinct pixels can be produced. All of these are
6502 allocated writable by the request. For GrayScale or
6503 PseudoColor, each mask has exactly one bit set to 1. For
6504 DirectColor, each has exactly three bits set to 1. If contig is
6505 True and if all masks are ORed together, a single contiguous
6506 set of bits set to 1 will be formed for GrayScale or
6507 PseudoColor and three contiguous sets of bits set to 1 (one
6508 within each pixel subfield) for DirectColor. The RGB values of
6509 the allocated entries are undefined. XAllocColorCells returns
6510 nonzero if it succeeded or zero if it failed.
6511
6512 XAllocColorCells can generate BadColor and BadValue errors.
6513
6514 To allocate read/write color resources for a DirectColor model,
6515 use XAllocColorPlanes.
6516
6517 Status XAllocColorPlanes(Display *display, Colormap colormap,
6518 Bool contig, unsigned long pixels_return[], int ncolors, int
6519 nreds, int ngreens, int nblues, unsigned long *rmask_return,
6520 unsigned long *gmask_return, unsigned long *bmask_return);
6521
6522 display
6523
6524 Specifies the connection to the X server.
6525
6526 colormap
6527
6528 Specifies the colormap.
6529
6530 contig
6531
6532 Specifies a Boolean value that indicates whether the planes
6533 must be contiguous.
6534
6535 pixels_return
6536
6537 Returns an array of pixel values. XAllocColorPlanes returns the
6538 pixel values in this array.
6539
6540 ncolors
6541
6542 Specifies the number of pixel values that are to be returned in
6543 the pixels_return array.
6544
6545 nreds
6546
6547 ngreens
6548
6549 nblues
6550
6551 Specify the number of red, green, and blue planes. The value
6552 you pass must be nonnegative.
6553
6554 rmask_return
6555
6556 gmask_return
6557
6558 bmask_return
6559
6560 Return bit masks for the red, green, and blue planes.
6561
6562 The specified ncolors must be positive; and nreds, ngreens, and
6563 nblues must be nonnegative, or a BadValue error results. If
6564 ncolors colors, nreds reds, ngreens greens, and nblues blues
6565 are requested, ncolors pixels are returned; and the masks have
6566 nreds, ngreens, and nblues bits set to 1, respectively. If
6567 contig is True, each mask will have a contiguous set of bits
6568 set to 1. No mask will have any bits set to 1 in common with
6569 any other mask or with any of the pixels. For DirectColor, each
6570 mask will lie within the corresponding pixel subfield. By ORing
6571 together subsets of masks with each pixel value, ncolors ×
6572 2^(nreds+ngreens+nblues) distinct pixel values can be produced.
6573 All of these are allocated by the request. However, in the
6574 colormap, there are only ncolors × 2^nreds independent red
6575 entries, ncolors × 2^ngreens independent green entries, and
6576 ncolors × 2^nblues independent blue entries. This is true even
6577 for PseudoColor. When the colormap entry of a pixel value is
6578 changed (using XStoreColors, XStoreColor, or XStoreNamedColor),
6579 the pixel is decomposed according to the masks, and the
6580 corresponding independent entries are updated.
6581 XAllocColorPlanes returns nonzero if it succeeded or zero if it
6582 failed.
6583
6584 XAllocColorPlanes can generate BadColor and BadValue errors.
6585
6586 To free colormap cells, use XFreeColors.
6587
6588 XFreeColors(Display *display, Colormap colormap, unsigned long
6589 pixels[], int npixels, unsigned long planes);
6590
6591 display
6592
6593 Specifies the connection to the X server.
6594
6595 colormap
6596
6597 Specifies the colormap.
6598
6599 pixels
6600
6601 Specifies an array of pixel values that map to the cells in the
6602 specified colormap.
6603
6604 npixels
6605
6606 Specifies the number of pixels.
6607
6608 planes
6609
6610 Specifies the planes you want to free.
6611
6612 The XFreeColors function frees the cells represented by pixels
6613 whose values are in the pixels array. The planes argument
6614 should not have any bits set to 1 in common with any of the
6615 pixels. The set of all pixels is produced by ORing together
6616 subsets of the planes argument with the pixels. The request
6617 frees all of these pixels that were allocated by the client
6618 (using XAllocColor, XAllocNamedColor, XAllocColorCells, and
6619 XAllocColorPlanes). Note that freeing an individual pixel
6620 obtained from XAllocColorPlanes may not actually allow it to be
6621 reused until all of its related pixels are also freed.
6622 Similarly, a read-only entry is not actually freed until it has
6623 been freed by all clients, and if a client allocates the same
6624 read-only entry multiple times, it must free the entry that
6625 many times before the entry is actually freed.
6626
6627 All specified pixels that are allocated by the client in the
6628 colormap are freed, even if one or more pixels produce an
6629 error. If a specified pixel is not a valid index into the
6630 colormap, a BadValue error results. If a specified pixel is not
6631 allocated by the client (that is, is unallocated or is only
6632 allocated by another client) or if the colormap was created
6633 with all entries writable (by passing AllocAll to
6634 XCreateColormap), a BadAccess error results. If more than one
6635 pixel is in error, the one that gets reported is arbitrary.
6636
6637 XFreeColors can generate BadAccess, BadColor, and BadValue
6638 errors.
6639
6640Modifying and Querying Colormap Cells
6641
6642 To store an RGB value in a single colormap cell, use
6643 XStoreColor.
6644
6645 XStoreColor(Display *display, Colormap colormap, XColor
6646 *color);
6647
6648 display
6649
6650 Specifies the connection to the X server.
6651
6652 colormap
6653
6654 Specifies the colormap.
6655
6656 color
6657
6658 Specifies the pixel and RGB values.
6659
6660 The XStoreColor function changes the colormap entry of the
6661 pixel value specified in the pixel member of the XColor
6662 structure. You specified this value in the pixel member of the
6663 XColor structure. This pixel value must be a read/write cell
6664 and a valid index into the colormap. If a specified pixel is
6665 not a valid index into the colormap, a BadValue error results.
6666 XStoreColor also changes the red, green, and/or blue color
6667 components. You specify which color components are to be
6668 changed by setting DoRed, DoGreen, and/or DoBlue in the flags
6669 member of the XColor structure. If the colormap is an installed
6670 map for its screen, the changes are visible immediately.
6671
6672 XStoreColor can generate BadAccess, BadColor, and BadValue
6673 errors.
6674
6675 To store multiple RGB values in multiple colormap cells, use
6676 XStoreColors.
6677
6678 XStoreColors(Display *display, Colormap colormap, XColor
6679 color[], int ncolors);
6680
6681 display
6682
6683 Specifies the connection to the X server.
6684
6685 colormap
6686
6687 Specifies the colormap.
6688
6689 color
6690
6691 Specifies an array of color definition structures to be stored.
6692
6693 ncolors
6694
6695 Specifies the number of XColor structures in the color
6696 definition array.
6697
6698 The XStoreColors function changes the colormap entries of the
6699 pixel values specified in the pixel members of the XColor
6700 structures. You specify which color components are to be
6701 changed by setting DoRed, DoGreen, and/or DoBlue in the flags
6702 member of the XColor structures. If the colormap is an
6703 installed map for its screen, the changes are visible
6704 immediately. XStoreColors changes the specified pixels if they
6705 are allocated writable in the colormap by any client, even if
6706 one or more pixels generates an error. If a specified pixel is
6707 not a valid index into the colormap, a BadValue error results.
6708 If a specified pixel either is unallocated or is allocated
6709 read-only, a BadAccess error results. If more than one pixel is
6710 in error, the one that gets reported is arbitrary.
6711
6712 XStoreColors can generate BadAccess, BadColor, and BadValue
6713 errors.
6714
6715 To store a color of arbitrary format in a single colormap cell,
6716 use XcmsStoreColor.
6717
6718 Status XcmsStoreColor(Display *display, Colormap colormap,
6719 XcmsColor *color);
6720
6721 display
6722
6723 Specifies the connection to the X server.
6724
6725 colormap
6726
6727 Specifies the colormap.
6728
6729 color
6730
6731 Specifies the color cell and the color to store. Values
6732 specified in this XcmsColor structure remain unchanged on
6733 return.
6734
6735 The XcmsStoreColor function converts the color specified in the
6736 XcmsColor structure into RGB values. It then uses this RGB
6737 specification in an XColor structure, whose three flags (DoRed,
6738 DoGreen, and DoBlue) are set, in a call to XStoreColor to
6739 change the color cell specified by the pixel member of the
6740 XcmsColor structure. This pixel value must be a valid index for
6741 the specified colormap, and the color cell specified by the
6742 pixel value must be a read/write cell. If the pixel value is
6743 not a valid index, a BadValue error results. If the color cell
6744 is unallocated or is allocated read-only, a BadAccess error
6745 results. If the colormap is an installed map for its screen,
6746 the changes are visible immediately.
6747
6748 Note that XStoreColor has no return value; therefore, an
6749 XcmsSuccess return value from this function indicates that the
6750 conversion to RGB succeeded and the call to XStoreColor was
6751 made. To obtain the actual color stored, use XcmsQueryColor.
6752 Because of the screen's hardware limitations or gamut
6753 compression, the color stored in the colormap may not be
6754 identical to the color specified.
6755
6756 XcmsStoreColor can generate BadAccess, BadColor, and BadValue
6757 errors.
6758
6759 To store multiple colors of arbitrary format in multiple
6760 colormap cells, use XcmsStoreColors.
6761
6762 Status XcmsStoreColors(Display *display, Colormap colormap,
6763 XcmsColor colors[], int ncolors, Bool
6764 compression_flags_return[]);
6765
6766 display
6767
6768 Specifies the connection to the X server.
6769
6770 colormap
6771
6772 Specifies the colormap.
6773
6774 colors
6775
6776 Specifies the color specification array of XcmsColor
6777 structures, each specifying a color cell and the color to store
6778 in that cell. Values specified in the array remain unchanged
6779 upon return.
6780
6781 ncolors
6782
6783 Specifies the number of XcmsColor structures in the
6784 color-specification array.
6785
6786 compression_flags_return
6787
6788 Returns an array of Boolean values indicating compression
6789 status. If a non-NULL pointer is supplied, each element of the
6790 array is set to True if the corresponding color was compressed
6791 and False otherwise. Pass NULL if the compression status is not
6792 useful.
6793
6794 The XcmsStoreColors function converts the colors specified in
6795 the array of XcmsColor structures into RGB values and then uses
6796 these RGB specifications in XColor structures, whose three
6797 flags (DoRed, DoGreen, and DoBlue) are set, in a call to
6798 XStoreColors to change the color cells specified by the pixel
6799 member of the corresponding XcmsColor structure. Each pixel
6800 value must be a valid index for the specified colormap, and the
6801 color cell specified by each pixel value must be a read/write
6802 cell. If a pixel value is not a valid index, a BadValue error
6803 results. If a color cell is unallocated or is allocated
6804 read-only, a BadAccess error results. If more than one pixel is
6805 in error, the one that gets reported is arbitrary. If the
6806 colormap is an installed map for its screen, the changes are
6807 visible immediately.
6808
6809 Note that XStoreColors has no return value; therefore, an
6810 XcmsSuccess return value from this function indicates that
6811 conversions to RGB succeeded and the call to XStoreColors was
6812 made. To obtain the actual colors stored, use XcmsQueryColors.
6813 Because of the screen's hardware limitations or gamut
6814 compression, the colors stored in the colormap may not be
6815 identical to the colors specified.
6816
6817 XcmsStoreColors can generate BadAccess, BadColor, and BadValue
6818 errors.
6819
6820 To store a color specified by name in a single colormap cell,
6821 use XStoreNamedColor.
6822
6823 XStoreNamedColor(Display *display, Colormap colormap, char
6824 *color, unsigned long pixel, int flags);
6825
6826 display
6827
6828 Specifies the connection to the X server.
6829
6830 colormap
6831
6832 Specifies the colormap.
6833
6834 color
6835
6836 Specifies the color name string (for example, red).
6837
6838 pixel
6839
6840 Specifies the entry in the colormap.
6841
6842 flags
6843
6844 Specifies which red, green, and blue components are set.
6845
6846 The XStoreNamedColor function looks up the named color with
6847 respect to the screen associated with the colormap and stores
6848 the result in the specified colormap. The pixel argument
6849 determines the entry in the colormap. The flags argument
6850 determines which of the red, green, and blue components are
6851 set. You can set this member to the bitwise inclusive OR of the
6852 bits DoRed, DoGreen, and DoBlue. If the color name is not in
6853 the Host Portable Character Encoding, the result is
6854 implementation-dependent. Use of uppercase or lowercase does
6855 not matter. If the specified pixel is not a valid index into
6856 the colormap, a BadValue error results. If the specified pixel
6857 either is unallocated or is allocated read-only, a BadAccess
6858 error results.
6859
6860 XStoreNamedColor can generate BadAccess, BadColor, BadName, and
6861 BadValue errors.
6862
6863 The XQueryColor and XQueryColors functions take pixel values in
6864 the pixel member of XColor structures and store in the
6865 structures the RGB values for those pixels from the specified
6866 colormap. The values returned for an unallocated entry are
6867 undefined. These functions also set the flags member in the
6868 XColor structure to all three colors. If a pixel is not a valid
6869 index into the specified colormap, a BadValue error results. If
6870 more than one pixel is in error, the one that gets reported is
6871 arbitrary.
6872
6873 To query the RGB value of a single colormap cell, use
6874 XQueryColor.
6875
6876 XQueryColor(Display *display, Colormap colormap, XColor
6877 *def_in_out);
6878
6879 display
6880
6881 Specifies the connection to the X server.
6882
6883 colormap
6884
6885 Specifies the colormap.
6886
6887 def_in_out
6888
6889 Specifies and returns the RGB values for the pixel specified in
6890 the structure.
6891
6892 The XQueryColor function returns the current RGB value for the
6893 pixel in the XColor structure and sets the DoRed, DoGreen, and
6894 DoBlue flags.
6895
6896 XQueryColor can generate BadColor and BadValue errors.
6897
6898 To query the RGB values of multiple colormap cells, use
6899 XQueryColors.
6900
6901 XQueryColors(Display *display, Colormap colormap, XColor
6902 defs_in_out[], int ncolors);
6903
6904 display
6905
6906 Specifies the connection to the X server.
6907
6908 colormap
6909
6910 Specifies the colormap.
6911
6912 defs_in_out
6913
6914 Specifies and returns an array of color definition structures
6915 for the pixel specified in the structure.
6916
6917 ncolors
6918
6919 Specifies the number of XColor structures in the color
6920 definition array.
6921
6922 The XQueryColors function returns the RGB value for each pixel
6923 in each XColor structure and sets the DoRed, DoGreen, and
6924 DoBlue flags in each structure.
6925
6926 XQueryColors can generate BadColor and BadValue errors.
6927
6928 To query the color of a single colormap cell in an arbitrary
6929 format, use XcmsQueryColor.
6930
6931 Status XcmsQueryColor(Display *display, Colormap colormap,
6932 XcmsColor *color_in_out, XcmsColorFormat result_format);
6933
6934 display
6935
6936 Specifies the connection to the X server.
6937
6938 colormap
6939
6940 Specifies the colormap.
6941
6942 color_in_out
6943
6944 Specifies the pixel member that indicates the color cell to
6945 query. The color specification stored for the color cell is
6946 returned in this XcmsColor structure.
6947
6948 result_format
6949
6950 Specifies the color format for the returned color
6951 specification.
6952
6953 The XcmsQueryColor function obtains the RGB value for the pixel
6954 value in the pixel member of the specified XcmsColor structure
6955 and then converts the value to the target format as specified
6956 by the result_format argument. If the pixel is not a valid
6957 index in the specified colormap, a BadValue error results.
6958
6959 XcmsQueryColor can generate BadColor and BadValue errors.
6960
6961 To query the color of multiple colormap cells in an arbitrary
6962 format, use XcmsQueryColors.
6963
6964 Status XcmsQueryColors(Display *display, Colormap colormap,
6965 XcmsColor colors_in_out[], unsigned int ncolors,
6966 XcmsColorFormat result_format);
6967
6968 display
6969
6970 Specifies the connection to the X server.
6971
6972 colormap
6973
6974 Specifies the colormap.
6975
6976 colors_in_out
6977
6978 Specifies an array of XcmsColor structures, each pixel member
6979 indicating the color cell to query. The color specifications
6980 for the color cells are returned in these structures.
6981
6982 ncolors
6983
6984 Specifies the number of XcmsColor structures in the
6985 color-specification array.
6986
6987 result_format
6988
6989 Specifies the color format for the returned color
6990 specification.
6991
6992 The XcmsQueryColors function obtains the RGB values for pixel
6993 values in the pixel members of XcmsColor structures and then
6994 converts the values to the target format as specified by the
6995 result_format argument. If a pixel is not a valid index into
6996 the specified colormap, a BadValue error results. If more than
6997 one pixel is in error, the one that gets reported is arbitrary.
6998
6999 XcmsQueryColors can generate BadColor and BadValue errors.
7000
7001Color Conversion Context Functions
7002
7003 This section describes functions to create, modify, and query
7004 Color Conversion Contexts (CCCs).
7005
7006 Associated with each colormap is an initial CCC transparently
7007 generated by Xlib. Therefore, when you specify a colormap as an
7008 argument to a function, you are indirectly specifying a CCC.
7009 The CCC attributes that can be modified by the X client are:
7010 * Client White Point
7011 * Gamut compression procedure and client data
7012 * White point adjustment procedure and client data
7013
7014 The initial values for these attributes are implementation
7015 specific. The CCC attributes for subsequently created CCCs can
7016 be defined by changing the CCC attributes of the default CCC.
7017 There is a default CCC associated with each screen.
7018
7019Getting and Setting the Color Conversion Context of a Colormap
7020
7021 To obtain the CCC associated with a colormap, use
7022 XcmsCCCOfColormap.
7023
7024 XcmsCCC XcmsCCCOfColormap(Display *display, Colormap colormap);
7025
7026 display
7027
7028 Specifies the connection to the X server.
7029
7030 colormap
7031
7032 Specifies the colormap.
7033
7034 The XcmsCCCOfColormap function returns the CCC associated with
7035 the specified colormap. Once obtained, the CCC attributes can
7036 be queried or modified. Unless the CCC associated with the
7037 specified colormap is changed with XcmsSetCCCOfColormap, this
7038 CCC is used when the specified colormap is used as an argument
7039 to color functions.
7040
7041 To change the CCC associated with a colormap, use
7042 XcmsSetCCCOfColormap.
7043
7044 XcmsCCC XcmsSetCCCOfColormap(Display *display, Colormap
7045 colormap, XcmsCCC ccc);
7046
7047 display
7048
7049 Specifies the connection to the X server.
7050
7051 colormap
7052
7053 Specifies the colormap.
7054
7055 ccc
7056
7057 Specifies the CCC.
7058
7059 The XcmsSetCCCOfColormap function changes the CCC associated
7060 with the specified colormap. It returns the CCC previously
7061 associated with the colormap. If they are not used again in the
7062 application, CCCs should be freed by calling XcmsFreeCCC.
7063 Several colormaps may share the same CCC without restriction;
7064 this includes the CCCs generated by Xlib with each colormap.
7065 Xlib, however, creates a new CCC with each new colormap.
7066
7067Obtaining the Default Color Conversion Context
7068
7069 You can change the default CCC attributes for subsequently
7070 created CCCs by changing the CCC attributes of the default CCC.
7071 A default CCC is associated with each screen.
7072
7073 To obtain the default CCC for a screen, use XcmsDefaultCCC.
7074
7075 XcmsCCC XcmsDefaultCCC(Display *display, int screen_number);
7076
7077 display
7078
7079 Specifies the connection to the X server.
7080
7081 screen_number
7082
7083 Specifies the appropriate screen number on the host server.
7084
7085 The XcmsDefaultCCC function returns the default CCC for the
7086 specified screen. Its visual is the default visual of the
7087 screen. Its initial gamut compression and white point
7088 adjustment procedures as well as the associated client data are
7089 implementation specific.
7090
7091Color Conversion Context Macros
7092
7093 Applications should not directly modify any part of the
7094 XcmsCCC. The following lists the C language macros, their
7095 corresponding function equivalents for other language bindings,
7096 and what data they both can return.
7097
7098 DisplayOfCCC(XcmsCCC ccc);
7099
7100 Display *XcmsDisplayOfCCC(XcmsCCC ccc);
7101
7102 ccc
7103
7104 Specifies the CCC.
7105
7106 Both return the display associated with the specified CCC.
7107
7108 VisualOfCCC(XcmsCCC ccc);
7109
7110 Visual *XcmsVisualOfCCC(XcmsCCC ccc);
7111
7112 ccc
7113
7114 Specifies the CCC.
7115
7116 Both return the visual associated with the specified CCC.
7117
7118 ScreenNumberOfCCC(XcmsCCC ccc);
7119
7120 int XcmsScreenNumberOfCCC(XcmsCCC ccc);
7121
7122 ccc
7123
7124 Specifies the CCC.
7125
7126 Both return the number of the screen associated with the
7127 specified CCC.
7128
7129 ScreenWhitePointOfCCC(XcmsCCC ccc);
7130
7131 XcmsColor XcmsScreenWhitePointOfCCC(XcmsCCC ccc);
7132
7133 ccc
7134
7135 Specifies the CCC.
7136
7137 Both return the white point of the screen associated with the
7138 specified CCC.
7139
7140 ClientWhitePointOfCCC(XcmsCCC ccc);
7141
7142 XcmsColor *XcmsClientWhitePointOfCCC(XcmsCCC ccc);
7143
7144 ccc
7145
7146 Specifies the CCC.
7147
7148 Both return the Client White Point of the specified CCC.
7149
7150Modifying Attributes of a Color Conversion Context
7151
7152 To set the Client White Point in the CCC, use
7153 XcmsSetWhitePoint.
7154
7155 Status XcmsSetWhitePoint(XcmsCCC ccc, XcmsColor *color);
7156
7157 ccc
7158
7159 Specifies the CCC.
7160
7161 color
7162
7163 Specifies the new Client White Point.
7164
7165 The XcmsSetWhitePoint function changes the Client White Point
7166 in the specified CCC. Note that the pixel member is ignored and
7167 that the color specification is left unchanged upon return. The
7168 format for the new white point must be XcmsCIEXYZFormat,
7169 XcmsCIEuvYFormat, XcmsCIExyYFormat, or XcmsUndefinedFormat. If
7170 the color argument is NULL, this function sets the format
7171 component of the Client White Point specification to
7172 XcmsUndefinedFormat, indicating that the Client White Point is
7173 assumed to be the same as the Screen White Point.
7174
7175 This function returns nonzero status if the format for the new
7176 white point is valid; otherwise, it returns zero.
7177
7178 To set the gamut compression procedure and corresponding client
7179 data in a specified CCC, use XcmsSetCompressionProc.
7180
7181 XcmsCompressionProc XcmsSetCompressionProc(XcmsCCC ccc,
7182 XcmsCompressionProc compression_proc, XPointer client_data);
7183
7184 ccc
7185
7186 Specifies the CCC.
7187
7188 compression_proc
7189
7190 Specifies the gamut compression procedure that is to be applied
7191 when a color lies outside the screen's color gamut. If NULL is
7192 specified and a function using this CCC must convert a color
7193 specification to a device-dependent format and encounters a
7194 color that lies outside the screen's color gamut, that function
7195 will return XcmsFailure.
7196
7197 client_data
7198
7199 Specifies client data for gamut compression procedure or NULL.
7200
7201 The XcmsSetCompressionProc function first sets the gamut
7202 compression procedure and client data in the specified CCC with
7203 the newly specified procedure and client data and then returns
7204 the old procedure.
7205
7206 To set the white point adjustment procedure and corresponding
7207 client data in a specified CCC, use XcmsSetWhiteAdjustProc.
7208
7209 XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc(XcmsCCC ccc,
7210 XcmsWhiteAdjustProc white_adjust_proc, XPointer client_data);
7211
7212 ccc
7213
7214 Specifies the CCC.
7215
7216 white_adjust_proc
7217
7218 Specifies the white point adjustment procedure.
7219
7220 client_data
7221
7222 Specifies client data for white point adjustment procedure or
7223 NULL.
7224
7225 The XcmsSetWhiteAdjustProc function first sets the white point
7226 adjustment procedure and client data in the specified CCC with
7227 the newly specified procedure and client data and then returns
7228 the old procedure.
7229
7230Creating and Freeing a Color Conversion Context
7231
7232 You can explicitly create a CCC within your application by
7233 calling XcmsCreateCCC. These created CCCs can then be used by
7234 those functions that explicitly call for a CCC argument. Old
7235 CCCs that will not be used by the application should be freed
7236 using XcmsFreeCCC.
7237
7238 To create a CCC, use XcmsCreateCCC.
7239
7240 XcmsCCC XcmsCreateCCC(Display *display, int screen_number,
7241 Visual *visual, XcmsColor *client_white_point,
7242 XcmsCompressionProc compression_proc, XPointer
7243 compression_client_data, XcmsWhiteAdjustProc white_adjust_proc,
7244 XPointer white_adjust_client_data);
7245
7246 display
7247
7248 Specifies the connection to the X server.
7249
7250 screen_number
7251
7252 Specifies the appropriate screen number on the host server.
7253
7254 visual
7255
7256 Specifies the visual type.
7257
7258 client_white_point
7259
7260 Specifies the Client White Point. If NULL is specified, the
7261 Client White Point is to be assumed to be the same as the
7262 Screen White Point. Note that the pixel member is ignored.
7263
7264 compression_proc
7265
7266 Specifies the gamut compression procedure that is to be applied
7267 when a color lies outside the screen's color gamut. If NULL is
7268 specified and a function using this CCC must convert a color
7269 specification to a device-dependent format and encounters a
7270 color that lies outside the screen's color gamut, that function
7271 will return XcmsFailure.
7272
7273 compression_client_data
7274
7275 Specifies client data for use by the gamut compression
7276 procedure or NULL.
7277
7278 white_adjust_proc
7279
7280 Specifies the white adjustment procedure that is to be applied
7281 when the Client White Point differs from the Screen White
7282 Point. NULL indicates that no white point adjustment is
7283 desired.
7284
7285 white_adjust_client_data
7286
7287 Specifies client data for use with the white point adjustment
7288 procedure or NULL.
7289
7290 The XcmsCreateCCC function creates a CCC for the specified
7291 display, screen, and visual.
7292
7293 To free a CCC, use XcmsFreeCCC.
7294
7295 void XcmsFreeCCC(XcmsCCC ccc);
7296
7297 ccc
7298
7299 Specifies the CCC.
7300
7301 The XcmsFreeCCC function frees the memory used for the
7302 specified CCC. Note that default CCCs and those currently
7303 associated with colormaps are ignored.
7304
7305Converting between Color Spaces
7306
7307 To convert an array of color specifications in arbitrary color
7308 formats to a single destination format, use XcmsConvertColors.
7309
7310 Status XcmsConvertColors(XcmsCCC ccc, XcmsColor
7311 colors_in_out[], unsigned int ncolors, XcmsColorFormat
7312 target_format, Bool compression_flags_return[]);
7313
7314 ccc
7315
7316 Specifies the CCC. If conversion is between device-independent
7317 color spaces only (for example, TekHVC to CIELuv), the CCC is
7318 necessary only to specify the Client White Point.
7319
7320 colors_in_out
7321
7322 Specifies an array of color specifications. Pixel members are
7323 ignored and remain unchanged upon return.
7324
7325 ncolors
7326
7327 Specifies the number of XcmsColor structures in the
7328 color-specification array.
7329
7330 target_format
7331
7332 Specifies the target color specification format.
7333
7334 compression_flags_return
7335
7336 Returns an array of Boolean values indicating compression
7337 status. If a non-NULL pointer is supplied, each element of the
7338 array is set to True if the corresponding color was compressed
7339 and False otherwise. Pass NULL if the compression status is not
7340 useful.
7341
7342 The XcmsConvertColors function converts the color
7343 specifications in the specified array of XcmsColor structures
7344 from their current format to a single target format, using the
7345 specified CCC. When the return value is XcmsFailure, the
7346 contents of the color specification array are left unchanged.
7347
7348 The array may contain a mixture of color specification formats
7349 (for example, 3 CIE XYZ, 2 CIE Luv, and so on). When the array
7350 contains both device-independent and device-dependent color
7351 specifications and the target_format argument specifies a
7352 device-dependent format (for example, XcmsRGBiFormat,
7353 XcmsRGBFormat), all specifications are converted to CIE XYZ
7354 format and then to the target device-dependent format.
7355
7356Callback Functions
7357
7358 This section describes the gamut compression and white point
7359 adjustment callbacks.
7360
7361 The gamut compression procedure specified in the CCC is called
7362 when an attempt to convert a color specification from
7363 XcmsCIEXYZ to a device-dependent format (typically XcmsRGBi)
7364 results in a color that lies outside the screen's color gamut.
7365 If the gamut compression procedure requires client data, this
7366 data is passed via the gamut compression client data in the
7367 CCC.
7368
7369 During color specification conversion between
7370 device-independent and device-dependent color spaces, if a
7371 white point adjustment procedure is specified in the CCC, it is
7372 triggered when the Client White Point and Screen White Point
7373 differ. If required, the client data is obtained from the CCC.
7374
7375Prototype Gamut Compression Procedure
7376
7377 The gamut compression callback interface must adhere to the
7378 following:
7379
7380 typedef Status(*XcmsCompressionProc)(XcmsCCC ccc, XcmsColor
7381 colors_in_out[], unsigned int ncolors, unsigned int index, Bool
7382 compression_flags_return[]);
7383
7384 ccc
7385
7386 Specifies the CCC.
7387
7388 colors_in_out
7389
7390 Specifies an array of color specifications. Pixel members
7391 should be ignored and must remain unchanged upon return.
7392
7393 ncolors
7394
7395 Specifies the number of XcmsColor structures in the
7396 color-specification array.
7397
7398 index
7399
7400 Specifies the index into the array of XcmsColor structures for
7401 the encountered color specification that lies outside the
7402 screen's color gamut. Valid values are 0 (for the first
7403 element) to ncolors - 1.
7404
7405 compression_flags_return
7406
7407 Returns an array of Boolean values for indicating compression
7408 status. If a non-NULL pointer is supplied and a color at a
7409 given index is compressed, then True should be stored at the
7410 corresponding index in this array; otherwise, the array should
7411 not be modified.
7412
7413 When implementing a gamut compression procedure, consider the
7414 following rules and assumptions:
7415 * The gamut compression procedure can attempt to compress one
7416 or multiple specifications at a time.
7417 * When called, elements 0 to index - 1 in the color
7418 specification array can be assumed to fall within the
7419 screen's color gamut. In addition, these color
7420 specifications are already in some device-dependent format
7421 (typically XcmsRGBi). If any modifications are made to
7422 these color specifications, they must be in their initial
7423 device-dependent format upon return.
7424 * When called, the element in the color specification array
7425 specified by the index argument contains the color
7426 specification outside the screen's color gamut encountered
7427 by the calling routine. In addition, this color
7428 specification can be assumed to be in XcmsCIEXYZ. Upon
7429 return, this color specification must be in XcmsCIEXYZ.
7430 * When called, elements from index to ncolors - 1 in the
7431 color specification array may or may not fall within the
7432 screen's color gamut. In addition, these color
7433 specifications can be assumed to be in XcmsCIEXYZ. If any
7434 modifications are made to these color specifications, they
7435 must be in XcmsCIEXYZ upon return.
7436 * The color specifications passed to the gamut compression
7437 procedure have already been adjusted to the Screen White
7438 Point. This means that at this point the color
7439 specification's white point is the Screen White Point.
7440 * If the gamut compression procedure uses a
7441 device-independent color space not initially accessible for
7442 use in the color management system, use XcmsAddColorSpace
7443 to ensure that it is added.
7444
7445Supplied Gamut Compression Procedures
7446
7447 The following equations are useful in describing gamut
7448 compression functions: delim %%
7449
7450%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
7451
7452%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right
7453]%
7454
7455%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
7456
7457%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right
7458]%
7459
7460 The gamut compression callback procedures provided by Xlib are
7461 as follows:
7462 * XcmsCIELabClipL
7463 * This brings the encountered out-of-gamut color
7464 specification into the screen's color gamut by reducing or
7465 increasing CIE metric lightness (L*) in the CIE L*a*b*
7466 color space until the color is within the gamut. If the
7467 Psychometric Chroma of the color specification is beyond
7468 maximum for the Psychometric Hue Angle, then while
7469 maintaining the same Psychometric Hue Angle, the color will
7470 be clipped to the CIE L*a*b* coordinates of maximum
7471 Psychometric Chroma. See XcmsCIELabQueryMaxC. No client
7472 data is necessary.
7473 * XcmsCIELabClipab
7474 * This brings the encountered out-of-gamut color
7475 specification into the screen's color gamut by reducing
7476 Psychometric Chroma, while maintaining Psychometric Hue
7477 Angle, until the color is within the gamut. No client data
7478 is necessary.
7479 * XcmsCIELabClipLab
7480 * This brings the encountered out-of-gamut color
7481 specification into the screen's color gamut by replacing it
7482 with CIE L*a*b* coordinates that fall within the color
7483 gamut while maintaining the original Psychometric Hue Angle
7484 and whose vector to the original coordinates is the
7485 shortest attainable. No client data is necessary.
7486 * XcmsCIELuvClipL
7487 * This brings the encountered out-of-gamut color
7488 specification into the screen's color gamut by reducing or
7489 increasing CIE metric lightness (L*) in the CIE L*u*v*
7490 color space until the color is within the gamut. If the
7491 Psychometric Chroma of the color specification is beyond
7492 maximum for the Psychometric Hue Angle, then, while
7493 maintaining the same Psychometric Hue Angle, the color will
7494 be clipped to the CIE L*u*v* coordinates of maximum
7495 Psychometric Chroma. See XcmsCIELuvQueryMaxC. No client
7496 data is necessary.
7497 * XcmsCIELuvClipuv
7498 * This brings the encountered out-of-gamut color
7499 specification into the screen's color gamut by reducing
7500 Psychometric Chroma, while maintaining Psychometric Hue
7501 Angle, until the color is within the gamut. No client data
7502 is necessary.
7503 * XcmsCIELuvClipLuv
7504 * This brings the encountered out-of-gamut color
7505 specification into the screen's color gamut by replacing it
7506 with CIE L*u*v* coordinates that fall within the color
7507 gamut while maintaining the original Psychometric Hue Angle
7508 and whose vector to the original coordinates is the
7509 shortest attainable. No client data is necessary.
7510 * XcmsTekHVCClipV
7511 * This brings the encountered out-of-gamut color
7512 specification into the screen's color gamut by reducing or
7513 increasing the Value dimension in the TekHVC color space
7514 until the color is within the gamut. If Chroma of the color
7515 specification is beyond maximum for the particular Hue,
7516 then, while maintaining the same Hue, the color will be
7517 clipped to the Value and Chroma coordinates that represent
7518 maximum Chroma for that particular Hue. No client data is
7519 necessary.
7520 * XcmsTekHVCClipC
7521 * This brings the encountered out-of-gamut color
7522 specification into the screen's color gamut by reducing the
7523 Chroma dimension in the TekHVC color space until the color
7524 is within the gamut. No client data is necessary.
7525 * XcmsTekHVCClipVC
7526 * This brings the encountered out-of-gamut color
7527 specification into the screen's color gamut by replacing it
7528 with TekHVC coordinates that fall within the color gamut
7529 while maintaining the original Hue and whose vector to the
7530 original coordinates is the shortest attainable. No client
7531 data is necessary.
7532
7533Prototype White Point Adjustment Procedure
7534
7535 The white point adjustment procedure interface must adhere to
7536 the following:
7537
7538 typedef Status (*XcmsWhiteAdjustProc)(XcmsCCC ccc, XcmsColor
7539 *initial_white_point, XcmsColor *target_white_point,
7540 XcmsColorFormat target_format, XcmsColor colors_in_out[],
7541 unsigned int ncolors, Bool compression_flags_return[]);
7542
7543 ccc
7544
7545 Specifies the CCC.
7546
7547 initial_white_point
7548
7549 Specifies the initial white point.
7550
7551 target_white_point
7552
7553 Specifies the target white point.
7554
7555 target_format
7556
7557 Specifies the target color specification format.
7558
7559 colors_in_out
7560
7561 Specifies an array of color specifications. Pixel members
7562 should be ignored and must remain unchanged upon return.
7563
7564 ncolors
7565
7566 Specifies the number of XcmsColor structures in the
7567 color-specification array.
7568
7569 compression_flags_return
7570
7571 Returns an array of Boolean values for indicating compression
7572 status. If a non-NULL pointer is supplied and a color at a
7573 given index is compressed, then True should be stored at the
7574 corresponding index in this array; otherwise, the array should
7575 not be modified.
7576
7577Supplied White Point Adjustment Procedures
7578
7579 White point adjustment procedures provided by Xlib are as
7580 follows:
7581 * XcmsCIELabWhiteShiftColors
7582 * This uses the CIE L*a*b* color space for adjusting the
7583 chromatic character of colors to compensate for the
7584 chromatic differences between the source and destination
7585 white points. This procedure simply converts the color
7586 specifications to XcmsCIELab using the source white point
7587 and then converts to the target specification format using
7588 the destination's white point. No client data is necessary.
7589 * XcmsCIELuvWhiteShiftColors
7590 * This uses the CIE L*u*v* color space for adjusting the
7591 chromatic character of colors to compensate for the
7592 chromatic differences between the source and destination
7593 white points. This procedure simply converts the color
7594 specifications to XcmsCIELuv using the source white point
7595 and then converts to the target specification format using
7596 the destination's white point. No client data is necessary.
7597 * XcmsTekHVCWhiteShiftColors
7598 * This uses the TekHVC color space for adjusting the
7599 chromatic character of colors to compensate for the
7600 chromatic differences between the source and destination
7601 white points. This procedure simply converts the color
7602 specifications to XcmsTekHVC using the source white point
7603 and then converts to the target specification format using
7604 the destination's white point. An advantage of this
7605 procedure over those previously described is an attempt to
7606 minimize hue shift. No client data is necessary.
7607
7608 From an implementation point of view, these white point
7609 adjustment procedures convert the color specifications to a
7610 device-independent but white-point-dependent color space (for
7611 example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one white point
7612 and then converting those specifications to the target color
7613 space using another white point. In other words, the
7614 specification goes in the color space with one white point but
7615 comes out with another white point, resulting in a chromatic
7616 shift based on the chromatic displacement between the initial
7617 white point and target white point. The CIE color spaces that
7618 are assumed to be white-point-independent are CIE u'v'Y, CIE
7619 XYZ, and CIE xyY. When developing a custom white point
7620 adjustment procedure that uses a device-independent color space
7621 not initially accessible for use in the color management
7622 system, use XcmsAddColorSpace to ensure that it is added.
7623
7624 As an example, if the CCC specifies a white point adjustment
7625 procedure and if the Client White Point and Screen White Point
7626 differ, the XcmsAllocColor function will use the white point
7627 adjustment procedure twice:
7628 * Once to convert to XcmsRGB
7629 * A second time to convert from XcmsRGB
7630
7631 For example, assume the specification is in XcmsCIEuvY and the
7632 adjustment procedure is XcmsCIELuvWhiteShiftColors. During
7633 conversion to XcmsRGB, the call to XcmsAllocColor results in
7634 the following series of color specification conversions:
7635 * From XcmsCIEuvY to XcmsCIELuv using the Client White Point
7636 * From XcmsCIELuv to XcmsCIEuvY using the Screen White Point
7637 * From XcmsCIEuvY to XcmsCIEXYZ (CIE u'v'Y and XYZ are
7638 white-point-independent color spaces)
7639 * From XcmsCIEXYZ to XcmsRGBi
7640 * From XcmsRGBi to XcmsRGB
7641
7642 The resulting RGB specification is passed to XAllocColor, and
7643 the RGB specification returned by XAllocColor is converted back
7644 to XcmsCIEuvY by reversing the color conversion sequence.
7645
7646Gamut Querying Functions
7647
7648 This section describes the gamut querying functions that Xlib
7649 provides. These functions allow the client to query the
7650 boundary of the screen's color gamut in terms of the CIE
7651 L*a*b*, CIE L*u*v*, and TekHVC color spaces. Functions are also
7652 provided that allow you to query the color specification of:
7653 * White (full-intensity red, green, and blue)
7654 * Red (full-intensity red while green and blue are zero)
7655 * Green (full-intensity green while red and blue are zero)
7656 * Blue (full-intensity blue while red and green are zero)
7657 * Black (zero-intensity red, green, and blue)
7658
7659 The white point associated with color specifications passed to
7660 and returned from these gamut querying functions is assumed to
7661 be the Screen White Point. This is a reasonable assumption,
7662 because the client is trying to query the screen's color gamut.
7663
7664 The following naming convention is used for the Max and Min
7665 functions:
7666
7667Xcms<color_space>QueryMax<dimensions>
7668
7669Xcms<color_space>QueryMin<dimensions>
7670
7671 The <dimensions> consists of a letter or letters that identify
7672 the dimensions of the color space that are not fixed. For
7673 example, XcmsTekHVCQueryMaxC is given a fixed Hue and Value for
7674 which maximum Chroma is found.
7675
7676Red, Green, and Blue Queries
7677
7678 To obtain the color specification for black (zero-intensity
7679 red, green, and blue), use XcmsQueryBlack.
7680
7681 Status XcmsQueryBlack(XcmsCCC ccc, XcmsColorFormat
7682 target_format, XcmsColor *color_return);
7683
7684 ccc
7685
7686 Specifies the CCC. The CCC's Client White Point and white point
7687 adjustment procedures are ignored.
7688
7689 target_format
7690
7691 Specifies the target color specification format.
7692
7693 color_return
7694
7695 Returns the color specification in the specified target format
7696 for zero-intensity red, green, and blue. The white point
7697 associated with the returned color specification is the Screen
7698 White Point. The value returned in the pixel member is
7699 undefined.
7700
7701 The XcmsQueryBlack function returns the color specification in
7702 the specified target format for zero-intensity red, green, and
7703 blue.
7704
7705 To obtain the color specification for blue (full-intensity blue
7706 while red and green are zero), use XcmsQueryBlue.
7707
7708 Status XcmsQueryBlue(XcmsCCC ccc, XcmsColorFormat
7709 target_format, XcmsColor *color_return);
7710
7711 ccc
7712
7713 Specifies the CCC. The CCC's Client White Point and white point
7714 adjustment procedures are ignored.
7715
7716 target_format
7717
7718 Specifies the target color specification format.
7719
7720 color_return
7721
7722 Returns the color specification in the specified target format
7723 for full-intensity blue while red and green are zero. The white
7724 point associated with the returned color specification is the
7725 Screen White Point. The value returned in the pixel member is
7726 undefined.
7727
7728 The XcmsQueryBlue function returns the color specification in
7729 the specified target format for full-intensity blue while red
7730 and green are zero.
7731
7732 To obtain the color specification for green (full-intensity
7733 green while red and blue are zero), use XcmsQueryGreen.
7734
7735 Status XcmsQueryGreen(XcmsCCC ccc, XcmsColorFormat
7736 target_format, XcmsColor *color_return);
7737
7738 ccc
7739
7740 Specifies the CCC. The CCC's Client White Point and white point
7741 adjustment procedures are ignored.
7742
7743 target_format
7744
7745 Specifies the target color specification format.
7746
7747 color_return
7748
7749 Returns the color specification in the specified target format
7750 for full-intensity green while red and blue are zero. The white
7751 point associated with the returned color specification is the
7752 Screen White Point. The value returned in the pixel member is
7753 undefined.
7754
7755 The XcmsQueryGreen function returns the color specification in
7756 the specified target format for full-intensity green while red
7757 and blue are zero.
7758
7759 To obtain the color specification for red (full-intensity red
7760 while green and blue are zero), use XcmsQueryRed.
7761
7762 Status XcmsQueryRed(XcmsCCC ccc, XcmsColorFormat target_format,
7763 XcmsColor *color_return);
7764
7765 ccc
7766
7767 Specifies the CCC. The CCC's Client White Point and white point
7768 adjustment procedures are ignored.
7769
7770 target_format
7771
7772 Specifies the target color specification format.
7773
7774 color_return
7775
7776 Returns the color specification in the specified target format
7777 for full-intensity red while green and blue are zero. The white
7778 point associated with the returned color specification is the
7779 Screen White Point. The value returned in the pixel member is
7780 undefined.
7781
7782 The XcmsQueryRed function returns the color specification in
7783 the specified target format for full-intensity red while green
7784 and blue are zero.
7785
7786 To obtain the color specification for white (full-intensity
7787 red, green, and blue), use XcmsQueryWhite.
7788
7789 Status XcmsQueryWhite(XcmsCCC ccc, XcmsColorFormat
7790 target_format, XcmsColor *color_return);
7791
7792 ccc
7793
7794 Specifies the CCC. The CCC's Client White Point and white point
7795 adjustment procedures are ignored.
7796
7797 target_format
7798
7799 Specifies the target color specification format.
7800
7801 color_return
7802
7803 Returns the color specification in the specified target format
7804 for full-intensity red, green, and blue. The white point
7805 associated with the returned color specification is the Screen
7806 White Point. The value returned in the pixel member is
7807 undefined.
7808
7809 The XcmsQueryWhite function returns the color specification in
7810 the specified target format for full-intensity red, green, and
7811 blue.
7812
7813CIELab Queries
7814
7815 The following equations are useful in describing the CIELab
7816 query functions: delim %%
7817
7818%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
7819
7820%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right
7821]%
7822
7823 To obtain the CIE L*a*b* coordinates of maximum Psychometric
7824 Chroma for a given Psychometric Hue Angle and CIE metric
7825 lightness (L*), use XcmsCIELabQueryMaxC.
7826
7827 Status XcmsCIELabQueryMaxC(XcmsCCC ccc, XcmsFloat hue_angle,
7828 XcmsFloat L_star, XcmsColor *color_return);
7829
7830 ccc
7831
7832 Specifies the CCC. The CCC's Client White Point and white point
7833 adjustment procedures are ignored.
7834
7835 hue_angle
7836
7837 Specifies the hue angle (in degrees) at which to find maximum
7838 chroma.
7839
7840 L_star
7841
7842 Specifies the lightness (L*) at which to find maximum chroma.
7843
7844 color_return
7845
7846 Returns the CIE L*a*b* coordinates of maximum chroma
7847 displayable by the screen for the given hue angle and
7848 lightness. The white point associated with the returned color
7849 specification is the Screen White Point. The value returned in
7850 the pixel member is undefined.
7851
7852 The XcmsCIELabQueryMaxC function, given a hue angle and
7853 lightness, finds the point of maximum chroma displayable by the
7854 screen. It returns this point in CIE L*a*b* coordinates.
7855
7856 To obtain the CIE L*a*b* coordinates of maximum CIE metric
7857 lightness (L*) for a given Psychometric Hue Angle and
7858 Psychometric Chroma, use XcmsCIELabQueryMaxL.
7859
7860 Status XcmsCIELabQueryMaxL(XcmsCCC ccc, XcmsFloat hue_angle,
7861 XcmsFloat chroma, XcmsColor *color_return);
7862
7863 ccc
7864
7865 Specifies the CCC. The CCC's Client White Point and white point
7866 adjustment procedures are ignored.
7867
7868 hue_angle
7869
7870 Specifies the hue angle (in degrees) at which to find maximum
7871 lightness.
7872
7873 chroma
7874
7875 Specifies the chroma at which to find maximum lightness.
7876
7877 color_return
7878
7879 Returns the CIE L*a*b* coordinates of maximum lightness
7880 displayable by the screen for the given hue angle and chroma.
7881 The white point associated with the returned color
7882 specification is the Screen White Point. The value returned in
7883 the pixel member is undefined.
7884
7885 The XcmsCIELabQueryMaxL function, given a hue angle and chroma,
7886 finds the point in CIE L*a*b* color space of maximum lightness
7887 (L*) displayable by the screen. It returns this point in CIE
7888 L*a*b* coordinates. An XcmsFailure return value usually
7889 indicates that the given chroma is beyond maximum for the given
7890 hue angle.
7891
7892 To obtain the CIE L*a*b* coordinates of maximum Psychometric
7893 Chroma for a given Psychometric Hue Angle, use
7894 XcmsCIELabQueryMaxLC.
7895
7896 Status XcmsCIELabQueryMaxLC(XcmsCCC ccc, XcmsFloat hue_angle,
7897 XcmsColor *color_return);
7898
7899 ccc
7900
7901 Specifies the CCC. The CCC's Client White Point and white point
7902 adjustment procedures are ignored.
7903
7904 hue_angle
7905
7906 Specifies the hue angle (in degrees) at which to find maximum
7907 chroma.
7908
7909 color_return
7910
7911 Returns the CIE L*a*b* coordinates of maximum chroma
7912 displayable by the screen for the given hue angle. The white
7913 point associated with the returned color specification is the
7914 Screen White Point. The value returned in the pixel member is
7915 undefined.
7916
7917 The XcmsCIELabQueryMaxLC function, given a hue angle, finds the
7918 point of maximum chroma displayable by the screen. It returns
7919 this point in CIE L*a*b* coordinates.
7920
7921 To obtain the CIE L*a*b* coordinates of minimum CIE metric
7922 lightness (L*) for a given Psychometric Hue Angle and
7923 Psychometric Chroma, use XcmsCIELabQueryMinL.
7924
7925 Status XcmsCIELabQueryMinL(XcmsCCC ccc, XcmsFloat hue_angle,
7926 XcmsFloat chroma, XcmsColor *color_return);
7927
7928 ccc
7929
7930 Specifies the CCC. The CCC's Client White Point and white point
7931 adjustment procedures are ignored.
7932
7933 hue_angle
7934
7935 Specifies the hue angle (in degrees) at which to find minimum
7936 lightness.
7937
7938 chroma
7939
7940 Specifies the chroma at which to find minimum lightness.
7941
7942 color_return
7943
7944 Returns the CIE L*a*b* coordinates of minimum lightness
7945 displayable by the screen for the given hue angle and chroma.
7946 The white point associated with the returned color
7947 specification is the Screen White Point. The value returned in
7948 the pixel member is undefined.
7949
7950 The XcmsCIELabQueryMinL function, given a hue angle and chroma,
7951 finds the point of minimum lightness (L*) displayable by the
7952 screen. It returns this point in CIE L*a*b* coordinates. An
7953 XcmsFailure return value usually indicates that the given
7954 chroma is beyond maximum for the given hue angle.
7955
7956CIELuv Queries
7957
7958 The following equations are useful in describing the CIELuv
7959 query functions: delim %%
7960
7961%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
7962
7963%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right
7964]%
7965
7966 To obtain the CIE L*u*v* coordinates of maximum Psychometric
7967 Chroma for a given Psychometric Hue Angle and CIE metric
7968 lightness (L*), use XcmsCIELuvQueryMaxC.
7969
7970 Status XcmsCIELuvQueryMaxC(XcmsCCC ccc, XcmsFloat hue_angle,
7971 XcmsFloat L_star, XcmsColor *color_return);
7972
7973 ccc
7974
7975 Specifies the CCC. The CCC's Client White Point and white point
7976 adjustment procedures are ignored.
7977
7978 hue_angle
7979
7980 Specifies the hue angle (in degrees) at which to find maximum
7981 chroma.
7982
7983 L_star
7984
7985 Specifies the lightness (L*) at which to find maximum chroma.
7986
7987 color_return
7988
7989 Returns the CIE L*u*v* coordinates of maximum chroma
7990 displayable by the screen for the given hue angle and
7991 lightness. The white point associated with the returned color
7992 specification is the Screen White Point. The value returned in
7993 the pixel member is undefined.
7994
7995 The XcmsCIELuvQueryMaxC function, given a hue angle and
7996 lightness, finds the point of maximum chroma displayable by the
7997 screen. It returns this point in CIE L*u*v* coordinates.
7998
7999 To obtain the CIE L*u*v* coordinates of maximum CIE metric
8000 lightness (L*) for a given Psychometric Hue Angle and
8001 Psychometric Chroma, use XcmsCIELuvQueryMaxL.
8002
8003 Status XcmsCIELuvQueryMaxL(XcmsCCC ccc, XcmsFloat hue_angle,
8004 XcmsFloat chroma, XcmsColor *color_return);
8005
8006 ccc
8007
8008 Specifies the CCC. The CCC's Client White Point and white point
8009 adjustment procedures are ignored.
8010
8011 hue_angle
8012
8013 Specifies the hue angle (in degrees) at which to find maximum
8014 lightness.
8015
8016 L_star
8017
8018 Specifies the lightness (L*) at which to find maximum
8019 lightness.
8020
8021 color_return
8022
8023 Returns the CIE L*u*v* coordinates of maximum lightness
8024 displayable by the screen for the given hue angle and chroma.
8025 The white point associated with the returned color
8026 specification is the Screen White Point. The value returned in
8027 the pixel member is undefined.
8028
8029 The XcmsCIELuvQueryMaxL function, given a hue angle and chroma,
8030 finds the point in CIE L*u*v* color space of maximum lightness
8031 (L*) displayable by the screen. It returns this point in CIE
8032 L*u*v* coordinates. An XcmsFailure return value usually
8033 indicates that the given chroma is beyond maximum for the given
8034 hue angle.
8035
8036 To obtain the CIE L*u*v* coordinates of maximum Psychometric
8037 Chroma for a given Psychometric Hue Angle, use
8038 XcmsCIELuvQueryMaxLC.
8039
8040 Status XcmsCIELuvQueryMaxLC(XcmsCCC ccc, XcmsFloat hue_angle,
8041 XcmsColor *color_return);
8042
8043 ccc
8044
8045 Specifies the CCC. The CCC's Client White Point and white point
8046 adjustment procedures are ignored.
8047
8048 hue_angle
8049
8050 Specifies the hue angle (in degrees) at which to find maximum
8051 chroma.
8052
8053 color_return
8054
8055 Returns the CIE L*u*v* coordinates of maximum chroma
8056 displayable by the screen for the given hue angle. The white
8057 point associated with the returned color specification is the
8058 Screen White Point. The value returned in the pixel member is
8059 undefined.
8060
8061 The XcmsCIELuvQueryMaxLC function, given a hue angle, finds the
8062 point of maximum chroma displayable by the screen. It returns
8063 this point in CIE L*u*v* coordinates.
8064
8065 To obtain the CIE L*u*v* coordinates of minimum CIE metric
8066 lightness (L*) for a given Psychometric Hue Angle and
8067 Psychometric Chroma, use XcmsCIELuvQueryMinL.
8068
8069 Status XcmsCIELuvQueryMinL(XcmsCCC ccc, XcmsFloat hue_angle,
8070 XcmsFloat chroma, XcmsColor *color_return);
8071
8072 ccc
8073
8074 Specifies the CCC. The CCC's Client White Point and white point
8075 adjustment procedures are ignored.
8076
8077 hue_angle
8078
8079 Specifies the hue angle (in degrees) at which to find minimum
8080 lightness.
8081
8082 chroma
8083
8084 Specifies the chroma at which to find minimum lightness.
8085
8086 color_return
8087
8088 Returns the CIE L*u*v* coordinates of minimum lightness
8089 displayable by the screen for the given hue angle and chroma.
8090 The white point associated with the returned color
8091 specification is the Screen White Point. The value returned in
8092 the pixel member is undefined.
8093
8094 The XcmsCIELuvQueryMinL function, given a hue angle and chroma,
8095 finds the point of minimum lightness (L*) displayable by the
8096 screen. It returns this point in CIE L*u*v* coordinates. An
8097 XcmsFailure return value usually indicates that the given
8098 chroma is beyond maximum for the given hue angle.
8099
8100TekHVC Queries
8101
8102 To obtain the maximum Chroma for a given Hue and Value, use
8103 XcmsTekHVCQueryMaxC.
8104
8105 Status XcmsTekHVCQueryMaxC(XcmsCCC ccc, XcmsFloat hue,
8106 XcmsFloat value, XcmsColor *color_return);
8107
8108 ccc
8109
8110 Specifies the CCC. The CCC's Client White Point and white point
8111 adjustment procedures are ignored.
8112
8113 hue
8114
8115 Specifies the Hue in which to find the maximum Chroma.
8116
8117 value
8118
8119 Specifies the Value in which to find the maximum Chroma.
8120
8121 color_return
8122
8123 Returns the maximum Chroma along with the actual Hue and Value
8124 at which the maximum Chroma was found. The white point
8125 associated with the returned color specification is the Screen
8126 White Point. The value returned in the pixel member is
8127 undefined.
8128
8129 The XcmsTekHVCQueryMaxC function, given a Hue and Value,
8130 determines the maximum Chroma in TekHVC color space displayable
8131 by the screen. It returns the maximum Chroma along with the
8132 actual Hue and Value at which the maximum Chroma was found.
8133
8134 To obtain the maximum Value for a given Hue and Chroma, use
8135 XcmsTekHVCQueryMaxV.
8136
8137 Status XcmsTekHVCQueryMaxV(XcmsCCC ccc, XcmsFloat hue,
8138 XcmsFloat chroma, XcmsColor *color_return);
8139
8140 ccc
8141
8142 Specifies the CCC. The CCC's Client White Point and white point
8143 adjustment procedures are ignored.
8144
8145 hue
8146
8147 Specifies the Hue in which to find the maximum Value.
8148
8149 chroma
8150
8151 Specifies the chroma at which to find maximum Value.
8152
8153 color_return
8154
8155 Returns the maximum Value along with the Hue and Chroma at
8156 which the maximum Value was found. The white point associated
8157 with the returned color specification is the Screen White
8158 Point. The value returned in the pixel member is undefined.
8159
8160 The XcmsTekHVCQueryMaxV function, given a Hue and Chroma,
8161 determines the maximum Value in TekHVC color space displayable
8162 by the screen. It returns the maximum Value and the actual Hue
8163 and Chroma at which the maximum Value was found.
8164
8165 To obtain the maximum Chroma and Value at which it is reached
8166 for a specified Hue, use XcmsTekHVCQueryMaxVC.
8167
8168 Status XcmsTekHVCQueryMaxVC(XcmsCCC ccc, XcmsFloat hue,
8169 XcmsColor *color_return);
8170
8171 ccc
8172
8173 Specifies the CCC. The CCC's Client White Point and white point
8174 adjustment procedures are ignored.
8175
8176 hue
8177
8178 Specifies the Hue in which to find the maximum Chroma.
8179
8180 color_return
8181
8182 Returns the color specification in XcmsTekHVC for the maximum
8183 Chroma, the Value at which that maximum Chroma is reached, and
8184 the actual Hue at which the maximum Chroma was found. The white
8185 point associated with the returned color specification is the
8186 Screen White Point. The value returned in the pixel member is
8187 undefined.
8188
8189 The XcmsTekHVCQueryMaxVC function, given a Hue, determines the
8190 maximum Chroma in TekHVC color space displayable by the screen
8191 and the Value at which that maximum Chroma is reached. It
8192 returns the maximum Chroma, the Value at which that maximum
8193 Chroma is reached, and the actual Hue for which the maximum
8194 Chroma was found.
8195
8196 To obtain a specified number of TekHVC specifications such that
8197 they contain maximum Values for a specified Hue and the Chroma
8198 at which the maximum Values are reached, use
8199 XcmsTekHVCQueryMaxVSamples.
8200
8201 Status XcmsTekHVCQueryMaxVSamples(XcmsCCC ccc, XcmsFloat hue,
8202 XcmsColor colors_return[], unsigned int nsamples);
8203
8204 ccc
8205
8206 Specifies the CCC. The CCC's Client White Point and white point
8207 adjustment procedures are ignored.
8208
8209 hue
8210
8211 Specifies the Hue for maximum Chroma/Value samples.
8212
8213 nsamples
8214
8215 Specifies the number of samples.
8216
8217 colors_return
8218
8219 Returns nsamples of color specifications in XcmsTekHVC such
8220 that the Chroma is the maximum attainable for the Value and
8221 Hue. The white point associated with the returned color
8222 specification is the Screen White Point. The value returned in
8223 the pixel member is undefined.
8224
8225 The XcmsTekHVCQueryMaxVSamples returns nsamples of maximum
8226 Value, the Chroma at which that maximum Value is reached, and
8227 the actual Hue for which the maximum Chroma was found. These
8228 sample points may then be used to plot the maximum Value/Chroma
8229 boundary of the screen's color gamut for the specified Hue in
8230 TekHVC color space.
8231
8232 To obtain the minimum Value for a given Hue and Chroma, use
8233 XcmsTekHVCQueryMinV.
8234
8235 Status XcmsTekHVCQueryMinV(XcmsCCC ccc, XcmsFloat hue,
8236 XcmsFloat chroma, XcmsColor *color_return);
8237
8238 ccc
8239
8240 Specifies the CCC. The CCC's Client White Point and white point
8241 adjustment procedures are ignored.
8242
8243 hue
8244
8245 Specifies the Hue in which to find the minimum Value.
8246
8247 value
8248
8249 Specifies the Value in which to find the minimum Value.
8250
8251 color_return
8252
8253 Returns the minimum Value and the actual Hue and Chroma at
8254 which the minimum Value was found. The white point associated
8255 with the returned color specification is the Screen White
8256 Point. The value returned in the pixel member is undefined.
8257
8258 The XcmsTekHVCQueryMinV function, given a Hue and Chroma,
8259 determines the minimum Value in TekHVC color space displayable
8260 by the screen. It returns the minimum Value and the actual Hue
8261 and Chroma at which the minimum Value was found.
8262
8263Color Management Extensions
8264
8265 The Xlib color management facilities can be extended in two
8266 ways:
8267 * Device-Independent Color Spaces
8268 * Device-independent color spaces that are derivable to CIE
8269 XYZ space can be added using the XcmsAddColorSpace
8270 function.
8271 * Color Characterization Function Set
8272 * A Color Characterization Function Set consists of
8273 device-dependent color spaces and their functions that
8274 convert between these color spaces and the CIE XYZ color
8275 space, bundled together for a specific class of output
8276 devices. A function set can be added using the
8277 XcmsAddFunctionSet function.
8278
8279Color Spaces
8280
8281 The CIE XYZ color space serves as the hub for all conversions
8282 between device-independent and device-dependent color spaces.
8283 Therefore, the knowledge to convert an XcmsColor structure to
8284 and from CIE XYZ format is associated with each color space.
8285 For example, conversion from CIE L*u*v* to RGB requires the
8286 knowledge to convert from CIE L*u*v* to CIE XYZ and from CIE
8287 XYZ to RGB. This knowledge is stored as an array of functions
8288 that, when applied in series, will convert the XcmsColor
8289 structure to or from CIE XYZ format. This color specification
8290 conversion mechanism facilitates the addition of color spaces.
8291
8292 Of course, when converting between only device-independent
8293 color spaces or only device-dependent color spaces, shortcuts
8294 are taken whenever possible. For example, conversion from
8295 TekHVC to CIE L*u*v* is performed by intermediate conversion to
8296 CIE u*v*Y and then to CIE L*u*v*, thus bypassing conversion
8297 between CIE u*v*Y and CIE XYZ.
8298
8299Adding Device-Independent Color Spaces
8300
8301 To add a device-independent color space, use XcmsAddColorSpace.
8302
8303 Status XcmsAddColorSpace(XcmsColorSpace *color_space);
8304
8305 color_space
8306
8307 Specifies the device-independent color space to add.
8308
8309 The XcmsAddColorSpace function makes a device-independent color
8310 space (actually an XcmsColorSpace structure) accessible by the
8311 color management system. Because format values for unregistered
8312 color spaces are assigned at run time, they should be treated
8313 as private to the client. If references to an unregistered
8314 color space must be made outside the client (for example,
8315 storing color specifications in a file using the unregistered
8316 color space), then reference should be made by color space
8317 prefix (see XcmsFormatOfPrefix and XcmsPrefixOfFormat).
8318
8319 If the XcmsColorSpace structure is already accessible in the
8320 color management system, XcmsAddColorSpace returns XcmsSuccess.
8321
8322 Note that added XcmsColorSpaces must be retained for reference
8323 by Xlib.
8324
8325Querying Color Space Format and Prefix
8326
8327 To obtain the format associated with the color space associated
8328 with a specified color string prefix, use XcmsFormatOfPrefix.
8329
8330 XcmsColorFormat XcmsFormatOfPrefix(char *prefix);
8331
8332 prefix
8333
8334 Specifies the string that contains the color space prefix.
8335
8336 The XcmsFormatOfPrefix function returns the format for the
8337 specified color space prefix (for example, the string
8338 ``CIEXYZ''). The prefix is case-insensitive. If the color space
8339 is not accessible in the color management system,
8340 XcmsFormatOfPrefix returns XcmsUndefinedFormat.
8341
8342 To obtain the color string prefix associated with the color
8343 space specified by a color format, use XcmsPrefixOfFormat.
8344
8345 char *XcmsPrefixOfFormat(XcmsColorFormat format);
8346
8347 format
8348
8349 Specifies the color specification format.
8350
8351 The XcmsPrefixOfFormat function returns the string prefix
8352 associated with the color specification encoding specified by
8353 the format argument. Otherwise, if no encoding is found, it
8354 returns NULL. The returned string must be treated as read-only.
8355
8356Creating Additional Color Spaces
8357
8358 Color space specific information necessary for color space
8359 conversion and color string parsing is stored in an
8360 XcmsColorSpace structure. Therefore, a new structure containing
8361 this information is required for each additional color space.
8362 In the case of device-independent color spaces, a handle to
8363 this new structure (that is, by means of a global variable) is
8364 usually made accessible to the client program for use with the
8365 XcmsAddColorSpace function.
8366
8367 If a new XcmsColorSpace structure specifies a color space not
8368 registered with the X Consortium, they should be treated as
8369 private to the client because format values for unregistered
8370 color spaces are assigned at run time. If references to an
8371 unregistered color space must be made outside the client (for
8372 example, storing color specifications in a file using the
8373 unregistered color space), then reference should be made by
8374 color space prefix (see XcmsFormatOfPrefix and
8375 XcmsPrefixOfFormat).
8376
8377
8378
8379typedef (*XcmsConversionProc)();
8380typedef XcmsConversionProc *XcmsFuncListPtr;
8381 /* A NULL terminated list of function pointers*/
8382
8383typedef struct _XcmsColorSpace {
8384 char *prefix;
8385 XcmsColorFormat format;
8386 XcmsParseStringProc parseString;
8387 XcmsFuncListPtr to_CIEXYZ;
8388 XcmsFuncListPtr from_CIEXYZ;
8389 int inverse_flag;
8390} XcmsColorSpace;
8391
8392 The prefix member specifies the prefix that indicates a color
8393 string is in this color space's string format. For example, the
8394 strings ``ciexyz'' or ``CIEXYZ'' for CIE XYZ, and ``rgb'' or
8395 ``RGB'' for RGB. The prefix is case insensitive. The format
8396 member specifies the color specification format. Formats for
8397 unregistered color spaces are assigned at run time. The
8398 parseString member contains a pointer to the function that can
8399 parse a color string into an XcmsColor structure. This function
8400 returns an integer (int): nonzero if it succeeded and zero
8401 otherwise. The to_CIEXYZ and from_CIEXYZ members contain
8402 pointers, each to a NULL terminated list of function pointers.
8403 When the list of functions is executed in series, it will
8404 convert the color specified in an XcmsColor structure from/to
8405 the current color space format to/from the CIE XYZ format. Each
8406 function returns an integer (int): nonzero if it succeeded and
8407 zero otherwise. The white point to be associated with the
8408 colors is specified explicitly, even though white points can be
8409 found in the CCC. The inverse_flag member, if nonzero,
8410 specifies that for each function listed in to_CIEXYZ, its
8411 inverse function can be found in from_CIEXYZ such that:
8412
8413Given: n = number of functions in each list
8414
8415for each i, such that 0 <= i < n
8416 from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].
8417
8418 This allows Xlib to use the shortest conversion path, thus
8419 bypassing CIE XYZ if possible (for example, TekHVC to CIE
8420 L*u*v*).
8421
8422Parse String Callback
8423
8424 The callback in the XcmsColorSpace structure for parsing a
8425 color string for the particular color space must adhere to the
8426 following software interface specification:
8427
8428 Status XcmsParseStringProc(char *color_string, XcmsColor
8429 *color_return);
8430
8431 color_string
8432
8433 Specifies the color string to parse.
8434
8435 color_return
8436
8437 Returns the color specification in the color space's format.
8438
8439Color Specification Conversion Callback
8440
8441 Callback functions in the XcmsColorSpace structure for
8442 converting a color specification between device-independent
8443 spaces must adhere to the following software interface
8444 specification:
8445
8446 Status ConversionProc(XcmsCCC ccc, XcmsColor *white_point,
8447 XcmsColor *colors_in_out, unsigned int ncolors);
8448
8449 ccc
8450
8451 Specifies the CCC.
8452
8453 white_point
8454
8455 Specifies the white point associated with color specifications.
8456 The pixel member should be ignored, and the entire structure
8457 remain unchanged upon return.
8458
8459 colors_in_out
8460
8461 Specifies an array of color specifications. Pixel members
8462 should be ignored and must remain unchanged upon return.
8463
8464 ncolors
8465
8466 Specifies the number of XcmsColor structures in the
8467 color-specification array.
8468
8469 Callback functions in the XcmsColorSpace structure for
8470 converting a color specification to or from a device-dependent
8471 space must adhere to the following software interface
8472 specification:
8473
8474 Status ConversionProc(XcmsCCC ccc, XcmsColor *colors_in_out,
8475 unsigned int ncolors, Bool compression_flags_return[]);
8476
8477 ccc
8478
8479 Specifies the CCC.
8480
8481 colors_in_out
8482
8483 Specifies an array of color specifications. Pixel members
8484 should be ignored and must remain unchanged upon return.
8485
8486 ncolors
8487
8488 Specifies the number of XcmsColor structures in the
8489 color-specification array.
8490
8491 compression_flags_return
8492
8493 Returns an array of Boolean values for indicating compression
8494 status. If a non-NULL pointer is supplied and a color at a
8495 given index is compressed, then True should be stored at the
8496 corresponding index in this array; otherwise, the array should
8497 not be modified.
8498
8499 Conversion functions are available globally for use by other
8500 color spaces. The conversion functions provided by Xlib are:
8501 Function Converts from Converts to
8502 XcmsCIELabToCIEXYZ XcmsCIELabFormat XcmsCIEXYZFormat
8503 XcmsCIELuvToCIEuvY XcmsCIELuvFormat XcmsCIEuvYFormat
8504 XcmsCIEXYZToCIELab XcmsCIEXYZFormat XcmsCIELabFormat
8505 XcmsCIEXYZToCIEuvY XcmsCIEXYZFormat XcmsCIEuvYFormat
8506 XcmsCIEXYZToCIExyY XcmsCIEXYZFormat XcmsCIExyYFormat
8507 XcmsCIEXYZToRGBi XcmsCIEXYZFormat XcmsRGBiFormat
8508 XcmsCIEuvYToCIELuv XcmsCIEuvYFormat XcmsCIELabFormat
8509 XcmsCIEuvYToCIEXYZ XcmsCIEuvYFormat XcmsCIEXYZFormat
8510 XcmsCIEuvYToTekHVC XcmsCIEuvYFormat XcmsTekHVCFormat
8511 XcmsCIExyYToCIEXYZ XcmsCIExyYFormat XcmsCIEXYZFormat
8512 XcmsRGBToRGBi XcmsRGBFormat XcmsRGBiFormat
8513 XcmsRGBiToCIEXYZ XcmsRGBiFormat XcmsCIEXYZFormat
8514 XcmsRGBiToRGB XcmsRGBiFormat XcmsRGBFormat
8515 XcmsTekHVCToCIEuvY XcmsTekHVCFormat XcmsCIEuvYFormat
8516
8517Function Sets
8518
8519 Functions to convert between device-dependent color spaces and
8520 CIE XYZ may differ for different classes of output devices (for
8521 example, color versus gray monitors). Therefore, the notion of
8522 a Color Characterization Function Set has been developed. A
8523 function set consists of device-dependent color spaces and the
8524 functions that convert color specifications between these
8525 device-dependent color spaces and the CIE XYZ color space
8526 appropriate for a particular class of output devices. The
8527 function set also contains a function that reads color
8528 characterization data off root window properties. It is this
8529 characterization data that will differ between devices within a
8530 class of output devices. For details about how color
8531 characterization data is stored in root window properties, see
8532 the section on Device Color Characterization in the
8533 Inter-Client Communication Conventions Manual. The LINEAR_RGB
8534 function set is provided by Xlib and will support most color
8535 monitors. Function sets may require data that differs from
8536 those needed for the LINEAR_RGB function set. In that case, its
8537 corresponding data may be stored on different root window
8538 properties.
8539
8540Adding Function Sets
8541
8542 To add a function set, use XcmsAddFunctionSet.
8543
8544 Status XcmsAddFunctionSet(XcmsFunctionSet *function_set);
8545
8546 function_set
8547
8548 Specifies the function set to add.
8549
8550 The XcmsAddFunctionSet function adds a function set to the
8551 color management system. If the function set uses
8552 device-dependent XcmsColorSpace structures not accessible in
8553 the color management system, XcmsAddFunctionSet adds them. If
8554 an added XcmsColorSpace structure is for a device-dependent
8555 color space not registered with the X Consortium, they should
8556 be treated as private to the client because format values for
8557 unregistered color spaces are assigned at run time. If
8558 references to an unregistered color space must be made outside
8559 the client (for example, storing color specifications in a file
8560 using the unregistered color space), then reference should be
8561 made by color space prefix (see XcmsFormatOfPrefix and
8562 XcmsPrefixOfFormat).
8563
8564 Additional function sets should be added before any calls to
8565 other Xlib routines are made. If not, the XcmsPerScrnInfo
8566 member of a previously created XcmsCCC does not have the
8567 opportunity to initialize with the added function set.
8568
8569Creating Additional Function Sets
8570
8571 The creation of additional function sets should be required
8572 only when an output device does not conform to existing
8573 function sets or when additional device-dependent color spaces
8574 are necessary. A function set consists primarily of a
8575 collection of device-dependent XcmsColorSpace structures and a
8576 means to read and store a screen's color characterization data.
8577 This data is stored in an XcmsFunctionSet structure. A handle
8578 to this structure (that is, by means of global variable) is
8579 usually made accessible to the client program for use with
8580 XcmsAddFunctionSet.
8581
8582 If a function set uses new device-dependent XcmsColorSpace
8583 structures, they will be transparently processed into the color
8584 management system. Function sets can share an XcmsColorSpace
8585 structure for a device-dependent color space. In addition,
8586 multiple XcmsColorSpace structures are allowed for a
8587 device-dependent color space; however, a function set can
8588 reference only one of them. These XcmsColorSpace structures
8589 will differ in the functions to convert to and from CIE XYZ,
8590 thus tailored for the specific function set.
8591
8592
8593
8594typedef struct _XcmsFunctionSet {
8595 XcmsColorSpace **DDColorSpaces;
8596 XcmsScreenInitProc screenInitProc;
8597 XcmsScreenFreeProc screenFreeProc;
8598} XcmsFunctionSet;
8599
8600 The DDColorSpaces member is a pointer to a NULL terminated list
8601 of pointers to XcmsColorSpace structures for the
8602 device-dependent color spaces that are supported by the
8603 function set. The screenInitProc member is set to the callback
8604 procedure (see the following interface specification) that
8605 initializes the XcmsPerScrnInfo structure for a particular
8606 screen.
8607
8608 The screen initialization callback must adhere to the following
8609 software interface specification:
8610
8611 typedef Status (*XcmsScreenInitProc)(Display *display, int
8612 screen_number, ScmsPerScrnInfo *screen_info);
8613
8614 display
8615
8616 Specifies the connection to the X server.
8617
8618 screen_number
8619
8620 Specifies the appropriate screen number on the host server.
8621
8622 screen_info
8623
8624 Specifies the XcmsPerScrnInfo structure, which contains the per
8625 screen information.
8626
8627 The screen initialization callback in the XcmsFunctionSet
8628 structure fetches the color characterization data (device
8629 profile) for the specified screen, typically off properties on
8630 the screen's root window. It then initializes the specified
8631 XcmsPerScrnInfo structure. If successful, the procedure fills
8632 in the XcmsPerScrnInfo structure as follows:
8633 * It sets the screenData member to the address of the created
8634 device profile data structure (contents known only by the
8635 function set).
8636 * It next sets the screenWhitePoint member.
8637 * It next sets the functionSet member to the address of the
8638 XcmsFunctionSet structure.
8639 * It then sets the state member to XcmsInitSuccess and
8640 finally returns XcmsSuccess.
8641
8642 If unsuccessful, the procedure sets the state member to
8643 XcmsInitFailure and returns XcmsFailure.
8644
8645 The XcmsPerScrnInfo structure contains:
8646
8647
8648
8649typedef struct _XcmsPerScrnInfo {
8650 XcmsColor screenWhitePoint;
8651 XPointer functionSet;
8652 XPointer screenData;
8653 unsigned char state;
8654 char pad[3];
8655} XcmsPerScrnInfo;
8656
8657 The screenWhitePoint member specifies the white point inherent
8658 to the screen. The functionSet member specifies the appropriate
8659 function set. The screenData member specifies the device
8660 profile. The state member is set to one of the following:
8661 * XcmsInitNone indicates initialization has not been
8662 previously attempted.
8663 * XcmsInitFailure indicates initialization has been
8664 previously attempted but failed.
8665 * XcmsInitSuccess indicates initialization has been
8666 previously attempted and succeeded.
8667
8668 The screen free callback must adhere to the following software
8669 interface specification:
8670
8671 typedef void (*XcmsScreenFreeProc)(XPointer screenData);
8672
8673 screenData
8674
8675 Specifies the data to be freed.
8676
8677 This function is called to free the screenData stored in an
8678 XcmsPerScrnInfo structure.
8679
8680Chapter 7. Graphics Context Functions
8681
8682 Table of Contents
8683
8684 Manipulating Graphics Context/State
8685 Using Graphics Context Convenience Routines
8686
8687 Setting the Foreground, Background, Function, or Plane
8688 Mask
8689
8690 Setting the Line Attributes and Dashes
8691 Setting the Fill Style and Fill Rule
8692 Setting the Fill Tile and Stipple
8693 Setting the Current Font
8694 Setting the Clip Region
8695 Setting the Arc Mode, Subwindow Mode, and Graphics
8696 Exposure
8697
8698 A number of resources are used when performing graphics
8699 operations in X. Most information about performing graphics
8700 (for example, foreground color, background color, line style,
8701 and so on) is stored in resources called graphics contexts
8702 (GCs). Most graphics operations (see chapter 8) take a GC as an
8703 argument. Although in theory the X protocol permits sharing of
8704 GCs between applications, it is expected that applications will
8705 use their own GCs when performing operations. Sharing of GCs is
8706 highly discouraged because the library may cache GC state.
8707
8708 Graphics operations can be performed to either windows or
8709 pixmaps, which collectively are called drawables. Each drawable
8710 exists on a single screen. A GC is created for a specific
8711 screen and drawable depth and can only be used with drawables
8712 of matching screen and depth.
8713
8714 This chapter discusses how to:
8715 * Manipulate graphics context/state
8716 * Use graphics context convenience functions
8717
8718Manipulating Graphics Context/State
8719
8720 Most attributes of graphics operations are stored in GCs. These
8721 include line width, line style, plane mask, foreground,
8722 background, tile, stipple, clipping region, end style, join
8723 style, and so on. Graphics operations (for example, drawing
8724 lines) use these values to determine the actual drawing
8725 operation. Extensions to X may add additional components to
8726 GCs. The contents of a GC are private to Xlib.
8727
8728 Xlib implements a write-back cache for all elements of a GC
8729 that are not resource IDs to allow Xlib to implement the
8730 transparent coalescing of changes to GCs. For example, a call
8731 to XSetForeground of a GC followed by a call to
8732 XSetLineAttributes results in only a single-change GC protocol
8733 request to the server. GCs are neither expected nor encouraged
8734 to be shared between client applications, so this write-back
8735 caching should present no problems. Applications cannot share
8736 GCs without external synchronization. Therefore, sharing GCs
8737 between applications is highly discouraged.
8738
8739 To set an attribute of a GC, set the appropriate member of the
8740 XGCValues structure and OR in the corresponding value bitmask
8741 in your subsequent calls to XCreateGC. The symbols for the
8742 value mask bits and the XGCValues structure are:
8743/* GC attribute value mask bits */
8744
8745#define GCFunction (1L<<0)
8746#define GCPlaneMask (1L<<1)
8747#define GCForeground (1L<<2)
8748#define GCBackground (1L<<3)
8749#define GCLineWidth (1L<<4)
8750#define GCLineStyle (1L<<5)
8751#define GCCapStyle (1L<<6)
8752#define GCJoinStyle (1L<<7)
8753#define GCFillStyle (1L<<8)
8754#define GCFillRule (1L<<9)
8755#define GCTile (1L<<10)
8756#define GCStipple (1L<<11)
8757#define GCTileStipXOrigin (1L<<12)
8758#define GCTileStipYOrigin (1L<<13)
8759#define GCFont (1L<<14)
8760#define GCSubwindowMode (1L<<15)
8761#define GCGraphicsExposures (1L<<16)
8762#define GCClipXOrigin (1L<<17)
8763#define GCClipYOrigin (1L<<18)
8764#define GCClipMask (1L<<19)
8765#define GCDashOffset (1L<<20)
8766#define GCDashList (1L<<21)
8767#define GCArcMode (1L<<22)
8768
8769
8770
8771/* Values */
8772
8773typedef struct {
8774 int function; /* logical operation */
8775 unsigned long plane_mask; /* plane mask */
8776 unsigned long foreground; /* foreground pixel */
8777 unsigned long background; /* background pixel */
8778 int line_width; /* line width (in pixels) */
8779 int line_style; /* LineSolid, LineOnOffDash, LineDoub
8780leDash */
8781 int cap_style; /* CapNotLast, CapButt, CapRound, Cap
8782Projecting */
8783 int join_style; /* JoinMiter, JoinRound, JoinBevel */
8784 int fill_style; /* FillSolid, FillTiled, FillStippled
8785 FillOpaqueStippled*/
8786 int fill_rule; /* EvenOddRule, WindingRule */
8787 int arc_mode; /* ArcChord, ArcPieSlice */
8788 Pixmap tile; /* tile pixmap for tiling operations
8789*/
8790 Pixmap stipple; /* stipple 1 plane pixmap for stippli
8791ng */
8792 int ts_x_origin; /* offset for tile or stipple operati
8793ons */
8794 int ts_y_origin
8795 Font font; /* default text font for text operati
8796ons */
8797 int subwindow_mode; /* ClipByChildren, IncludeInferiors *
8798/
8799 Bool graphics_exposures; /* boolean, should exposures be gener
8800ated */
8801 int clip_x_origin; /* origin for clipping */
8802 int clip_y_origin;
8803 Pixmap clip_mask; /* bitmap clipping; other calls for r
8804ects */
8805 int dash_offset; /* patterned/dashed line information
8806*/
8807 char dashes;
8808} XGCValues;
8809
8810 The default GC values are:
8811 Component Default
8812 function GXcopy
8813 plane_mask All ones
8814 foreground 0
8815 background 1
8816 line_width 0
8817 line_style LineSolid
8818 cap_style CapButt
8819 join_style JoinMiter
8820 fill_style FillSolid
8821 fill_rule EvenOddRule
8822 arc_mode ArcPieSlice
8823 tile
8824
8825 Pixmap of unspecified size filled with foreground pixel
8826
8827 (that is, client specified pixel if any, else 0)
8828
8829 (subsequent changes to foreground do not affect this pixmap)
8830 stipple Pixmap of unspecified size filled with ones
8831 ts_x_origin 0
8832 ts_y_origin 0
8833 font <implementation dependent>
8834 subwindow_mode ClipByChildren
8835 graphics_exposures True
8836 clip_x_origin 0
8837 clip_y_origin 0
8838 clip_mask None
8839 dash_offset 0
8840 dashes 4 (that is, the list [4, 4])
8841
8842 Note that foreground and background are not set to any values
8843 likely to be useful in a window.
8844
8845 The function attributes of a GC are used when you update a
8846 section of a drawable (the destination) with bits from
8847 somewhere else (the source). The function in a GC defines how
8848 the new destination bits are to be computed from the source
8849 bits and the old destination bits. GXcopy is typically the most
8850 useful because it will work on a color display, but special
8851 applications may use other functions, particularly in concert
8852 with particular planes of a color display. The 16 GC functions,
8853 defined in <X11/X.h>, are:
8854 Function Name Value Operation
8855 GXclear 0x0 0
8856 GXand 0x1 src AND dst
8857 GXandReverse 0x2 src AND NOT dst
8858 GXcopy 0x3 src
8859 GXandInverted 0x4 (NOT src) AND dst
8860 GXnoop 0x5 dst
8861 GXxor 0x6 src XOR dst
8862 GXor 0x7 src OR dst
8863 GXnor 0x8 (NOT src) AND (NOT dst)
8864 GXequiv 0x9 (NOT src) XOR dst
8865 GXinvert 0xa NOT dst
8866 GXorReverse 0xb src OR (NOT dst)
8867 GXcopyInverted 0xc NOT src
8868 GXorInverted 0xd (NOT src) OR dst
8869 GXnand 0xe (NOT src) OR (NOT dst)
8870 GXset 0xf 1
8871
8872 Many graphics operations depend on either pixel values or
8873 planes in a GC. The planes attribute is of type long, and it
8874 specifies which planes of the destination are to be modified,
8875 one bit per plane. A monochrome display has only one plane and
8876 will be the least significant bit of the word. As planes are
8877 added to the display hardware, they will occupy more
8878 significant bits in the plane mask.
8879
8880 In graphics operations, given a source and destination pixel,
8881 the result is computed bitwise on corresponding bits of the
8882 pixels. That is, a Boolean operation is performed in each bit
8883 plane. The plane_mask restricts the operation to a subset of
8884 planes. A macro constant AllPlanes can be used to refer to all
8885 planes of the screen simultaneously. The result is computed by
8886 the following:
8887
8888((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
8889
8890 Range checking is not performed on the values for foreground,
8891 background, or plane_mask. They are simply truncated to the
8892 appropriate number of bits. The line-width is measured in
8893 pixels and either can be greater than or equal to one (wide
8894 line) or can be the special value zero (thin line).
8895
8896 Wide lines are drawn centered on the path described by the
8897 graphics request. Unless otherwise specified by the join-style
8898 or cap-style, the bounding box of a wide line with endpoints
8899 [x1, y1], [x2, y2] and width w is a rectangle with vertices at
8900 the following real coordinates:
8901
8902
8903
8904[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
8905[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
8906
8907 Here sn is the sine of the angle of the line, and cs is the
8908 cosine of the angle of the line. A pixel is part of the line
8909 and so is drawn if the center of the pixel is fully inside the
8910 bounding box (which is viewed as having infinitely thin edges).
8911 If the center of the pixel is exactly on the bounding box, it
8912 is part of the line if and only if the interior is immediately
8913 to its right (x increasing direction). Pixels with centers on a
8914 horizontal edge are a special case and are part of the line if
8915 and only if the interior or the boundary is immediately below
8916 (y increasing direction) and the interior or the boundary is
8917 immediately to the right (x increasing direction).
8918
8919 Thin lines (zero line-width) are one-pixel-wide lines drawn
8920 using an unspecified, device-dependent algorithm. There are
8921 only two constraints on this algorithm.
8922 * If a line is drawn unclipped from [x1,y1] to [x2,y2] and if
8923 another line is drawn unclipped from [x1+dx,y1+dy] to
8924 [x2+dx,y2+dy], a point [x,y] is touched by drawing the
8925 first line if and only if the point [x+dx,y+dy] is touched
8926 by drawing the second line.
8927 * The effective set of points comprising a line cannot be
8928 affected by clipping. That is, a point is touched in a
8929 clipped line if and only if the point lies inside the
8930 clipping region and the point would be touched by the line
8931 when drawn unclipped.
8932
8933 A wide line drawn from [x1,y1] to [x2,y2] always draws the same
8934 pixels as a wide line drawn from [x2,y2] to [x1,y1], not
8935 counting cap-style and join-style. It is recommended that this
8936 property be true for thin lines, but this is not required. A
8937 line-width of zero may differ from a line-width of one in which
8938 pixels are drawn. This permits the use of many manufacturers'
8939 line drawing hardware, which may run many times faster than the
8940 more precisely specified wide lines.
8941
8942 In general, drawing a thin line will be faster than drawing a
8943 wide line of width one. However, because of their different
8944 drawing algorithms, thin lines may not mix well aesthetically
8945 with wide lines. If it is desirable to obtain precise and
8946 uniform results across all displays, a client should always use
8947 a line-width of one rather than a line-width of zero.
8948
8949 The line-style defines which sections of a line are drawn:
8950
8951 LineSolid
8952
8953 The full path of the line is drawn.
8954
8955 LineDoubleDash
8956
8957 The full path of the line is drawn, but the even dashes are
8958 filled differently from the odd dashes (see fill-style) with
8959 CapButt style used where even and odd dashes meet.
8960
8961 LineOnOffDash
8962
8963 Only the even dashes are drawn, and cap-style applies to all
8964 internal ends of the individual dashes, except CapNotLast is
8965 treated as CapButt.
8966
8967 The cap-style defines how the endpoints of a path are drawn:
8968
8969 CapNotLast
8970
8971 This is equivalent to CapButt except that for a line-width of
8972 zero the final endpoint is not drawn.
8973
8974 CapButt
8975
8976 The line is square at the endpoint (perpendicular to the slope
8977 of the line) with no projection beyond.
8978
8979 CapRound
8980
8981 The line has a circular arc with the diameter equal to the
8982 line-width, centered on the endpoint. (This is equivalent to
8983 CapButt for line-width of zero).
8984
8985 CapProjecting
8986
8987 The line is square at the end, but the path continues beyond
8988 the endpoint for a distance equal to half the line-width. (This
8989 is equivalent to CapButt for line-width of zero).
8990
8991 The join-style defines how corners are drawn for wide lines:
8992
8993 JoinMiter
8994
8995 The outer edges of two lines extend to meet at an angle.
8996 However, if the angle is less than 11 degrees, then a JoinBevel
8997 join-style is used instead.
8998
8999 JoinRound
9000
9001 The corner is a circular arc with the diameter equal to the
9002 line-width, centered on the joinpoint.
9003
9004 JoinBevel
9005
9006 The corner has CapButt endpoint styles with the triangular
9007 notch filled.
9008
9009 For a line with coincident endpoints (x1=x2, y1=y2), when the
9010 cap-style is applied to both endpoints, the semantics depends
9011 on the line-width and the cap-style:
9012 CapNotLast thin The results are device dependent, but the
9013 desired effect is that nothing is drawn.
9014 CapButt thin The results are device dependent, but the desired
9015 effect is that a single pixel is drawn.
9016 CapRound thin The results are the same as for CapButt /thin.
9017 CapProjecting thin The results are the same as for CapButt
9018 /thin.
9019 CapButt wide Nothing is drawn.
9020 CapRound wide The closed path is a circle, centered at the
9021 endpoint, and with the diameter equal to the line-width.
9022 CapProjecting wide The closed path is a square, aligned with
9023 the coordinate axes, centered at the endpoint, and with the
9024 sides equal to the line-width.
9025
9026 For a line with coincident endpoints (x1=x2, y1=y2), when the
9027 join-style is applied at one or both endpoints, the effect is
9028 as if the line was removed from the overall path. However, if
9029 the total path consists of or is reduced to a single point
9030 joined with itself, the effect is the same as when the
9031 cap-style is applied at both endpoints.
9032
9033 The tile/stipple represents an infinite two-dimensional plane,
9034 with the tile/stipple replicated in all dimensions. When that
9035 plane is superimposed on the drawable for use in a graphics
9036 operation, the upper-left corner of some instance of the
9037 tile/stipple is at the coordinates within the drawable
9038 specified by the tile/stipple origin. The tile/stipple and clip
9039 origins are interpreted relative to the origin of whatever
9040 destination drawable is specified in a graphics request. The
9041 tile pixmap must have the same root and depth as the GC, or a
9042 BadMatch error results. The stipple pixmap must have depth one
9043 and must have the same root as the GC, or a BadMatch error
9044 results. For stipple operations where the fill-style is
9045 FillStippled but not FillOpaqueStippled, the stipple pattern is
9046 tiled in a single plane and acts as an additional clip mask to
9047 be ANDed with the clip-mask. Although some sizes may be faster
9048 to use than others, any size pixmap can be used for tiling or
9049 stippling.
9050
9051 The fill-style defines the contents of the source for line,
9052 text, and fill requests. For all text and fill requests (for
9053 example, XDrawText, XDrawText16, XFillRectangle, XFillPolygon,
9054 and XFillArc); for line requests with line-style LineSolid (for
9055 example, XDrawLine, XDrawSegments, XDrawRectangle, XDrawArc);
9056 and for the even dashes for line requests with line-style
9057 LineOnOffDash or LineDoubleDash, the following apply:
9058 FillSolid Foreground
9059 FillTiled Tile
9060 FillOpaqueStippled A tile with the same width and height as
9061 stipple, but with background everywhere stipple has a zero and
9062 with foreground everywhere stipple has a one
9063 FillStippled Foreground masked by stipple
9064
9065 When drawing lines with line-style LineDoubleDash, the odd
9066 dashes are controlled by the fill-style in the following
9067 manner:
9068 FillSolid Background
9069 FillTiled Same as for even dashes
9070 FillOpaqueStippled Same as for even dashes
9071 FillStippled Background masked by stipple
9072
9073 Storing a pixmap in a GC might or might not result in a copy
9074 being made. If the pixmap is later used as the destination for
9075 a graphics request, the change might or might not be reflected
9076 in the GC. If the pixmap is used simultaneously in a graphics
9077 request both as a destination and as a tile or stipple, the
9078 results are undefined.
9079
9080 For optimum performance, you should draw as much as possible
9081 with the same GC (without changing its components). The costs
9082 of changing GC components relative to using different GCs
9083 depend on the display hardware and the server implementation.
9084 It is quite likely that some amount of GC information will be
9085 cached in display hardware and that such hardware can only
9086 cache a small number of GCs.
9087
9088 The dashes value is actually a simplified form of the more
9089 general patterns that can be set with XSetDashes. Specifying a
9090 value of N is equivalent to specifying the two-element list [N,
9091 N] in XSetDashes. The value must be nonzero, or a BadValue
9092 error results.
9093
9094 The clip-mask restricts writes to the destination drawable. If
9095 the clip-mask is set to a pixmap, it must have depth one and
9096 have the same root as the GC, or a BadMatch error results. If
9097 clip-mask is set to None, the pixels are always drawn
9098 regardless of the clip origin. The clip-mask also can be set by
9099 calling the XSetClipRectangles or XSetRegion functions. Only
9100 pixels where the clip-mask has a bit set to 1 are drawn. Pixels
9101 are not drawn outside the area covered by the clip-mask or
9102 where the clip-mask has a bit set to 0. The clip-mask affects
9103 all graphics requests. The clip-mask does not clip sources. The
9104 clip-mask origin is interpreted relative to the origin of
9105 whatever destination drawable is specified in a graphics
9106 request.
9107
9108 You can set the subwindow-mode to ClipByChildren or
9109 IncludeInferiors. For ClipByChildren, both source and
9110 destination windows are additionally clipped by all viewable
9111 InputOutput children. For IncludeInferiors, neither source nor
9112 destination window is clipped by inferiors. This will result in
9113 including subwindow contents in the source and drawing through
9114 subwindow boundaries of the destination. The use of
9115 IncludeInferiors on a window of one depth with mapped inferiors
9116 of differing depth is not illegal, but the semantics are
9117 undefined by the core protocol.
9118
9119 The fill-rule defines what pixels are inside (drawn) for paths
9120 given in XFillPolygon requests and can be set to EvenOddRule or
9121 WindingRule. For EvenOddRule, a point is inside if an infinite
9122 ray with the point as origin crosses the path an odd number of
9123 times. For WindingRule, a point is inside if an infinite ray
9124 with the point as origin crosses an unequal number of clockwise
9125 and counterclockwise directed path segments. A clockwise
9126 directed path segment is one that crosses the ray from left to
9127 right as observed from the point. A counterclockwise segment is
9128 one that crosses the ray from right to left as observed from
9129 the point. The case where a directed line segment is coincident
9130 with the ray is uninteresting because you can simply choose a
9131 different ray that is not coincident with a segment.
9132
9133 For both EvenOddRule and WindingRule, a point is infinitely
9134 small, and the path is an infinitely thin line. A pixel is
9135 inside if the center point of the pixel is inside and the
9136 center point is not on the boundary. If the center point is on
9137 the boundary, the pixel is inside if and only if the polygon
9138 interior is immediately to its right (x increasing direction).
9139 Pixels with centers on a horizontal edge are a special case and
9140 are inside if and only if the polygon interior is immediately
9141 below (y increasing direction).
9142
9143 The arc-mode controls filling in the XFillArcs function and can
9144 be set to ArcPieSlice or ArcChord. For ArcPieSlice, the arcs
9145 are pie-slice filled. For ArcChord, the arcs are chord filled.
9146
9147 The graphics-exposure flag controls GraphicsExpose event
9148 generation for XCopyArea and XCopyPlane requests (and any
9149 similar requests defined by extensions).
9150
9151 To create a new GC that is usable on a given screen with a
9152 depth of drawable, use XCreateGC.
9153
9154 GC XCreateGC(Display *display, Drawable d, unsigned long
9155 valuemask, XGCValues *values);
9156
9157 display
9158
9159 Specifies the connection to the X server.
9160
9161 d
9162
9163 Specifies the drawable.
9164
9165 valuemask
9166
9167 Specifies which components in the GC are to be set using the
9168 information in the specified values structure. This argument is
9169 the bitwise inclusive OR of zero or more of the valid GC
9170 component mask bits.
9171
9172 values
9173
9174 Specifies any values as specified by the valuemask.
9175
9176 The XCreateGC function creates a graphics context and returns a
9177 GC. The GC can be used with any destination drawable having the
9178 same root and depth as the specified drawable. Use with other
9179 drawables results in a BadMatch error.
9180
9181 XCreateGC can generate BadAlloc, BadDrawable, BadFont,
9182 BadMatch, BadPixmap, and BadValue errors.
9183
9184 To copy components from a source GC to a destination GC, use
9185 XCopyGC.
9186
9187 XCopyGC(Display *display, GC src, GC dest, unsigned long
9188 valuemask);
9189
9190 display
9191
9192 Specifies the connection to the X server.
9193
9194 src
9195
9196 Specifies the components of the source GC.
9197
9198 valuemask
9199
9200 Specifies which components in the GC are to be copied to the
9201 destination GC. This argument is the bitwise inclusive OR of
9202 zero or more of the valid GC component mask bits.
9203
9204 dest
9205
9206 Specifies the destination GC.
9207
9208 The XCopyGC function copies the specified components from the
9209 source GC to the destination GC. The source and destination GCs
9210 must have the same root and depth, or a BadMatch error results.
9211 The valuemask specifies which component to copy, as for
9212 XCreateGC.
9213
9214 XCopyGC can generate BadAlloc, BadGC, and BadMatch errors.
9215
9216 To change the components in a given GC, use XChangeGC.
9217
9218 XChangeGC(Display *display, GC gc, unsigned long valuemask,
9219 XGCValues *values);
9220
9221 display
9222
9223 Specifies the connection to the X server.
9224
9225 gc
9226
9227 Specifies the GC.
9228
9229 valuemask
9230
9231 Specifies which components in the GC are to be changed using
9232 information in the specified values structure. This argument is
9233 the bitwise inclusive OR of zero or more of the valid GC
9234 component mask bits.
9235
9236 values
9237
9238 Specifies any values as specified by the valuemask.
9239
9240 The XChangeGC function changes the components specified by
9241 valuemask for the specified GC. The values argument contains
9242 the values to be set. The values and restrictions are the same
9243 as for XCreateGC. Changing the clip-mask overrides any previous
9244 XSetClipRectangles request on the context. Changing the
9245 dash-offset or dash-list overrides any previous XSetDashes
9246 request on the context. The order in which components are
9247 verified and altered is server dependent. If an error is
9248 generated, a subset of the components may have been altered.
9249
9250 XChangeGC can generate BadAlloc, BadFont, BadGC, BadMatch,
9251 BadPixmap, and BadValue errors.
9252
9253 To obtain components of a given GC, use XGetGCValues.
9254
9255 Status XGetGCValues(Display *display, GC gc, unsigned long
9256 valuemask, XGCValues *values_return);
9257
9258 display
9259
9260 Specifies the connection to the X server.
9261
9262 gc
9263
9264 Specifies the GC.
9265
9266 valuemask
9267
9268 Specifies which components in the GC are to be returned in the
9269 values_return argument. This argument is the bitwise inclusive
9270 OR of zero or more of the valid GC component mask bits.
9271
9272 values_return
9273
9274 Returns the GC values in the specified XGCValues structure.
9275
9276 The XGetGCValues function returns the components specified by
9277 valuemask for the specified GC. If the valuemask contains a
9278 valid set of GC mask bits (GCFunction, GCPlaneMask,
9279 GCForeground, GCBackground, GCLineWidth, GCLineStyle,
9280 GCCapStyle, GCJoinStyle, GCFillStyle, GCFillRule, GCTile,
9281 GCStipple, GCTileStipXOrigin, GCTileStipYOrigin, GCFont,
9282 GCSubwindowMode, GCGraphicsExposures, GCClipXOrigin,
9283 GCClipYOrigin, GCDashOffset, or GCArcMode) and no error occurs,
9284 XGetGCValues sets the requested components in values_return and
9285 returns a nonzero status. Otherwise, it returns a zero status.
9286 Note that the clip-mask and dash-list (represented by the
9287 GCClipMask and GCDashList bits, respectively, in the valuemask)
9288 cannot be requested. Also note that an invalid resource ID
9289 (with one or more of the three most significant bits set to 1)
9290 will be returned for GCFont, GCTile, and GCStipple if the
9291 component has never been explicitly set by the client.
9292
9293 To free a given GC, use XFreeGC.
9294
9295 XFreeGC(Display *display, GC gc);
9296
9297 display
9298
9299 Specifies the connection to the X server.
9300
9301 gc
9302
9303 Specifies the GC.
9304
9305 The XFreeGC function destroys the specified GC as well as all
9306 the associated storage.
9307
9308 XFreeGC can generate a BadGC error.
9309
9310 To obtain the GContext resource ID for a given GC, use
9311 XGContextFromGC.
9312
9313 GContext XGContextFromGC(GC gc);
9314
9315 gc
9316
9317 Specifies the GC for which you want the resource ID.
9318
9319 Xlib usually defers sending changes to the components of a GC
9320 to the server until a graphics function is actually called with
9321 that GC. This permits batching of component changes into a
9322 single server request. In some circumstances, however, it may
9323 be necessary for the client to explicitly force sending the
9324 changes to the server. An example might be when a protocol
9325 extension uses the GC indirectly, in such a way that the
9326 extension interface cannot know what GC will be used. To force
9327 sending GC component changes, use XFlushGC.
9328
9329 void XFlushGC(Display *display, GC gc);
9330
9331 display
9332
9333 Specifies the connection to the X server.
9334
9335 gc
9336
9337 Specifies the GC.
9338
9339Using Graphics Context Convenience Routines
9340
9341 This section discusses how to set the:
9342 * Foreground, background, plane mask, or function components
9343 * Line attributes and dashes components
9344 * Fill style and fill rule components
9345 * Fill tile and stipple components
9346 * Font component
9347 * Clip region component
9348 * Arc mode, subwindow mode, and graphics exposure components
9349
9350Setting the Foreground, Background, Function, or Plane Mask
9351
9352 To set the foreground, background, plane mask, and function
9353 components for a given GC, use XSetState.
9354
9355 XSetState(Display *display, GC gc, unsigned long foreground,
9356 unsigned long background, int function, unsigned long
9357 plane_mask);
9358
9359 display
9360
9361 Specifies the connection to the X server.
9362
9363 gc
9364
9365 Specifies the GC.
9366
9367 foreground
9368
9369 Specifies the foreground you want to set for the specified GC.
9370
9371 background
9372
9373 Specifies the background you want to set for the specified GC.
9374
9375 function
9376
9377 Specifies the function you want to set for the specified GC.
9378
9379 plane_mask
9380
9381 Specifies the plane mask.
9382
9383 XSetState can generate BadAlloc, BadGC, and BadValue errors.
9384
9385 To set the foreground of a given GC, use XSetForeground.
9386
9387 XSetForeground(Display *display, GC gc, unsigned long
9388 foreground);
9389
9390 display
9391
9392 Specifies the connection to the X server.
9393
9394 gc
9395
9396 Specifies the GC.
9397
9398 foreground
9399
9400 Specifies the foreground you want to set for the specified GC.
9401
9402 XSetForeground can generate BadAlloc and BadGC errors.
9403
9404 To set the background of a given GC, use XSetBackground.
9405
9406 XSetBackground(Display *display, GC gc, unsigned long
9407 background);
9408
9409 display
9410
9411 Specifies the connection to the X server.
9412
9413 gc
9414
9415 Specifies the GC.
9416
9417 background
9418
9419 Specifies the background you want to set for the specified GC.
9420
9421 XSetBackground can generate BadAlloc and BadGC errors.
9422
9423 To set the display function in a given GC, use XSetFunction.
9424
9425 XSetFunction(Display *display, GC gc, int function);
9426
9427 display
9428
9429 Specifies the connection to the X server.
9430
9431 gc
9432
9433 Specifies the GC.
9434
9435 function
9436
9437 Specifies the function you want to set for the specified GC.
9438
9439 XSetFunction can generate BadAlloc, BadGC, and BadValue errors.
9440
9441 To set the plane mask of a given GC, use XSetPlaneMask.
9442
9443 XSetPlaneMask(Display *display, GC gc, unsigned long
9444 plane_mask);
9445
9446 display
9447
9448 Specifies the connection to the X server.
9449
9450 gc
9451
9452 Specifies the GC.
9453
9454 plane_mask
9455
9456 Specifies the plane mask.
9457
9458 XSetPlaneMask can generate BadAlloc and BadGC errors.
9459
9460Setting the Line Attributes and Dashes
9461
9462 To set the line drawing components of a given GC, use
9463 XSetLineAttributes.
9464
9465 XSetLineAttributes(Display *display, GC gc, unsigned int
9466 line_width, int line_style, int cap_style, int join_style);
9467
9468 display
9469
9470 Specifies the connection to the X server.
9471
9472 gc
9473
9474 Specifies the GC.
9475
9476 line_width
9477
9478 Specifies the line-width you want to set for the specified GC.
9479
9480 line_style
9481
9482 Specifies the line-style you want to set for the specified GC.
9483 You can pass LineSolid, LineOnOffDash, or LineDoubleDash.
9484
9485 cap_style
9486
9487 Specifies the line-style and cap-style you want to set for the
9488 specified GC. You can pass CapNotLast, CapButt, CapRound, or
9489 CapProjecting.
9490
9491 join_style
9492
9493 Specifies the line join-style you want to set for the specified
9494 GC. You can pass JoinMiter, JoinRound, or JoinBevel.
9495
9496 XSetLineAttributes can generate BadAlloc, BadGC, and BadValue
9497 errors.
9498
9499 To set the dash-offset and dash-list for dashed line styles of
9500 a given GC, use XSetDashes.
9501
9502 XSetDashes(Display *display, GC gc, int dash_offset, char
9503 dash_list[], int n);
9504
9505 display
9506
9507 Specifies the connection to the X server.
9508
9509 gc
9510
9511 Specifies the GC.
9512
9513 dash_offset
9514
9515 Specifies the phase of the pattern for the dashed line-style
9516 you want to set for the specified GC.
9517
9518 dash_list
9519
9520 Specifies the dash-list for the dashed line-style you want to
9521 set for the specified GC.
9522
9523 n
9524
9525 Specifies the number of elements in dash_list.
9526
9527 The XSetDashes function sets the dash-offset and dash-list
9528 attributes for dashed line styles in the specified GC. There
9529 must be at least one element in the specified dash_list, or a
9530 BadValue error results. The initial and alternating elements
9531 (second, fourth, and so on) of the dash_list are the even
9532 dashes, and the others are the odd dashes. Each element
9533 specifies a dash length in pixels. All of the elements must be
9534 nonzero, or a BadValue error results. Specifying an odd-length
9535 list is equivalent to specifying the same list concatenated
9536 with itself to produce an even-length list.
9537
9538 The dash-offset defines the phase of the pattern, specifying
9539 how many pixels into the dash-list the pattern should actually
9540 begin in any single graphics request. Dashing is continuous
9541 through path elements combined with a join-style but is reset
9542 to the dash-offset between each sequence of joined lines.
9543
9544 The unit of measure for dashes is the same for the ordinary
9545 coordinate system. Ideally, a dash length is measured along the
9546 slope of the line, but implementations are only required to
9547 match this ideal for horizontal and vertical lines. Failing the
9548 ideal semantics, it is suggested that the length be measured
9549 along the major axis of the line. The major axis is defined as
9550 the x axis for lines drawn at an angle of between -45 and +45
9551 degrees or between 135 and 225 degrees from the x axis. For all
9552 other lines, the major axis is the y axis.
9553
9554 XSetDashes can generate BadAlloc, BadGC, and BadValue errors.
9555
9556Setting the Fill Style and Fill Rule
9557
9558 To set the fill-style of a given GC, use XSetFillStyle.
9559
9560 XSetFillStyle(Display *display, GC gc, int fill_style);
9561
9562 display
9563
9564 Specifies the connection to the X server.
9565
9566 gc
9567
9568 Specifies the GC.
9569
9570 fill_style
9571
9572 Specifies the fill-style you want to set for the specified GC.
9573 You can pass FillSolid, FillTiled, FillStippled, or
9574 FillOpaqueStippled.
9575
9576 XSetFillStyle can generate BadAlloc, BadGC, and BadValue
9577 errors.
9578
9579 To set the fill-rule of a given GC, use XSetFillRule.
9580
9581 XSetFillRule(Display *display, GC gc, int fill_rule);
9582
9583 display
9584
9585 Specifies the connection to the X server.
9586
9587 gc
9588
9589 Specifies the GC.
9590
9591 fill_rule
9592
9593 Specifies the fill-rule you want to set for the specified GC.
9594 You can pass EvenOddRule or WindingRule.
9595
9596 XSetFillRule can generate BadAlloc, BadGC, and BadValue errors.
9597
9598Setting the Fill Tile and Stipple
9599
9600 Some displays have hardware support for tiling or stippling
9601 with patterns of specific sizes. Tiling and stippling
9602 operations that restrict themselves to those specific sizes run
9603 much faster than such operations with arbitrary size patterns.
9604 Xlib provides functions that you can use to determine the best
9605 size, tile, or stipple for the display as well as to set the
9606 tile or stipple shape and the tile or stipple origin.
9607
9608 To obtain the best size of a tile, stipple, or cursor, use
9609 XQueryBestSize.
9610
9611 Status XQueryBestSize(Display *display, int class, Drawable
9612 which_screen, unsigned int width, unsigned int height, unsigned
9613 int *width_return, unsigned int *height_return);
9614
9615 display
9616
9617 Specifies the connection to the X server.
9618
9619 class
9620
9621 Specifies the class that you are interested in. You can pass
9622 TileShape, CursorShape, or StippleShape.
9623
9624 which_screen
9625
9626 Specifies any drawable on the screen.
9627
9628 width
9629
9630 height
9631
9632 Specify the width and height.
9633
9634 width_return
9635
9636 height_return
9637
9638 Return the width and height of the object best supported by the
9639 display hardware.
9640
9641 The XQueryBestSize function returns the best or closest size to
9642 the specified size. For CursorShape, this is the largest size
9643 that can be fully displayed on the screen specified by
9644 which_screen. For TileShape, this is the size that can be tiled
9645 fastest. For StippleShape, this is the size that can be
9646 stippled fastest. For CursorShape, the drawable indicates the
9647 desired screen. For TileShape and StippleShape, the drawable
9648 indicates the screen and possibly the window class and depth.
9649 An InputOnly window cannot be used as the drawable for
9650 TileShape or StippleShape, or a BadMatch error results.
9651
9652 XQueryBestSize can generate BadDrawable, BadMatch, and BadValue
9653 errors.
9654
9655 To obtain the best fill tile shape, use XQueryBestTile.
9656
9657 Status XQueryBestTile(Display *display, Drawable which_screen,
9658 unsigned int width, unsigned int height, unsigned int
9659 *width_return, unsigned int *height_return);
9660
9661 display
9662
9663 Specifies the connection to the X server.
9664
9665 which_screen
9666
9667 Specifies any drawable on the screen.
9668
9669 width
9670
9671 height
9672
9673 Specify the width and height.
9674
9675 width_return
9676
9677 height_return
9678
9679 Return the width and height of the object best supported by the
9680 display hardware.
9681
9682 The XQueryBestTile function returns the best or closest size,
9683 that is, the size that can be tiled fastest on the screen
9684 specified by which_screen. The drawable indicates the screen
9685 and possibly the window class and depth. If an InputOnly window
9686 is used as the drawable, a BadMatch error results.
9687
9688 XQueryBestTile can generate BadDrawable and BadMatch errors.
9689
9690 To obtain the best stipple shape, use XQueryBestStipple.
9691
9692 Status XQueryBestStipple(Display *display, Drawable
9693 which_screen, unsigned int width, unsigned int height, unsigned
9694 int *width_return, unsigned int *height_return);
9695
9696 display
9697
9698 Specifies the connection to the X server.
9699
9700 which_screen
9701
9702 Specifies any drawable on the screen.
9703
9704 width
9705
9706 height
9707
9708 Specify the width and height.
9709
9710 width_return
9711
9712 height_return
9713
9714 Return the width and height of the object best supported by the
9715 display hardware.
9716
9717 The XQueryBestStipple function returns the best or closest
9718 size, that is, the size that can be stippled fastest on the
9719 screen specified by which_screen. The drawable indicates the
9720 screen and possibly the window class and depth. If an InputOnly
9721 window is used as the drawable, a BadMatch error results.
9722
9723 XQueryBestStipple can generate BadDrawable and BadMatch errors.
9724
9725 To set the fill tile of a given GC, use XSetTile.
9726
9727 XSetTile(Display *display, GC gc, Pixmap tile);
9728
9729 display
9730
9731 Specifies the connection to the X server.
9732
9733 gc
9734
9735 Specifies the GC.
9736
9737 tile
9738
9739 Specifies the fill tile you want to set for the specified GC.
9740
9741 The tile and GC must have the same depth, or a BadMatch error
9742 results.
9743
9744 XSetTile can generate BadAlloc, BadGC, BadMatch, and BadPixmap
9745 errors.
9746
9747 To set the stipple of a given GC, use XSetStipple.
9748
9749 XSetStipple(Display *display, GC gc, Pixmap stipple);
9750
9751 display
9752
9753 Specifies the connection to the X server.
9754
9755 gc
9756
9757 Specifies the GC.
9758
9759 stipple
9760
9761 Specifies the stipple you want to set for the specified GC.
9762
9763 The stipple must have a depth of one, or a BadMatch error
9764 results.
9765
9766 XSetStipple can generate BadAlloc, BadGC, BadMatch, and
9767 BadPixmap errors.
9768
9769 To set the tile or stipple origin of a given GC, use
9770 XSetTSOrigin.
9771
9772 XSetTSOrigin(Display *display, GC gc, int ts_x_origin, int
9773 ts_y_origin);
9774
9775 display
9776
9777 Specifies the connection to the X server.
9778
9779 gc
9780
9781 Specifies the GC.
9782
9783 ts_x_origin
9784
9785 ts_y_origin
9786
9787 Specify the x and y coordinates of the tile and stipple origin.
9788
9789 When graphics requests call for tiling or stippling, the
9790 parent's origin will be interpreted relative to whatever
9791 destination drawable is specified in the graphics request.
9792
9793 XSetTSOrigin can generate BadAlloc and BadGC errors.
9794
9795Setting the Current Font
9796
9797 To set the current font of a given GC, use XSetFont.
9798
9799 XSetFont(Display *display, GC gc, Font font);
9800
9801 display
9802
9803 Specifies the connection to the X server.
9804
9805 gc
9806
9807 Specifies the GC.
9808
9809 font
9810
9811 Specifies the font.
9812
9813 XSetFont can generate BadAlloc, BadFont, and BadGC errors.
9814
9815Setting the Clip Region
9816
9817 Xlib provides functions that you can use to set the clip-origin
9818 and the clip-mask or set the clip-mask to a list of rectangles.
9819
9820 To set the clip-origin of a given GC, use XSetClipOrigin.
9821
9822 XSetClipOrigin(Display *display, GC gc, int clip_x_origin, int
9823 clip_y_origin);
9824
9825 display
9826
9827 Specifies the connection to the X server.
9828
9829 gc
9830
9831 Specifies the GC.
9832
9833 clip_x_origin
9834
9835 clip_y_origin
9836
9837 Specify the x and y coordinates of the clip-mask origin.
9838
9839 The clip-mask origin is interpreted relative to the origin of
9840 whatever destination drawable is specified in the graphics
9841 request.
9842
9843 XSetClipOrigin can generate BadAlloc and BadGC errors.
9844
9845 To set the clip-mask of a given GC to the specified pixmap, use
9846 XSetClipMask.
9847
9848 XSetClipMask(Display *display, GC gc, Pixmap pixmap);
9849
9850 display
9851
9852 Specifies the connection to the X server.
9853
9854 gc
9855
9856 Specifies the GC.
9857
9858 pixmap
9859
9860 Specifies the pixmap or None.
9861
9862 If the clip-mask is set to None, the pixels are always drawn
9863 (regardless of the clip-origin).
9864
9865 XSetClipMask can generate BadAlloc, BadGC, BadMatch, and
9866 BadPixmap errors.
9867
9868 To set the clip-mask of a given GC to the specified list of
9869 rectangles, use XSetClipRectangles.
9870
9871 XSetClipRectangles(Display *display, GC gc, int clip_x_origin,
9872 int clip_y_origin, XRectangle rectangles[], int n, int
9873 ordering);
9874
9875 display
9876
9877 Specifies the connection to the X server.
9878
9879 gc
9880
9881 Specifies the GC.
9882
9883 clip_x_origin
9884
9885 clip_y_origin
9886
9887 Specify the x and y coordinates of the clip-mask origin.
9888
9889 rectangles
9890
9891 Specifies an array of rectangles that define the clip-mask.
9892
9893 n
9894
9895 Specifies the number of rectangles.
9896
9897 ordering
9898
9899 Specifies the ordering relations on the rectangles. You can
9900 pass Unsorted, YSorted, YXSorted, or YXBanded.
9901
9902 The XSetClipRectangles function changes the clip-mask in the
9903 specified GC to the specified list of rectangles and sets the
9904 clip origin. The output is clipped to remain contained within
9905 the rectangles. The clip-origin is interpreted relative to the
9906 origin of whatever destination drawable is specified in a
9907 graphics request. The rectangle coordinates are interpreted
9908 relative to the clip-origin. The rectangles should be
9909 nonintersecting, or the graphics results will be undefined.
9910 Note that the list of rectangles can be empty, which
9911 effectively disables output. This is the opposite of passing
9912 None as the clip-mask in XCreateGC, XChangeGC, and
9913 XSetClipMask.
9914
9915 If known by the client, ordering relations on the rectangles
9916 can be specified with the ordering argument. This may provide
9917 faster operation by the server. If an incorrect ordering is
9918 specified, the X server may generate a BadMatch error, but it
9919 is not required to do so. If no error is generated, the
9920 graphics results are undefined. Unsorted means the rectangles
9921 are in arbitrary order. YSorted means that the rectangles are
9922 nondecreasing in their Y origin. YXSorted additionally
9923 constrains YSorted order in that all rectangles with an equal Y
9924 origin are nondecreasing in their X origin. YXBanded
9925 additionally constrains YXSorted by requiring that, for every
9926 possible Y scanline, all rectangles that include that scanline
9927 have an identical Y origins and Y extents.
9928
9929 XSetClipRectangles can generate BadAlloc, BadGC, BadMatch, and
9930 BadValue errors.
9931
9932 Xlib provides a set of basic functions for performing region
9933 arithmetic. For information about these functions, see section
9934 16.5.
9935
9936Setting the Arc Mode, Subwindow Mode, and Graphics Exposure
9937
9938 To set the arc mode of a given GC, use XSetArcMode.
9939
9940 XSetArcMode(Display *display, GC gc, int arc_mode);
9941
9942 display
9943
9944 Specifies the connection to the X server.
9945
9946 gc
9947
9948 Specifies the GC.
9949
9950 arc_mode
9951
9952 Specifies the arc mode. You can pass ArcChord or ArcPieSlice.
9953
9954 XSetArcMode can generate BadAlloc, BadGC, and BadValue errors.
9955
9956 To set the subwindow mode of a given GC, use XSetSubwindowMode.
9957
9958 XSetSubwindowMode(Display *display, GC gc, int subwindow_mode);
9959
9960 display
9961
9962 Specifies the connection to the X server.
9963
9964 gc
9965
9966 Specifies the GC.
9967
9968 subwindow_mode
9969
9970 Specifies the subwindow mode. You can pass ClipByChildren or
9971 IncludeInferiors.
9972
9973 XSetSubwindowMode can generate BadAlloc, BadGC, and BadValue
9974 errors.
9975
9976 To set the graphics-exposures flag of a given GC, use
9977 XSetGraphicsExposures.
9978
9979 XSetGraphicsExposures(Display *display, GC gc, Bool
9980 graphics_exposures);
9981
9982 display
9983
9984 Specifies the connection to the X server.
9985
9986 gc
9987
9988 Specifies the GC.
9989
9990 graphics_exposures
9991
9992 Specifies a Boolean value that indicates whether you want
9993 GraphicsExpose and NoExpose events to be reported when calling
9994 XCopyArea and XCopyPlane with this GC.
9995
9996 XSetGraphicsExposures can generate BadAlloc, BadGC, and
9997 BadValue errors.
9998
9999Chapter 8. Graphics Functions
10000
10001 Table of Contents
10002
10003 Clearing Areas
10004 Copying Areas
10005 Drawing Points, Lines, Rectangles, and Arcs
10006
10007 Drawing Single and Multiple Points
10008 Drawing Single and Multiple Lines
10009 Drawing Single and Multiple Rectangles
10010 Drawing Single and Multiple Arcs
10011
10012 Filling Areas
10013
10014 Filling Single and Multiple Rectangles
10015 Filling a Single Polygon
10016 Filling Single and Multiple Arcs
10017
10018 Font Metrics
10019
10020 Loading and Freeing Fonts
10021 Obtaining and Freeing Font Names and Information
10022 Computing Character String Sizes
10023 Computing Logical Extents
10024 Querying Character String Sizes
10025
10026 Drawing Text
10027
10028 Drawing Complex Text
10029 Drawing Text Characters
10030 Drawing Image Text Characters
10031
10032 Transferring Images between Client and Server
10033
10034 Once you have established a connection to a display, you can
10035 use the Xlib graphics functions to:
10036 * Clear and copy areas
10037 * Draw points, lines, rectangles, and arcs
10038 * Fill areas
10039 * Manipulate fonts
10040 * Draw text
10041 * Transfer images between clients and the server
10042
10043 If the same drawable and GC is used for each call, Xlib batches
10044 back-to-back calls to XDrawPoint, XDrawLine, XDrawRectangle,
10045 XFillArc, and XFillRectangle. Note that this reduces the total
10046 number of requests sent to the server.
10047
10048Clearing Areas
10049
10050 Xlib provides functions that you can use to clear an area or
10051 the entire window. Because pixmaps do not have defined
10052 backgrounds, they cannot be filled by using the functions
10053 described in this section. Instead, to accomplish an analogous
10054 operation on a pixmap, you should use XFillRectangle, which
10055 sets the pixmap to a known value.
10056
10057 To clear a rectangular area of a given window, use XClearArea.
10058
10059 XClearArea(Display *display, Window w, int x, int y, unsigned
10060 int width, unsigned int height, Bool exposures);
10061
10062 display
10063
10064 Specifies the connection to the X server.
10065
10066 w
10067
10068 Specifies the window.
10069
10070 x
10071
10072 y
10073
10074 Specify the x and y coordinates, which are relative to the
10075 origin of the window and specify the upper-left corner of the
10076 rectangle.
10077
10078 width
10079
10080 height
10081
10082 Specify the width and height, which are the dimensions of the
10083 rectangle.
10084
10085 exposures
10086
10087 Specifies a Boolean value that indicates if Expose events are
10088 to be generated.
10089
10090 The XClearArea function paints a rectangular area in the
10091 specified window according to the specified dimensions with the
10092 window's background pixel or pixmap. The subwindow-mode
10093 effectively is ClipByChildren. If width is zero, it is replaced
10094 with the current width of the window minus x. If height is
10095 zero, it is replaced with the current height of the window
10096 minus y. If the window has a defined background tile, the
10097 rectangle clipped by any children is filled with this tile. If
10098 the window has background None, the contents of the window are
10099 not changed. In either case, if exposures is True, one or more
10100 Expose events are generated for regions of the rectangle that
10101 are either visible or are being retained in a backing store. If
10102 you specify a window whose class is InputOnly, a BadMatch error
10103 results.
10104
10105 XClearArea can generate BadMatch, BadValue, and BadWindow
10106 errors.
10107
10108 To clear the entire area in a given window, use XClearWindow.
10109
10110 XClearWindow(Display *display, Window w);
10111
10112 display
10113
10114 Specifies the connection to the X server.
10115
10116 w
10117
10118 Specifies the window.
10119
10120 The XClearWindow function clears the entire area in the
10121 specified window and is equivalent to XClearArea (display, w,
10122 0, 0, 0, 0, False). If the window has a defined background
10123 tile, the rectangle is tiled with a plane-mask of all ones and
10124 GXcopy function. If the window has background None, the
10125 contents of the window are not changed. If you specify a window
10126 whose class is InputOnly, a BadMatch error results.
10127
10128 XClearWindow can generate BadMatch and BadWindow errors.
10129
10130Copying Areas
10131
10132 Xlib provides functions that you can use to copy an area or a
10133 bit plane.
10134
10135 To copy an area between drawables of the same root and depth,
10136 use XCopyArea.
10137
10138 XCopyArea(Display *display, Drawable src, Drawable dest, GC gc,
10139 int src_x, int src_y, unsigned int width, unsigned int height,
10140 int dest_x, int dest_y);
10141
10142 display
10143
10144 Specifies the connection to the X server.
10145
10146 src
10147
10148 dest
10149
10150 Specify the source and destination rectangles to be combined.
10151
10152 gc
10153
10154 Specifies the GC.
10155
10156 src_x
10157
10158 src_y
10159
10160 Specify the x and y coordinates, which are relative to the
10161 origin of the source rectangle and specify its upper-left
10162 corner.
10163
10164 width
10165
10166 height
10167
10168 Specify the width and height, which are the dimensions of both
10169 the source and destination rectangles.
10170
10171 dest_x
10172
10173 dest_y
10174
10175 Specify the x and y coordinates, which are relative to the
10176 origin of the destination rectangle and specify its upper-left
10177 corner.
10178
10179 The XCopyArea function combines the specified rectangle of src
10180 with the specified rectangle of dest. The drawables must have
10181 the same root and depth, or a BadMatch error results.
10182
10183 If regions of the source rectangle are obscured and have not
10184 been retained in backing store or if regions outside the
10185 boundaries of the source drawable are specified, those regions
10186 are not copied. Instead, the following occurs on all
10187 corresponding destination regions that are either visible or
10188 are retained in backing store. If the destination is a window
10189 with a background other than None, corresponding regions of the
10190 destination are tiled with that background (with plane-mask of
10191 all ones and GXcopy function). Regardless of tiling or whether
10192 the destination is a window or a pixmap, if graphics-exposures
10193 is True, then GraphicsExpose events for all corresponding
10194 destination regions are generated. If graphics-exposures is
10195 True but no GraphicsExpose events are generated, a NoExpose
10196 event is generated. Note that by default graphics-exposures is
10197 True in new GCs.
10198
10199 This function uses these GC components: function, plane-mask,
10200 subwindow-mode, graphics-exposures, clip-x-origin,
10201 clip-y-origin, and clip-mask.
10202
10203 XCopyArea can generate BadDrawable, BadGC, and BadMatch errors.
10204
10205 To copy a single bit plane of a given drawable, use XCopyPlane.
10206
10207 XCopyPlane(Display *display, Drawable src, Drawable dest, GC
10208 gc, int src_x, int src_y, unsigned int width, unsigned int
10209 height, int dest_x, int dest_y, unsigned long plane);
10210
10211 display
10212
10213 Specifies the connection to the X server.
10214
10215 src
10216
10217 dest
10218
10219 Specify the source and destination rectangles to be combined.
10220
10221 gc
10222
10223 Specifies the GC.
10224
10225 src_x
10226
10227 src_y
10228
10229 Specify the x and y coordinates, which are relative to the
10230 origin of the source rectangle and specify its upper-left
10231 corner.
10232
10233 width
10234
10235 height
10236
10237 Specify the width and height, which are the dimensions of both
10238 the source and destination rectangles.
10239
10240 dest_x
10241
10242 dest_y
10243
10244 Specify the x and y coordinates, which are relative to the
10245 origin of the destination rectangle and specify its upper-left
10246 corner.
10247
10248 plane
10249
10250 Specifies the bit plane. You must set exactly one bit to 1.
10251
10252 The XCopyPlane function uses a single bit plane of the
10253 specified source rectangle combined with the specified GC to
10254 modify the specified rectangle of dest. The drawables must have
10255 the same root but need not have the same depth. If the
10256 drawables do not have the same root, a BadMatch error results.
10257 If plane does not have exactly one bit set to 1 and the value
10258 of plane is not less than %2 sup n%, where n is the depth of
10259 src, a BadValue error results.
10260
10261 Effectively, XCopyPlane forms a pixmap of the same depth as the
10262 rectangle of dest and with a size specified by the source
10263 region. It uses the foreground/background pixels in the GC
10264 (foreground everywhere the bit plane in src contains a bit set
10265 to 1, background everywhere the bit plane in src contains a bit
10266 set to 0) and the equivalent of a CopyArea protocol request is
10267 performed with all the same exposure semantics. This can also
10268 be thought of as using the specified region of the source bit
10269 plane as a stipple with a fill-style of FillOpaqueStippled for
10270 filling a rectangular area of the destination.
10271
10272 This function uses these GC components: function, plane-mask,
10273 foreground, background, subwindow-mode, graphics-exposures,
10274 clip-x-origin, clip-y-origin, and clip-mask.
10275
10276 XCopyPlane can generate BadDrawable, BadGC, BadMatch, and
10277 BadValue errors.
10278
10279Drawing Points, Lines, Rectangles, and Arcs
10280
10281 Xlib provides functions that you can use to draw:
10282 * A single point or multiple points
10283 * A single line or multiple lines
10284 * A single rectangle or multiple rectangles
10285 * A single arc or multiple arcs
10286
10287 Some of the functions described in the following sections use
10288 these structures:
10289
10290
10291
10292typedef struct {
10293 short x1, y1, x2, y2;
10294} XSegment;
10295
10296
10297
10298typedef struct {
10299 short x, y;
10300} XPoint;
10301
10302
10303
10304typedef struct {
10305 short x, y;
10306 unsigned short width, height;
10307} XRectangle;
10308
10309
10310
10311typedef struct {
10312 short x, y;
10313 unsigned short width, height;
10314 short angle1, angle2; /* Degrees * 64 */
10315} XArc;
10316
10317 All x and y members are signed integers. The width and height
10318 members are 16-bit unsigned integers. You should be careful not
10319 to generate coordinates and sizes out of the 16-bit ranges,
10320 because the protocol only has 16-bit fields for these values.
10321
10322Drawing Single and Multiple Points
10323
10324 To draw a single point in a given drawable, use XDrawPoint.
10325
10326 XDrawPoint(Display *display, Drawable d, GC gc, int x, int y);
10327
10328 display
10329
10330 Specifies the connection to the X server.
10331
10332 d
10333
10334 Specifies the drawable.
10335
10336 gc
10337
10338 Specifies the GC.
10339
10340 x
10341
10342 y
10343
10344 Specify the x and y coordinates where you want the point drawn.
10345
10346 To draw multiple points in a given drawable, use XDrawPoints.
10347
10348 XDrawPoints(Display *display, Drawable d, GC gc, XPoint
10349 *points, int npoints, int mode);
10350
10351 display
10352
10353 Specifies the connection to the X server.
10354
10355 d
10356
10357 Specifies the drawable.
10358
10359 gc
10360
10361 Specifies the GC.
10362
10363 points
10364
10365 Specifies an array of points.
10366
10367 npoints
10368
10369 Specifies the number of points in the array.
10370
10371 mode
10372
10373 Specifies the coordinate mode. You can pass CoordModeOrigin or
10374 CoordModePrevious.
10375
10376 The XDrawPoint function uses the foreground pixel and function
10377 components of the GC to draw a single point into the specified
10378 drawable; XDrawPoints draws multiple points this way.
10379 CoordModeOrigin treats all coordinates as relative to the
10380 origin, and CoordModePrevious treats all coordinates after the
10381 first as relative to the previous point. XDrawPoints draws the
10382 points in the order listed in the array.
10383
10384 Both functions use these GC components: function, plane-mask,
10385 foreground, subwindow-mode, clip-x-origin, clip-y-origin, and
10386 clip-mask.
10387
10388 XDrawPoint can generate BadDrawable, BadGC, and BadMatch
10389 errors. XDrawPoints can generate BadDrawable, BadGC, BadMatch,
10390 and BadValue errors.
10391
10392Drawing Single and Multiple Lines
10393
10394 To draw a single line between two points in a given drawable,
10395 use XDrawLine.
10396
10397 XDrawLine(Display *display, Drawable d, GC gc, int x1, int y1,
10398 int x2, int y2);
10399
10400 display
10401
10402 Specifies the connection to the X server.
10403
10404 d
10405
10406 Specifies the drawable.
10407
10408 gc
10409
10410 Specifies the GC.
10411
10412 x1
10413
10414 y1
10415
10416 x2
10417
10418 y2
10419
10420 Specify the points (x1, y1) and (x2, y2) to be connected.
10421
10422 To draw multiple lines in a given drawable, use XDrawLines.
10423
10424 XDrawLines(Display *display, Drawable d, GC gc, XPoint *points,
10425 int npoints, int mode);
10426
10427 display
10428
10429 Specifies the connection to the X server.
10430
10431 d
10432
10433 Specifies the drawable.
10434
10435 gc
10436
10437 Specifies the GC.
10438
10439 points
10440
10441 Specifies an array of points.
10442
10443 npoints
10444
10445 Specifies the number of points in the array.
10446
10447 mode
10448
10449 Specifies the coordinate mode. You can pass CoordModeOrigin or
10450 CoordModePrevious.
10451
10452 To draw multiple, unconnected lines in a given drawable, use
10453 XDrawSegments.
10454
10455 XDrawSegments(Display *display, Drawable d, GC gc, XSegment
10456 *segments, int nsegments);
10457
10458 display
10459
10460 Specifies the connection to the X server.
10461
10462 d
10463
10464 Specifies the drawable.
10465
10466 gc
10467
10468 Specifies the GC.
10469
10470 segments
10471
10472 Specifies an array of segments.
10473
10474 nsegments
10475
10476 Specifies the number of segments in the array.
10477
10478 The XDrawLine function uses the components of the specified GC
10479 to draw a line between the specified set of points (x1, y1) and
10480 (x2, y2). It does not perform joining at coincident endpoints.
10481 For any given line, XDrawLine does not draw a pixel more than
10482 once. If lines intersect, the intersecting pixels are drawn
10483 multiple times.
10484
10485 The XDrawLines function uses the components of the specified GC
10486 to draw npoints-1 lines between each pair of points (point[i],
10487 point[i+1]) in the array of XPoint structures. It draws the
10488 lines in the order listed in the array. The lines join
10489 correctly at all intermediate points, and if the first and last
10490 points coincide, the first and last lines also join correctly.
10491 For any given line, XDrawLines does not draw a pixel more than
10492 once. If thin (zero line-width) lines intersect, the
10493 intersecting pixels are drawn multiple times. If wide lines
10494 intersect, the intersecting pixels are drawn only once, as
10495 though the entire PolyLine protocol request were a single,
10496 filled shape. CoordModeOrigin treats all coordinates as
10497 relative to the origin, and CoordModePrevious treats all
10498 coordinates after the first as relative to the previous point.
10499
10500 The XDrawSegments function draws multiple, unconnected lines.
10501 For each segment, XDrawSegments draws a line between (x1, y1)
10502 and (x2, y2). It draws the lines in the order listed in the
10503 array of XSegment structures and does not perform joining at
10504 coincident endpoints. For any given line, XDrawSegments does
10505 not draw a pixel more than once. If lines intersect, the
10506 intersecting pixels are drawn multiple times.
10507
10508 All three functions use these GC components: function,
10509 plane-mask, line-width, line-style, cap-style, fill-style,
10510 subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
10511 The XDrawLines function also uses the join-style GC component.
10512 All three functions also use these GC mode-dependent
10513 components: foreground, background, tile, stipple,
10514 tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and
10515 dash-list.
10516
10517 XDrawLine, XDrawLines, and XDrawSegments can generate
10518 BadDrawable, BadGC, and BadMatch errors. XDrawLines also can
10519 generate BadValue errors.
10520
10521Drawing Single and Multiple Rectangles
10522
10523 To draw the outline of a single rectangle in a given drawable,
10524 use XDrawRectangle.
10525
10526 XDrawRectangle(Display *display, Drawable d, GC gc, int x, int
10527 y, unsigned int width, unsigned int height);
10528
10529 display
10530
10531 Specifies the connection to the X server.
10532
10533 d
10534
10535 Specifies the drawable.
10536
10537 gc
10538
10539 Specifies the GC.
10540
10541 x
10542
10543 y
10544
10545 Specify the x and y coordinates, which specify the upper-left
10546 corner of the rectangle.
10547
10548 width
10549
10550 height
10551
10552 Specify the width and height, which specify the dimensions of
10553 the rectangle.
10554
10555 To draw the outline of multiple rectangles in a given drawable,
10556 use XDrawRectangles.
10557
10558 XDrawRectangles(Display *display, Drawable d, GC gc, XRectangle
10559 rectangles[], int nrectangles);
10560
10561 display
10562
10563 Specifies the connection to the X server.
10564
10565 d
10566
10567 Specifies the drawable.
10568
10569 gc
10570
10571 Specifies the GC.
10572
10573 rectangles
10574
10575 Specifies an array of rectangles.
10576
10577 nrectangles
10578
10579 Specifies the number of rectangles in the array.
10580
10581 The XDrawRectangle and XDrawRectangles functions draw the
10582 outlines of the specified rectangle or rectangles as if a
10583 five-point PolyLine protocol request were specified for each
10584 rectangle:
10585 * [x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
10586
10587 For the specified rectangle or rectangles, these functions do
10588 not draw a pixel more than once. XDrawRectangles draws the
10589 rectangles in the order listed in the array. If rectangles
10590 intersect, the intersecting pixels are drawn multiple times.
10591
10592 Both functions use these GC components: function, plane-mask,
10593 line-width, line-style, cap-style, join-style, fill-style,
10594 subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
10595 They also use these GC mode-dependent components: foreground,
10596 background, tile, stipple, tile-stipple-x-origin,
10597 tile-stipple-y-origin, dash-offset, and dash-list.
10598
10599 XDrawRectangle and XDrawRectangles can generate BadDrawable,
10600 BadGC, and BadMatch errors.
10601
10602Drawing Single and Multiple Arcs
10603
10604 To draw a single arc in a given drawable, use XDrawArc.
10605
10606 XDrawArc(Display *display, Drawable d, GC gc, int x, int y,
10607 unsigned int width, unsigned int height, int angle1, int
10608 angle2);
10609
10610 display
10611
10612 Specifies the connection to the X server.
10613
10614 d
10615
10616 Specifies the drawable.
10617
10618 gc
10619
10620 Specifies the GC.
10621
10622 x
10623
10624 y
10625
10626 Specify the x and y coordinates, which are relative to the
10627 origin of the drawable and specify the upper-left corner of the
10628 bounding rectangle.
10629
10630 width
10631
10632 height
10633
10634 Specify the width and height, which are the major and minor
10635 axes of the arc.
10636
10637 angle1
10638
10639 Specifies the start of the arc relative to the three-o'clock
10640 position from the center, in units of degrees * 64.
10641
10642 angle2
10643
10644 Specifies the path and extent of the arc relative to the start
10645 of the arc, in units of degrees * 64.
10646
10647 To draw multiple arcs in a given drawable, use XDrawArcs.
10648
10649 XDrawArcs(Display *display, Drawable d, GC gc, XArc *arcs, int
10650 narcs);
10651
10652 display
10653
10654 Specifies the connection to the X server.
10655
10656 d
10657
10658 Specifies the drawable.
10659
10660 gc
10661
10662 Specifies the GC.
10663
10664 arcs
10665
10666 Specifies an array of arcs.
10667
10668 narcs
10669
10670 Specifies the number of arcs in the array.
10671
10672 delim %% XDrawArc draws a single circular or elliptical arc,
10673 and XDrawArcs draws multiple circular or elliptical arcs. Each
10674 arc is specified by a rectangle and two angles. The center of
10675 the circle or ellipse is the center of the rectangle, and the
10676 major and minor axes are specified by the width and height.
10677 Positive angles indicate counterclockwise motion, and negative
10678 angles indicate clockwise motion. If the magnitude of angle2 is
10679 greater than 360 degrees, XDrawArc or XDrawArcs truncates it to
10680 360 degrees.
10681
10682 For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1,
10683 ~angle2 ]%, the origin of the major and minor axes is at % [ x
10684 +^ {width over 2} , ~y +^ {height over 2} ]%, and the
10685 infinitely thin path describing the entire circle or ellipse
10686 intersects the horizontal axis at % [ x, ~y +^ {height over 2}
10687 ]% and % [ x +^ width , ~y +^ { height over 2 }] % and
10688 intersects the vertical axis at % [ x +^ { width over 2 } , ~y
10689 ]% and % [ x +^ { width over 2 }, ~y +^ height ]%. These
10690 coordinates can be fractional and so are not truncated to
10691 discrete coordinates. The path should be defined by the ideal
10692 mathematical path. For a wide line with line-width lw, the
10693 bounding outlines for filling are given by the two infinitely
10694 thin paths consisting of all points whose perpendicular
10695 distance from the path of the circle/ellipse is equal to lw/2
10696 (which may be a fractional value). The cap-style and join-style
10697 are applied the same as for a line corresponding to the tangent
10698 of the circle/ellipse at the endpoint.
10699
10700 For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1,
10701 ~angle2 ]%, the angles must be specified in the effectively
10702 skewed coordinate system of the ellipse (for a circle, the
10703 angles and coordinate systems are identical). The relationship
10704 between these angles and angles expressed in the normal
10705 coordinate system of the screen (as measured with a protractor)
10706 is as follows:
10707
10708% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
10709 * width over height right ) +^ adjust%
10710
10711 The skewed-angle and normal-angle are expressed in radians
10712 (rather than in degrees scaled by 64) in the range % [ 0 , ~2
10713 pi ]% and where atan returns a value in the range % [ - pi over
10714 2 , ~pi over 2 ] % and adjust is:
10715
10716
10717
10718%0% for normal-angle in the range % [ 0 , ~pi over 2 ]%
10719%pi% for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2 ]
10720%
10721%2 pi% for normal-angle in the range % [ {3 pi} over 2 , ~2 pi ]%
10722
10723 For any given arc, XDrawArc and XDrawArcs do not draw a pixel
10724 more than once. If two arcs join correctly and if the
10725 line-width is greater than zero and the arcs intersect,
10726 XDrawArc and XDrawArcs do not draw a pixel more than once.
10727 Otherwise, the intersecting pixels of intersecting arcs are
10728 drawn multiple times. Specifying an arc with one endpoint and a
10729 clockwise extent draws the same pixels as specifying the other
10730 endpoint and an equivalent counterclockwise extent, except as
10731 it affects joins.
10732
10733 If the last point in one arc coincides with the first point in
10734 the following arc, the two arcs will join correctly. If the
10735 first point in the first arc coincides with the last point in
10736 the last arc, the two arcs will join correctly. By specifying
10737 one axis to be zero, a horizontal or vertical line can be
10738 drawn. Angles are computed based solely on the coordinate
10739 system and ignore the aspect ratio.
10740
10741 Both functions use these GC components: function, plane-mask,
10742 line-width, line-style, cap-style, join-style, fill-style,
10743 subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
10744 They also use these GC mode-dependent components: foreground,
10745 background, tile, stipple, tile-stipple-x-origin,
10746 tile-stipple-y-origin, dash-offset, and dash-list.
10747
10748 XDrawArc and XDrawArcs can generate BadDrawable, BadGC, and
10749 BadMatch errors.
10750
10751Filling Areas
10752
10753 Xlib provides functions that you can use to fill:
10754 * A single rectangle or multiple rectangles
10755 * A single polygon
10756 * A single arc or multiple arcs
10757
10758Filling Single and Multiple Rectangles
10759
10760 To fill a single rectangular area in a given drawable, use
10761 XFillRectangle.
10762
10763 XFillRectangle(Display *display, Drawable d, GC gc, int x, int
10764 y, unsigned int width, unsigned int height);
10765
10766 display
10767
10768 Specifies the connection to the X server.
10769
10770 d
10771
10772 Specifies the drawable.
10773
10774 gc
10775
10776 Specifies the GC.
10777
10778 x
10779
10780 y
10781
10782 Specify the x and y coordinates, which are relative to the
10783 origin of the drawable and specify the upper-left corner of the
10784 rectangle.
10785
10786 width
10787
10788 height
10789
10790 Specify the width and height, which are the dimensions of the
10791 rectangle to be filled.
10792
10793 To fill multiple rectangular areas in a given drawable, use
10794 XFillRectangles.
10795
10796 XFillRectangles(Display *display, Drawable d, GC gc, XRectangle
10797 *rectangles, int nrectangles);
10798
10799 display
10800
10801 Specifies the connection to the X server.
10802
10803 d
10804
10805 Specifies the drawable.
10806
10807 gc
10808
10809 Specifies the GC.
10810
10811 rectangles
10812
10813 Specifies an array of rectangles.
10814
10815 nrectangles
10816
10817 Specifies the number of rectangles in the array.
10818
10819 The XFillRectangle and XFillRectangles functions fill the
10820 specified rectangle or rectangles as if a four-point
10821 FillPolygon protocol request were specified for each rectangle:
10822
10823[x,y] [x+width,y] [x+width,y+height] [x,y+height]
10824
10825 Each function uses the x and y coordinates, width and height
10826 dimensions, and GC you specify.
10827
10828 XFillRectangles fills the rectangles in the order listed in the
10829 array. For any given rectangle, XFillRectangle and
10830 XFillRectangles do not draw a pixel more than once. If
10831 rectangles intersect, the intersecting pixels are drawn
10832 multiple times.
10833
10834 Both functions use these GC components: function, plane-mask,
10835 fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
10836 clip-mask. They also use these GC mode-dependent components:
10837 foreground, background, tile, stipple, tile-stipple-x-origin,
10838 and tile-stipple-y-origin.
10839
10840 XFillRectangle and XFillRectangles can generate BadDrawable,
10841 BadGC, and BadMatch errors.
10842
10843Filling a Single Polygon
10844
10845 To fill a polygon area in a given drawable, use XFillPolygon.
10846
10847 XFillPolygon(Display *display, Drawable d, GC gc, XPoint
10848 *points, int npoints, int shape, int mode);
10849
10850 display
10851
10852 Specifies the connection to the X server.
10853
10854 d
10855
10856 Specifies the drawable.
10857
10858 gc
10859
10860 Specifies the GC.
10861
10862 points
10863
10864 Specifies an array of points.
10865
10866 npoints
10867
10868 Specifies the number of points in the array.
10869
10870 shape
10871
10872 Specifies a shape that helps the server to improve performance.
10873 You can pass Complex, Convex, or Nonconvex.
10874
10875 mode
10876
10877 Specifies the coordinate mode. You can pass CoordModeOrigin or
10878 CoordModePrevious.
10879
10880 XFillPolygon fills the region closed by the specified path. The
10881 path is closed automatically if the last point in the list does
10882 not coincide with the first point. XFillPolygon does not draw a
10883 pixel of the region more than once. CoordModeOrigin treats all
10884 coordinates as relative to the origin, and CoordModePrevious
10885 treats all coordinates after the first as relative to the
10886 previous point.
10887
10888 Depending on the specified shape, the following occurs:
10889 * If shape is Complex, the path may self-intersect. Note that
10890 contiguous coincident points in the path are not treated as
10891 self-intersection.
10892 * If shape is Convex, for every pair of points inside the
10893 polygon, the line segment connecting them does not
10894 intersect the path. If known by the client, specifying
10895 Convex can improve performance. If you specify Convex for a
10896 path that is not convex, the graphics results are
10897 undefined.
10898 * If shape is Nonconvex, the path does not self-intersect,
10899 but the shape is not wholly convex. If known by the client,
10900 specifying Nonconvex instead of Complex may improve
10901 performance. If you specify Nonconvex for a
10902 self-intersecting path, the graphics results are undefined.
10903
10904 The fill-rule of the GC controls the filling behavior of
10905 self-intersecting polygons.
10906
10907 This function uses these GC components: function, plane-mask,
10908 fill-style, fill-rule, subwindow-mode, clip-x-origin,
10909 clip-y-origin, and clip-mask. It also uses these GC
10910 mode-dependent components: foreground, background, tile,
10911 stipple, tile-stipple-x-origin, and tile-stipple-y-origin.
10912
10913 XFillPolygon can generate BadDrawable, BadGC, BadMatch, and
10914 BadValue errors.
10915
10916Filling Single and Multiple Arcs
10917
10918 To fill a single arc in a given drawable, use XFillArc.
10919
10920 XFillArc(Display *display, Drawable d, GC gc, int x, int y,
10921 unsigned int width, unsigned int height, int angle1, int
10922 angle2);
10923
10924 display
10925
10926 Specifies the connection to the X server.
10927
10928 d
10929
10930 Specifies the drawable.
10931
10932 gc
10933
10934 Specifies the GC.
10935
10936 x
10937
10938 y
10939
10940 Specify the x and y coordinates, which are relative to the
10941 origin of the drawable and specify the upper-left corner of the
10942 bounding rectangle.
10943
10944 width
10945
10946 height
10947
10948 Specify the width and height, which are the major and minor
10949 axes of the arc.
10950
10951 angle1
10952
10953 Specifies the start of the arc relative to the three-o'clock
10954 position from the center, in units of degrees * 64.
10955
10956 angle2
10957
10958 Specifies the path and extent of the arc relative to the start
10959 of the arc, in units of degrees * 64.
10960
10961 To fill multiple arcs in a given drawable, use XFillArcs.
10962
10963 XFillArcs(Display *display, Drawable d, GC gc, XArc *arcs, int
10964 narcs);
10965
10966 display
10967
10968 Specifies the connection to the X server.
10969
10970 d
10971
10972 Specifies the drawable.
10973
10974 gc
10975
10976 Specifies the GC.
10977
10978 arcs
10979
10980 Specifies an array of arcs.
10981
10982 narcs
10983
10984 Specifies the number of arcs in the array.
10985
10986 For each arc, XFillArc or XFillArcs fills the region closed by
10987 the infinitely thin path described by the specified arc and,
10988 depending on the arc-mode specified in the GC, one or two line
10989 segments. For ArcChord, the single line segment joining the
10990 endpoints of the arc is used. For ArcPieSlice, the two line
10991 segments joining the endpoints of the arc with the center point
10992 are used. XFillArcs fills the arcs in the order listed in the
10993 array. For any given arc, XFillArc and XFillArcs do not draw a
10994 pixel more than once. If regions intersect, the intersecting
10995 pixels are drawn multiple times.
10996
10997 Both functions use these GC components: function, plane-mask,
10998 fill-style, arc-mode, subwindow-mode, clip-x-origin,
10999 clip-y-origin, and clip-mask. They also use these GC
11000 mode-dependent components: foreground, background, tile,
11001 stipple, tile-stipple-x-origin, and tile-stipple-y-origin.
11002
11003 XFillArc and XFillArcs can generate BadDrawable, BadGC, and
11004 BadMatch errors.
11005
11006Font Metrics
11007
11008 A font is a graphical description of a set of characters that
11009 are used to increase efficiency whenever a set of small,
11010 similar sized patterns are repeatedly used.
11011
11012 This section discusses how to:
11013 * Load and free fonts
11014 * Obtain and free font names
11015 * Compute character string sizes
11016 * Compute logical extents
11017 * Query character string sizes
11018
11019 The X server loads fonts whenever a program requests a new
11020 font. The server can cache fonts for quick lookup. Fonts are
11021 global across all screens in a server. Several levels are
11022 possible when dealing with fonts. Most applications simply use
11023 XLoadQueryFont to load a font and query the font metrics.
11024
11025 Characters in fonts are regarded as masks. Except for image
11026 text requests, the only pixels modified are those in which bits
11027 are set to 1 in the character. This means that it makes sense
11028 to draw text using stipples or tiles (for example, many menus
11029 gray-out unusable entries).
11030
11031 The XFontStruct structure contains all of the information for
11032 the font and consists of the font-specific information as well
11033 as a pointer to an array of XCharStruct structures for the
11034 characters contained in the font. The XFontStruct, XFontProp,
11035 and XCharStruct structures contain:
11036
11037
11038
11039typedef struct {
11040 short lbearing; /* origin to left edge of raster */
11041 short rbearing; /* origin to right edge of raster */
11042 short width; /* advance to next char's origin */
11043 short ascent; /* baseline to top edge of raster */
11044 short descent; /* baseline to bottom edge of raster
11045*/
11046 unsigned short attributes; /* per char flags (not predefined) */
11047} XCharStruct;
11048
11049
11050
11051typedef struct {
11052 Atom name;
11053 unsigned long card32;
11054} XFontProp;
11055
11056
11057
11058typedef struct { /* normal 16 bit characters are two bytes */
11059 unsigned char byte1;
11060 unsigned char byte2;
11061} XChar2b;
11062
11063
11064
11065typedef struct {
11066 XExtData *ext_data; /* hook for extension to hang dat
11067a */
11068 Font fid; /* Font id for this font */
11069 unsigned direction; /* hint about the direction font
11070is painted */
11071 unsigned min_char_or_byte2; /* first character */
11072 unsigned max_char_or_byte2; /* last character */
11073 unsigned min_byte1; /* first row that exists */
11074 unsigned max_byte1; /* last row that exists */
11075 Bool all_chars_exist; /* flag if all characters have no
11076nzero size */
11077 unsigned default_char; /* char to print for undefined ch
11078aracter */
11079 int n_properties; /* how many properties there are
11080*/
11081 XFontProp *properties; /* pointer to array of additional
11082 properties */
11083 XCharStruct min_bounds; /* minimum bounds over all existi
11084ng char */
11085 XCharStruct max_bounds; /* maximum bounds over all existi
11086ng char */
11087 XCharStruct *per_char; /* first_char to last_char inform
11088ation */
11089 int ascent; /* logical extent above baseline
11090for spacing */
11091 int descent; /* logical descent below baseline
11092 for spacing */
11093} XFontStruct;
11094
11095 X supports single byte/character, two bytes/character matrix,
11096 and 16-bit character text operations. Note that any of these
11097 forms can be used with a font, but a single byte/character text
11098 request can only specify a single byte (that is, the first row
11099 of a 2-byte font). You should view 2-byte fonts as a
11100 two-dimensional matrix of defined characters: byte1 specifies
11101 the range of defined rows and byte2 defines the range of
11102 defined columns of the font. Single byte/character fonts have
11103 one row defined, and the byte2 range specified in the structure
11104 defines a range of characters.
11105
11106 The bounding box of a character is defined by the XCharStruct
11107 of that character. When characters are absent from a font, the
11108 default_char is used. When fonts have all characters of the
11109 same size, only the information in the XFontStruct min and max
11110 bounds are used.
11111
11112 The members of the XFontStruct have the following semantics:
11113 * The direction member can be either FontLeftToRight or
11114 FontRightToLeft. It is just a hint as to whether most
11115 XCharStruct elements have a positive (FontLeftToRight) or a
11116 negative (FontRightToLeft) character width metric. The core
11117 protocol defines no support for vertical text.
11118 * If the min_byte1 and max_byte1 members are both zero,
11119 min_char_or_byte2 specifies the linear character index
11120 corresponding to the first element of the per_char array,
11121 and max_char_or_byte2 specifies the linear character index
11122 of the last element.
11123 * If either min_byte1 or max_byte1 are nonzero, both
11124 min_char_or_byte2 and max_char_or_byte2 are less than 256,
11125 and the 2-byte character index values corresponding to the
11126 per_char array element N (counting from 0) are:
11127 * byte1 = N/D + min_byte1 byte2 = N\\D + min_char_or_byte2
11128 * where:
11129 * D = max_char_or_byte2 - min_char_or_byte2 + 1 / = integer
11130 division \\ = integer modulus
11131 * If the per_char pointer is NULL, all glyphs between the
11132 first and last character indexes inclusive have the same
11133 information, as given by both min_bounds and max_bounds.
11134 * If all_chars_exist is True, all characters in the per_char
11135 array have nonzero bounding boxes.
11136 * The default_char member specifies the character that will
11137 be used when an undefined or nonexistent character is
11138 printed. The default_char is a 16-bit character (not a
11139 2-byte character). For a font using 2-byte matrix format,
11140 the default_char has byte1 in the most-significant byte and
11141 byte2 in the least significant byte. If the default_char
11142 itself specifies an undefined or nonexistent character, no
11143 printing is performed for an undefined or nonexistent
11144 character.
11145 * The min_bounds and max_bounds members contain the most
11146 extreme values of each individual XCharStruct component
11147 over all elements of this array (and ignore nonexistent
11148 characters). The bounding box of the font (the smallest
11149 rectangle enclosing the shape obtained by superimposing all
11150 of the characters at the same origin [x,y]) has its
11151 upper-left coordinate at:
11152 [x + min_bounds.lbearing, y - max_bounds.ascent]
11153
11154 * Its width is:
11155 max_bounds.rbearing - min_bounds.lbearing
11156
11157 * Its height is:
11158 max_bounds.ascent + max_bounds.descent
11159
11160 * The ascent member is the logical extent of the font above
11161 the baseline that is used for determining line spacing.
11162 Specific characters may extend beyond this.
11163 * The descent member is the logical extent of the font at or
11164 below the baseline that is used for determining line
11165 spacing. Specific characters may extend beyond this.
11166 * If the baseline is at Y-coordinate y, the logical extent of
11167 the font is inclusive between the Y-coordinate values (y -
11168 font.ascent) and (y + font.descent - 1). Typically, the
11169 minimum interline spacing between rows of text is given by
11170 ascent + descent.
11171
11172 For a character origin at [x,y], the bounding box of a
11173 character (that is, the smallest rectangle that encloses the
11174 character's shape) described in terms of XCharStruct components
11175 is a rectangle with its upper-left corner at:
11176
11177[x + lbearing, y - ascent]
11178
11179 Its width is:
11180
11181rbearing - lbearing
11182
11183 Its height is:
11184
11185ascent + descent
11186
11187 The origin for the next character is defined to be:
11188
11189[x + width, y]
11190
11191 The lbearing member defines the extent of the left edge of the
11192 character ink from the origin. The rbearing member defines the
11193 extent of the right edge of the character ink from the origin.
11194 The ascent member defines the extent of the top edge of the
11195 character ink from the origin. The descent member defines the
11196 extent of the bottom edge of the character ink from the origin.
11197 The width member defines the logical width of the character.
11198
11199 Note that the baseline (the y position of the character origin)
11200 is logically viewed as being the scanline just below
11201 nondescending characters. When descent is zero, only pixels
11202 with Y-coordinates less than y are drawn, and the origin is
11203 logically viewed as being coincident with the left edge of a
11204 nonkerned character. When lbearing is zero, no pixels with
11205 X-coordinate less than x are drawn. Any of the XCharStruct
11206 metric members could be negative. If the width is negative, the
11207 next character will be placed to the left of the current
11208 origin.
11209
11210 The X protocol does not define the interpretation of the
11211 attributes member in the XCharStruct structure. A nonexistent
11212 character is represented with all members of its XCharStruct
11213 set to zero.
11214
11215 A font is not guaranteed to have any properties. The
11216 interpretation of the property value (for example, long or
11217 unsigned long) must be derived from a priori knowledge of the
11218 property. A basic set of font properties is specified in the X
11219 Consortium standard X Logical Font Description Conventions.
11220
11221Loading and Freeing Fonts
11222
11223 Xlib provides functions that you can use to load fonts, get
11224 font information, unload fonts, and free font information. A
11225 few font functions use a GContext resource ID or a font ID
11226 interchangeably.
11227
11228 To load a given font, use XLoadFont.
11229
11230 Font XLoadFont(Display *display, char *name);
11231
11232 display
11233
11234 Specifies the connection to the X server.
11235
11236 name
11237
11238 Specifies the name of the font, which is a null-terminated
11239 string.
11240
11241 The XLoadFont function loads the specified font and returns its
11242 associated font ID. If the font name is not in the Host
11243 Portable Character Encoding, the result is
11244 implementation-dependent. Use of uppercase or lowercase does
11245 not matter. When the characters ``?'' and ``*'' are used in a
11246 font name, a pattern match is performed and any matching font
11247 is used. In the pattern, the ``?'' character will match any
11248 single character, and the ``*'' character will match any number
11249 of characters. A structured format for font names is specified
11250 in the X Consortium standard X Logical Font Description
11251 Conventions. If XLoadFont was unsuccessful at loading the
11252 specified font, a BadName error results. Fonts are not
11253 associated with a particular screen and can be stored as a
11254 component of any GC. When the font is no longer needed, call
11255 XUnloadFont.
11256
11257 XLoadFont can generate BadAlloc and BadName errors.
11258
11259 To return information about an available font, use XQueryFont.
11260
11261 XFontStruct *XQueryFont(Display *display, XID font_ID);
11262
11263 display
11264
11265 Specifies the connection to the X server.
11266
11267 font_ID
11268
11269 Specifies the font ID or the GContext ID.
11270
11271 The XQueryFont function returns a pointer to the XFontStruct
11272 structure, which contains information associated with the font.
11273 You can query a font or the font stored in a GC. The font ID
11274 stored in the XFontStruct structure will be the GContext ID,
11275 and you need to be careful when using this ID in other
11276 functions (see XGContextFromGC). If the font does not exist,
11277 XQueryFont returns NULL. To free this data, use XFreeFontInfo.
11278
11279 To perform a XLoadFont and XQueryFont in a single operation,
11280 use XLoadQueryFont.
11281
11282 XFontStruct *XLoadQueryFont(Display *display, char *name);
11283
11284 display
11285
11286 Specifies the connection to the X server.
11287
11288 name
11289
11290 Specifies the name of the font, which is a null-terminated
11291 string.
11292
11293 The XLoadQueryFont function provides the most common way for
11294 accessing a font. XLoadQueryFont both opens (loads) the
11295 specified font and returns a pointer to the appropriate
11296 XFontStruct structure. If the font name is not in the Host
11297 Portable Character Encoding, the result is
11298 implementation-dependent. If the font does not exist,
11299 XLoadQueryFont returns NULL.
11300
11301 XLoadQueryFont can generate a BadAlloc error.
11302
11303 To unload the font and free the storage used by the font
11304 structure that was allocated by XQueryFont or XLoadQueryFont,
11305 use XFreeFont.
11306
11307 XFreeFont(Display *display, XFontStruct *font_struct);
11308
11309 display
11310
11311 Specifies the connection to the X server.
11312
11313 font_struct
11314
11315 Specifies the storage associated with the font.
11316
11317 The XFreeFont function deletes the association between the font
11318 resource ID and the specified font and frees the XFontStruct
11319 structure. The font itself will be freed when no other resource
11320 references it. The data and the font should not be referenced
11321 again.
11322
11323 XFreeFont can generate a BadFont error.
11324
11325 To return a given font property, use XGetFontProperty.
11326
11327 Bool XGetFontProperty(XFontStruct *font_struct, Atom atom,
11328 unsigned long *value_return);
11329
11330 font_struct
11331
11332 Specifies the storage associated with the font.
11333
11334 atom
11335
11336 Specifies the atom for the property name you want returned.
11337
11338 value_return
11339
11340 Returns the value of the font property.
11341
11342 Given the atom for that property, the XGetFontProperty function
11343 returns the value of the specified font property.
11344 XGetFontProperty also returns False if the property was not
11345 defined or True if it was defined. A set of predefined atoms
11346 exists for font properties, which can be found in
11347 <X11/Xatom.h>. This set contains the standard properties
11348 associated with a font. Although it is not guaranteed, it is
11349 likely that the predefined font properties will be present.
11350
11351 To unload a font that was loaded by XLoadFont, use XUnloadFont.
11352
11353 XUnloadFont(Display *display, Font font);
11354
11355 display
11356
11357 Specifies the connection to the X server.
11358
11359 font
11360
11361 Specifies the font.
11362
11363 The XUnloadFont function deletes the association between the
11364 font resource ID and the specified font. The font itself will
11365 be freed when no other resource references it. The font should
11366 not be referenced again.
11367
11368 XUnloadFont can generate a BadFont error.
11369
11370Obtaining and Freeing Font Names and Information
11371
11372 You obtain font names and information by matching a wildcard
11373 specification when querying a font type for a list of available
11374 sizes and so on.
11375
11376 To return a list of the available font names, use XListFonts.
11377
11378 char **XListFonts(Display *display, char *pattern, int
11379 maxnames, int *actual_count_return);
11380
11381 display
11382
11383 Specifies the connection to the X server.
11384
11385 pattern
11386
11387 Specifies the null-terminated pattern string that can contain
11388 wildcard characters.
11389
11390 maxnames
11391
11392 Specifies the maximum number of names to be returned.
11393
11394 actual_count_return
11395
11396 Returns the actual number of font names.
11397
11398 The XListFonts function returns an array of available font
11399 names (as controlled by the font search path; see XSetFontPath)
11400 that match the string you passed to the pattern argument. The
11401 pattern string can contain any characters, but each asterisk
11402 (*) is a wildcard for any number of characters, and each
11403 question mark (?) is a wildcard for a single character. If the
11404 pattern string is not in the Host Portable Character Encoding,
11405 the result is implementation-dependent. Use of uppercase or
11406 lowercase does not matter. Each returned string is
11407 null-terminated. If the data returned by the server is in the
11408 Latin Portable Character Encoding, then the returned strings
11409 are in the Host Portable Character Encoding. Otherwise, the
11410 result is implementation-dependent. If there are no matching
11411 font names, XListFonts returns NULL. The client should call
11412 XFreeFontNames when finished with the result to free the
11413 memory.
11414
11415 To free a font name array, use XFreeFontNames.
11416
11417 XFreeFontNames(char *list[]);
11418
11419 list
11420
11421 Specifies the array of strings you want to free.
11422
11423 The XFreeFontNames function frees the array and strings
11424 returned by XListFonts or XListFontsWithInfo.
11425
11426 To obtain the names and information about available fonts, use
11427 XListFontsWithInfo.
11428
11429 char **XListFontsWithInfo(Display *display, char *pattern, int
11430 maxnames, int *count_return, XFontStruct **info_return);
11431
11432 display
11433
11434 Specifies the connection to the X server.
11435
11436 pattern
11437
11438 Specifies the null-terminated pattern string that can contain
11439 wildcard characters.
11440
11441 maxnames
11442
11443 Specifies the maximum number of names to be returned.
11444
11445 count_return
11446
11447 Returns the actual number of matched font names.
11448
11449 info_return
11450
11451 Returns the font information.
11452
11453 The XListFontsWithInfo function returns a list of font names
11454 that match the specified pattern and their associated font
11455 information. The list of names is limited to size specified by
11456 maxnames. The information returned for each font is identical
11457 to what XLoadQueryFont would return except that the
11458 per-character metrics are not returned. The pattern string can
11459 contain any characters, but each asterisk (*) is a wildcard for
11460 any number of characters, and each question mark (?) is a
11461 wildcard for a single character. If the pattern string is not
11462 in the Host Portable Character Encoding, the result is
11463 implementation-dependent. Use of uppercase or lowercase does
11464 not matter. Each returned string is null-terminated. If the
11465 data returned by the server is in the Latin Portable Character
11466 Encoding, then the returned strings are in the Host Portable
11467 Character Encoding. Otherwise, the result is
11468 implementation-dependent. If there are no matching font names,
11469 XListFontsWithInfo returns NULL.
11470
11471 To free only the allocated name array, the client should call
11472 XFreeFontNames. To free both the name array and the font
11473 information array or to free just the font information array,
11474 the client should call XFreeFontInfo.
11475
11476 To free font structures and font names, use XFreeFontInfo.
11477
11478 XFreeFontInfo(char **names, XFontStruct *free_info, int
11479 actual_count);
11480
11481 names
11482
11483 Specifies the list of font names.
11484
11485 free_info
11486
11487 Specifies the font information.
11488
11489 actual_count
11490
11491 Specifies the actual number of font names.
11492
11493 The XFreeFontInfo function frees a font structure or an array
11494 of font structures and optionally an array of font names. If
11495 NULL is passed for names, no font names are freed. If a font
11496 structure for an open font (returned by XLoadQueryFont) is
11497 passed, the structure is freed, but the font is not closed; use
11498 XUnloadFont to close the font.
11499
11500Computing Character String Sizes
11501
11502 Xlib provides functions that you can use to compute the width,
11503 the logical extents, and the server information about 8-bit and
11504 2-byte text strings. The width is computed by adding the
11505 character widths of all the characters. It does not matter if
11506 the font is an 8-bit or 2-byte font. These functions return the
11507 sum of the character metrics in pixels.
11508
11509 To determine the width of an 8-bit character string, use
11510 XTextWidth.
11511
11512 int XTextWidth(XFontStruct *font_struct, char *string, int
11513 count);
11514
11515 font_struct
11516
11517 Specifies the font used for the width computation.
11518
11519 string
11520
11521 Specifies the character string.
11522
11523 count
11524
11525 Specifies the character count in the specified string.
11526
11527 To determine the width of a 2-byte character string, use
11528 XTextWidth16.
11529
11530 int XTextWidth16(XFontStruct *font_struct, XChar2b *string, int
11531 count);
11532
11533 font_struct
11534
11535 Specifies the font used for the width computation.
11536
11537 string
11538
11539 Specifies the character string.
11540
11541 count
11542
11543 Specifies the character count in the specified string.
11544
11545Computing Logical Extents
11546
11547 To compute the bounding box of an 8-bit character string in a
11548 given font, use XTextExtents.
11549
11550 XTextExtents(XFontStruct *font_struct, char *string, int
11551 nchars, int *direction_return, int *font_ascent_return, int
11552 *font_descent_return, XCharStruct *overall_return);
11553
11554 font_struct
11555
11556 Specifies the XFontStruct structure.
11557
11558 string
11559
11560 Specifies the character string.
11561
11562 nchars
11563
11564 Specifies the number of characters in the character string.
11565
11566 direction_return
11567
11568 Returns the value of the direction hint (FontLeftToRight or
11569 FontRightToLeft).
11570
11571 font_ascent_return
11572
11573 Returns the font ascent.
11574
11575 font_descent_return
11576
11577 Returns the font descent.
11578
11579 overall_return
11580
11581 Returns the overall size in the specified XCharStruct
11582 structure.
11583
11584 To compute the bounding box of a 2-byte character string in a
11585 given font, use XTextExtents16.
11586
11587 XTextExtents16(XFontStruct *font_struct, XChar2b *string, int
11588 nchars, int *direction_return, int *font_ascent_return, int
11589 *font_descent_return, XCharStruct *overall_return);
11590
11591 font_struct
11592
11593 Specifies the XFontStruct structure.
11594
11595 string
11596
11597 Specifies the character string.
11598
11599 nchars
11600
11601 Specifies the number of characters in the character string.
11602
11603 direction_return
11604
11605 Returns the value of the direction hint (FontLeftToRight or
11606 FontRightToLeft).
11607
11608 font_ascent_return
11609
11610 Returns the font ascent.
11611
11612 font_descent_return
11613
11614 Returns the font descent.
11615
11616 overall_return
11617
11618 Returns the overall size in the specified XCharStruct
11619 structure.
11620
11621 The XTextExtents and XTextExtents16 functions perform the size
11622 computation locally and, thereby, avoid the round-trip overhead
11623 of XQueryTextExtents and XQueryTextExtents16. Both functions
11624 return an XCharStruct structure, whose members are set to the
11625 values as follows.
11626
11627 The ascent member is set to the maximum of the ascent metrics
11628 of all characters in the string. The descent member is set to
11629 the maximum of the descent metrics. The width member is set to
11630 the sum of the character-width metrics of all characters in the
11631 string. For each character in the string, let W be the sum of
11632 the character-width metrics of all characters preceding it in
11633 the string. Let L be the left-side-bearing metric of the
11634 character plus W. Let R be the right-side-bearing metric of the
11635 character plus W. The lbearing member is set to the minimum L
11636 of all characters in the string. The rbearing member is set to
11637 the maximum R.
11638
11639 For fonts defined with linear indexing rather than 2-byte
11640 matrix indexing, each XChar2b structure is interpreted as a
11641 16-bit number with byte1 as the most significant byte. If the
11642 font has no defined default character, undefined characters in
11643 the string are taken to have all zero metrics.
11644
11645Querying Character String Sizes
11646
11647 To query the server for the bounding box of an 8-bit character
11648 string in a given font, use XQueryTextExtents.
11649
11650 XQueryTextExtents(Display *display, XID font_ID, char *string,
11651 int nchars, int *direction_return, int *font_ascent_return, int
11652 *font_descent_return, XCharStruct *overall_return);
11653
11654 display
11655
11656 Specifies the connection to the X server.
11657
11658 font_ID
11659
11660 Specifies either the font ID or the GContext ID that contains
11661 the font.
11662
11663 string
11664
11665 Specifies the character string.
11666
11667 nchars
11668
11669 Specifies the number of characters in the character string.
11670
11671 direction_return
11672
11673 Returns the value of the direction hint (FontLeftToRight or
11674 FontRightToLeft).
11675
11676 font_ascent_return
11677
11678 Returns the font ascent.
11679
11680 font_descent_return
11681
11682 Returns the font descent.
11683
11684 overall_return
11685
11686 Returns the overall size in the specified XCharStruct
11687 structure.
11688
11689 To query the server for the bounding box of a 2-byte character
11690 string in a given font, use XQueryTextExtents16.
11691
11692 XQueryTextExtents16(Display *display, XID font_ID, XChar2b
11693 *string, int nchars, int *direction_return, int
11694 *font_ascent_return, int *font_descent_return, XCharStruct
11695 *overall_return);
11696
11697 display
11698
11699 Specifies the connection to the X server.
11700
11701 font_ID
11702
11703 Specifies either the font ID or the GContext ID that contains
11704 the font.
11705
11706 string
11707
11708 Specifies the character string.
11709
11710 nchars
11711
11712 Specifies the number of characters in the character string.
11713
11714 direction_return
11715
11716 Returns the value of the direction hint (FontLeftToRight or
11717 FontRightToLeft).
11718
11719 font_ascent_return
11720
11721 Returns the font ascent.
11722
11723 font_descent_return
11724
11725 Returns the font descent.
11726
11727 overall_return
11728
11729 Returns the overall size in the specified XCharStruct
11730 structure.
11731
11732 The XQueryTextExtents and XQueryTextExtents16 functions return
11733 the bounding box of the specified 8-bit and 16-bit character
11734 string in the specified font or the font contained in the
11735 specified GC. These functions query the X server and,
11736 therefore, suffer the round-trip overhead that is avoided by
11737 XTextExtents and XTextExtents16. Both functions return a
11738 XCharStruct structure, whose members are set to the values as
11739 follows.
11740
11741 The ascent member is set to the maximum of the ascent metrics
11742 of all characters in the string. The descent member is set to
11743 the maximum of the descent metrics. The width member is set to
11744 the sum of the character-width metrics of all characters in the
11745 string. For each character in the string, let W be the sum of
11746 the character-width metrics of all characters preceding it in
11747 the string. Let L be the left-side-bearing metric of the
11748 character plus W. Let R be the right-side-bearing metric of the
11749 character plus W. The lbearing member is set to the minimum L
11750 of all characters in the string. The rbearing member is set to
11751 the maximum R.
11752
11753 For fonts defined with linear indexing rather than 2-byte
11754 matrix indexing, each XChar2b structure is interpreted as a
11755 16-bit number with byte1 as the most significant byte. If the
11756 font has no defined default character, undefined characters in
11757 the string are taken to have all zero metrics.
11758
11759 Characters with all zero metrics are ignored. If the font has
11760 no defined default_char, the undefined characters in the string
11761 are also ignored.
11762
11763 XQueryTextExtents and XQueryTextExtents16 can generate BadFont
11764 and BadGC errors.
11765
11766Drawing Text
11767
11768 This section discusses how to draw:
11769 * Complex text
11770 * Text characters
11771 * Image text characters
11772
11773 The fundamental text functions XDrawText and XDrawText16 use
11774 the following structures:
11775
11776
11777
11778typedef struct {
11779 char *chars; /* pointer to string */
11780 int nchars; /* number of characters */
11781 int delta; /* delta between strings */
11782 Font font; /* Font to print it in, None don't change */
11783} XTextItem;
11784
11785
11786
11787typedef struct {
11788 XChar2b *chars; /* pointer to two-byte characters */
11789 int nchars; /* number of characters */
11790 int delta; /* delta between strings */
11791 Font font; /* font to print it in, None don't change */
11792} XTextItem16;
11793
11794 If the font member is not None, the font is changed before
11795 printing and also is stored in the GC. If an error was
11796 generated during text drawing, the previous items may have been
11797 drawn. The baseline of the characters are drawn starting at the
11798 x and y coordinates that you pass in the text drawing
11799 functions.
11800
11801 For example, consider the background rectangle drawn by
11802 XDrawImageString. If you want the upper-left corner of the
11803 background rectangle to be at pixel coordinate (x,y), pass the
11804 (x,y + ascent) as the baseline origin coordinates to the text
11805 functions. The ascent is the font ascent, as given in the
11806 XFontStruct structure. If you want the lower-left corner of the
11807 background rectangle to be at pixel coordinate (x,y), pass the
11808 (x,y - descent + 1) as the baseline origin coordinates to the
11809 text functions. The descent is the font descent, as given in
11810 the XFontStruct structure.
11811
11812Drawing Complex Text
11813
11814 To draw 8-bit characters in a given drawable, use XDrawText.
11815
11816 XDrawText(Display *display, Drawable d, GC gc, int x, int y,
11817 XTextItem *items, int nitems);
11818
11819 display
11820
11821 Specifies the connection to the X server.
11822
11823 d
11824
11825 Specifies the drawable.
11826
11827 gc
11828
11829 Specifies the GC.
11830
11831 x
11832
11833 y
11834
11835 Specify the x and y coordinates, which are relative to the
11836 origin of the specified drawable and define the origin of the
11837 first character.
11838
11839 items
11840
11841 Specifies an array of text items.
11842
11843 nitems
11844
11845 Specifies the number of text items in the array.
11846
11847 To draw 2-byte characters in a given drawable, use XDrawText16.
11848
11849 XDrawText16(Display *display, Drawable d, GC gc, int x, int y,
11850 XTextItem16 *items, int nitems);
11851
11852 display
11853
11854 Specifies the connection to the X server.
11855
11856 d
11857
11858 Specifies the drawable.
11859
11860 gc
11861
11862 Specifies the GC.
11863
11864 x
11865
11866 y
11867
11868 Specify the x and y coordinates, which are relative to the
11869 origin of the specified drawable and define the origin of the
11870 first character.
11871
11872 items
11873
11874 Specifies an array of text items.
11875
11876 nitems
11877
11878 Specifies the number of text items in the array.
11879
11880 The XDrawText16 function is similar to XDrawText except that it
11881 uses 2-byte or 16-bit characters. Both functions allow complex
11882 spacing and font shifts between counted strings.
11883
11884 Each text item is processed in turn. A font member other than
11885 None in an item causes the font to be stored in the GC and used
11886 for subsequent text. A text element delta specifies an
11887 additional change in the position along the x axis before the
11888 string is drawn. The delta is always added to the character
11889 origin and is not dependent on any characteristics of the font.
11890 Each character image, as defined by the font in the GC, is
11891 treated as an additional mask for a fill operation on the
11892 drawable. The drawable is modified only where the font
11893 character has a bit set to 1. If a text item generates a
11894 BadFont error, the previous text items may have been drawn.
11895
11896 For fonts defined with linear indexing rather than 2-byte
11897 matrix indexing, each XChar2b structure is interpreted as a
11898 16-bit number with byte1 as the most significant byte.
11899
11900 Both functions use these GC components: function, plane-mask,
11901 fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin,
11902 and clip-mask. They also use these GC mode-dependent
11903 components: foreground, background, tile, stipple,
11904 tile-stipple-x-origin, and tile-stipple-y-origin.
11905
11906 XDrawText and XDrawText16 can generate BadDrawable, BadFont,
11907 BadGC, and BadMatch errors.
11908
11909Drawing Text Characters
11910
11911 To draw 8-bit characters in a given drawable, use XDrawString.
11912
11913 XDrawString(Display *display, Drawable d, GC gc, int x, int y,
11914 char *string, int length);
11915
11916 display
11917
11918 Specifies the connection to the X server.
11919
11920 d
11921
11922 Specifies the drawable.
11923
11924 gc
11925
11926 Specifies the GC.
11927
11928 x
11929
11930 y
11931
11932 Specify the x and y coordinates, which are relative to the
11933 origin of the specified drawable and define the origin of the
11934 first character.
11935
11936 string
11937
11938 Specifies the character string.
11939
11940 length
11941
11942 Specifies the number of characters in the string argument.
11943
11944 To draw 2-byte characters in a given drawable, use
11945 XDrawString16.
11946
11947 XDrawString16(Display *display, Drawable d, GC gc, int x, int
11948 y, XChar2b *string, int length);
11949
11950 display
11951
11952 Specifies the connection to the X server.
11953
11954 d
11955
11956 Specifies the drawable.
11957
11958 gc
11959
11960 Specifies the GC.
11961
11962 x
11963
11964 y
11965
11966 Specify the x and y coordinates, which are relative to the
11967 origin of the specified drawable and define the origin of the
11968 first character.
11969
11970 string
11971
11972 Specifies the character string.
11973
11974 length
11975
11976 Specifies the number of characters in the string argument.
11977
11978 Each character image, as defined by the font in the GC, is
11979 treated as an additional mask for a fill operation on the
11980 drawable. The drawable is modified only where the font
11981 character has a bit set to 1. For fonts defined with 2-byte
11982 matrix indexing and used with XDrawString16, each byte is used
11983 as a byte2 with a byte1 of zero.
11984
11985 Both functions use these GC components: function, plane-mask,
11986 fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin,
11987 and clip-mask. They also use these GC mode-dependent
11988 components: foreground, background, tile, stipple,
11989 tile-stipple-x-origin, and tile-stipple-y-origin.
11990
11991 XDrawString and XDrawString16 can generate BadDrawable, BadGC,
11992 and BadMatch errors.
11993
11994Drawing Image Text Characters
11995
11996 Some applications, in particular terminal emulators, need to
11997 print image text in which both the foreground and background
11998 bits of each character are painted. This prevents annoying
11999 flicker on many displays.
12000
12001 To draw 8-bit image text characters in a given drawable, use
12002 XDrawImageString.
12003
12004 XDrawImageString(Display *display, Drawable d, GC gc, int x,
12005 int y, char *string, int length);
12006
12007 display
12008
12009 Specifies the connection to the X server.
12010
12011 d
12012
12013 Specifies the drawable.
12014
12015 gc
12016
12017 Specifies the GC.
12018
12019 x
12020
12021 y
12022
12023 Specify the x and y coordinates, which are relative to the
12024 origin of the specified drawable and define the origin of the
12025 first character.
12026
12027 string
12028
12029 Specifies the character string.
12030
12031 length
12032
12033 Specifies the number of characters in the string argument.
12034
12035 To draw 2-byte image text characters in a given drawable, use
12036 XDrawImageString16.
12037
12038 XDrawImageString16(Display *display, Drawable d, GC gc, int x,
12039 int y, XChar2b *string, int length);
12040
12041 display
12042
12043 Specifies the connection to the X server.
12044
12045 d
12046
12047 Specifies the drawable.
12048
12049 gc
12050
12051 Specifies the GC.
12052
12053 x
12054
12055 y
12056
12057 Specify the x and y coordinates, which are relative to the
12058 origin of the specified drawable and define the origin of the
12059 first character.
12060
12061 string
12062
12063 Specifies the character string.
12064
12065 length
12066
12067 Specifies the number of characters in the string argument.
12068
12069 The XDrawImageString16 function is similar to XDrawImageString
12070 except that it uses 2-byte or 16-bit characters. Both functions
12071 also use both the foreground and background pixels of the GC in
12072 the destination.
12073
12074 The effect is first to fill a destination rectangle with the
12075 background pixel defined in the GC and then to paint the text
12076 with the foreground pixel. The upper-left corner of the filled
12077 rectangle is at:
12078
12079[x, y - font-ascent]
12080
12081 The width is:
12082
12083overall-width
12084
12085 The height is:
12086
12087font-ascent + font-descent
12088
12089 The overall-width, font-ascent, and font-descent are as would
12090 be returned by XQueryTextExtents using gc and string. The
12091 function and fill-style defined in the GC are ignored for these
12092 functions. The effective function is GXcopy, and the effective
12093 fill-style is FillSolid.
12094
12095 For fonts defined with 2-byte matrix indexing and used with
12096 XDrawImageString, each byte is used as a byte2 with a byte1 of
12097 zero.
12098
12099 Both functions use these GC components: plane-mask, foreground,
12100 background, font, subwindow-mode, clip-x-origin, clip-y-origin,
12101 and clip-mask.
12102
12103 XDrawImageString and XDrawImageString16 can generate
12104 BadDrawable, BadGC, and BadMatch errors.
12105
12106Transferring Images between Client and Server
12107
12108 Xlib provides functions that you can use to transfer images
12109 between a client and the server. Because the server may require
12110 diverse data formats, Xlib provides an image object that fully
12111 describes the data in memory and that provides for basic
12112 operations on that data. You should reference the data through
12113 the image object rather than referencing the data directly.
12114 However, some implementations of the Xlib library may
12115 efficiently deal with frequently used data formats by replacing
12116 functions in the procedure vector with special case functions.
12117 Supported operations include destroying the image, getting a
12118 pixel, storing a pixel, extracting a subimage of an image, and
12119 adding a constant to an image (see section 16.8).
12120
12121 All the image manipulation functions discussed in this section
12122 make use of the XImage structure, which describes an image as
12123 it exists in the client's memory.
12124
12125
12126
12127typedef struct _XImage {
12128 int width, height; /* size of image */
12129 int xoffset; /* number of pixels offset in X directio
12130n */
12131 int format; /* XYBitmap, XYPixmap, ZPixmap */
12132 char *data; /* pointer to image data */
12133 int byte_order; /* data byte order, LSBFirst, MSBFirst *
12134/
12135 int bitmap_unit; /* quant. of scanline 8, 16, 32 */
12136 int bitmap_bit_order; /* LSBFirst, MSBFirst */
12137 int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */
12138 int depth; /* depth of image */
12139 int bytes_per_line; /* accelerator to next scanline */
12140 int bits_per_pixel; /* bits per pixel (ZPixmap) */
12141 unsigned long red_mask; /* bits in z arrangement */
12142 unsigned long green_mask;
12143 unsigned long blue_mask;
12144 XPointer obdata; /* hook for the object routines to hang
12145on */
12146 struct funcs { /* image manipulation routines */
12147 struct _XImage *(*create_image)();
12148 int (*destroy_image)();
12149 unsigned long (*get_pixel)();
12150 int (*put_pixel)();
12151 struct _XImage *(*sub_image)();
12152 int (*add_pixel)();
12153 } f;
12154} XImage;
12155
12156 To initialize the image manipulation routines of an image
12157 structure, use XInitImage.
12158
12159 Status XInitImage(XImage *image);
12160
12161 ximage
12162
12163 Specifies the image.
12164
12165 The XInitImage function initializes the internal image
12166 manipulation routines of an image structure, based on the
12167 values of the various structure members. All fields other than
12168 the manipulation routines must already be initialized. If the
12169 bytes_per_line member is zero, XInitImage will assume the image
12170 data is contiguous in memory and set the bytes_per_line member
12171 to an appropriate value based on the other members; otherwise,
12172 the value of bytes_per_line is not changed. All of the
12173 manipulation routines are initialized to functions that other
12174 Xlib image manipulation functions need to operate on the type
12175 of image specified by the rest of the structure.
12176
12177 This function must be called for any image constructed by the
12178 client before passing it to any other Xlib function. Image
12179 structures created or returned by Xlib do not need to be
12180 initialized in this fashion.
12181
12182 This function returns a nonzero status if initialization of the
12183 structure is successful. It returns zero if it detected some
12184 error or inconsistency in the structure, in which case the
12185 image is not changed.
12186
12187 To combine an image with a rectangle of a drawable on the
12188 display, use XPutImage.
12189
12190 XPutImage(Display *display, Drawable d, GC gc, XImage *image,
12191 int src_x, int src_y, int dest_x, int dest_y, unsigned int
12192 width, unsigned int height);
12193
12194 display
12195
12196 Specifies the connection to the X server.
12197
12198 d
12199
12200 Specifies the drawable.
12201
12202 gc
12203
12204 Specifies the GC.
12205
12206 image
12207
12208 Specifies the image you want combined with the rectangle.
12209
12210 src_x
12211
12212 Specifies the offset in X from the left edge of the image
12213 defined by the XImage structure.
12214
12215 src_y
12216
12217 Specifies the offset in Y from the top edge of the image
12218 defined by the XImage structure.
12219
12220 dest_x
12221
12222 dest_y
12223
12224 Specify the x and y coordinates, which are relative to the
12225 origin of the drawable and are the coordinates of the subimage.
12226
12227 width
12228
12229 height
12230
12231 Specify the width and height of the subimage, which define the
12232 dimensions of the rectangle.
12233
12234 The XPutImage function combines an image with a rectangle of
12235 the specified drawable. The section of the image defined by the
12236 src_x, src_y, width, and height arguments is drawn on the
12237 specified part of the drawable. If XYBitmap format is used, the
12238 depth of the image must be one, or a BadMatch error results.
12239 The foreground pixel in the GC defines the source for the one
12240 bits in the image, and the background pixel defines the source
12241 for the zero bits. For XYPixmap and ZPixmap, the depth of the
12242 image must match the depth of the drawable, or a BadMatch error
12243 results.
12244
12245 If the characteristics of the image (for example, byte_order
12246 and bitmap_unit) differ from what the server requires,
12247 XPutImage automatically makes the appropriate conversions.
12248
12249 This function uses these GC components: function, plane-mask,
12250 subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It
12251 also uses these GC mode-dependent components: foreground and
12252 background.
12253
12254 XPutImage can generate BadDrawable, BadGC, BadMatch, and
12255 BadValue errors.
12256
12257 To return the contents of a rectangle in a given drawable on
12258 the display, use XGetImage. This function specifically supports
12259 rudimentary screen dumps.
12260
12261 XImage *XGetImage(Display *display, Drawable d, int x, int y,
12262 unsigned int width, unsigned int height, unsigned long
12263 plane_mask, int format);
12264
12265 display
12266
12267 Specifies the connection to the X server.
12268
12269 d
12270
12271 Specifies the drawable.
12272
12273 x
12274
12275 y
12276
12277 Specify the x and y coordinates, which are relative to the
12278 origin of the drawable and define the upper-left corner of the
12279 rectangle.
12280
12281 width
12282
12283 height
12284
12285 Specify the width and height of the subimage, which define the
12286 dimensions of the rectangle.
12287
12288 plane_mask
12289
12290 Specifies the plane mask.
12291
12292 format
12293
12294 Specifies the format for the image. You can pass XYPixmap or
12295 ZPixmap.
12296
12297 The XGetImage function returns a pointer to an XImage
12298 structure. This structure provides you with the contents of the
12299 specified rectangle of the drawable in the format you specify.
12300 If the format argument is XYPixmap, the image contains only the
12301 bit planes you passed to the plane_mask argument. If the
12302 plane_mask argument only requests a subset of the planes of the
12303 display, the depth of the returned image will be the number of
12304 planes requested. If the format argument is ZPixmap, XGetImage
12305 returns as zero the bits in all planes not specified in the
12306 plane_mask argument. The function performs no range checking on
12307 the values in plane_mask and ignores extraneous bits.
12308
12309 XGetImage returns the depth of the image to the depth member of
12310 the XImage structure. The depth of the image is as specified
12311 when the drawable was created, except when getting a subset of
12312 the planes in XYPixmap format, when the depth is given by the
12313 number of bits set to 1 in plane_mask.
12314
12315 If the drawable is a pixmap, the given rectangle must be wholly
12316 contained within the pixmap, or a BadMatch error results. If
12317 the drawable is a window, the window must be viewable, and it
12318 must be the case that if there were no inferiors or overlapping
12319 windows, the specified rectangle of the window would be fully
12320 visible on the screen and wholly contained within the outside
12321 edges of the window, or a BadMatch error results. Note that the
12322 borders of the window can be included and read with this
12323 request. If the window has backing-store, the backing-store
12324 contents are returned for regions of the window that are
12325 obscured by noninferior windows. If the window does not have
12326 backing-store, the returned contents of such obscured regions
12327 are undefined. The returned contents of visible regions of
12328 inferiors of a different depth than the specified window's
12329 depth are also undefined. The pointer cursor image is not
12330 included in the returned contents. If a problem occurs,
12331 XGetImage returns NULL.
12332
12333 XGetImage can generate BadDrawable, BadMatch, and BadValue
12334 errors.
12335
12336 To copy the contents of a rectangle on the display to a
12337 location within a preexisting image structure, use
12338 XGetSubImage.
12339
12340 XImage *XGetSubImage(Display *display, Drawable d, int x, int
12341 y, unsigned int width, unsigned int height, unsigned long
12342 plane_mask, int format, XImage *dest_image, int dest_x, int
12343 dest_y);
12344
12345 display
12346
12347 Specifies the connection to the X server.
12348
12349 d
12350
12351 Specifies the drawable.
12352
12353 x
12354
12355 y
12356
12357 Specify the x and y coordinates, which are relative to the
12358 origin of the drawable and define the upper-left corner of the
12359 rectangle.
12360
12361 width
12362
12363 height
12364
12365 Specify the width and height of the subimage, which define the
12366 dimensions of the rectangle.
12367
12368 plane_mask
12369
12370 Specifies the plane mask.
12371
12372 format
12373
12374 Specifies the format for the image. You can pass XYPixmap or
12375 ZPixmap.
12376
12377 dest_image
12378
12379 Specifies the destination image.
12380
12381 dest_x
12382
12383 dest_y
12384
12385 Specify the x and y coordinates, which are relative to the
12386 origin of the destination rectangle, specify its upper-left
12387 corner, and determine where the subimage is placed in the
12388 destination image.
12389
12390 The XGetSubImage function updates dest_image with the specified
12391 subimage in the same manner as XGetImage. If the format
12392 argument is XYPixmap, the image contains only the bit planes
12393 you passed to the plane_mask argument. If the format argument
12394 is ZPixmap, XGetSubImage returns as zero the bits in all planes
12395 not specified in the plane_mask argument. The function performs
12396 no range checking on the values in plane_mask and ignores
12397 extraneous bits. As a convenience, XGetSubImage returns a
12398 pointer to the same XImage structure specified by dest_image.
12399
12400 The depth of the destination XImage structure must be the same
12401 as that of the drawable. If the specified subimage does not fit
12402 at the specified location on the destination image, the right
12403 and bottom edges are clipped. If the drawable is a pixmap, the
12404 given rectangle must be wholly contained within the pixmap, or
12405 a BadMatch error results. If the drawable is a window, the
12406 window must be viewable, and it must be the case that if there
12407 were no inferiors or overlapping windows, the specified
12408 rectangle of the window would be fully visible on the screen
12409 and wholly contained within the outside edges of the window, or
12410 a BadMatch error results. If the window has backing-store, then
12411 the backing-store contents are returned for regions of the
12412 window that are obscured by noninferior windows. If the window
12413 does not have backing-store, the returned contents of such
12414 obscured regions are undefined. The returned contents of
12415 visible regions of inferiors of a different depth than the
12416 specified window's depth are also undefined. If a problem
12417 occurs, XGetSubImage returns NULL.
12418
12419 XGetSubImage can generate BadDrawable, BadGC, BadMatch, and
12420 BadValue errors.
12421
12422Chapter 9. Window and Session Manager Functions
12423
12424 Table of Contents
12425
12426 Changing the Parent of a Window
12427 Controlling the Lifetime of a Window
12428 Managing Installed Colormaps
12429 Setting and Retrieving the Font Search Path
12430 Grabbing the Server
12431 Killing Clients
12432 Controlling the Screen Saver
12433 Controlling Host Access
12434
12435 Adding, Getting, or Removing Hosts
12436 Changing, Enabling, or Disabling Access Control
12437
12438 Although it is difficult to categorize functions as exclusively
12439 for an application, a window manager, or a session manager, the
12440 functions in this chapter are most often used by window
12441 managers and session managers. It is not expected that these
12442 functions will be used by most application programs. Xlib
12443 provides management functions to:
12444 * Change the parent of a window
12445 * Control the lifetime of a window
12446 * Manage installed colormaps
12447 * Set and retrieve the font search path
12448 * Grab the server
12449 * Kill a client
12450 * Control the screen saver
12451 * Control host access
12452
12453Changing the Parent of a Window
12454
12455 To change a window's parent to another window on the same
12456 screen, use XReparentWindow. There is no way to move a window
12457 between screens.
12458
12459 XReparentWindow(Display *display, Window w, Window parent, int
12460 x, int y);
12461
12462 display
12463
12464 Specifies the connection to the X server.
12465
12466 w
12467
12468 Specifies the window.
12469
12470 parent
12471
12472 Specifies the parent window.
12473
12474 x
12475
12476 y
12477
12478 Specify the x and y coordinates of the position in the new
12479 parent window.
12480
12481 If the specified window is mapped, XReparentWindow
12482 automatically performs an UnmapWindow request on it, removes it
12483 from its current position in the hierarchy, and inserts it as
12484 the child of the specified parent. The window is placed in the
12485 stacking order on top with respect to sibling windows.
12486
12487 After reparenting the specified window, XReparentWindow causes
12488 the X server to generate a ReparentNotify event. The
12489 override_redirect member returned in this event is set to the
12490 window's corresponding attribute. Window manager clients
12491 usually should ignore this window if this member is set to
12492 True. Finally, if the specified window was originally mapped,
12493 the X server automatically performs a MapWindow request on it.
12494
12495 The X server performs normal exposure processing on formerly
12496 obscured windows. The X server might not generate Expose events
12497 for regions from the initial UnmapWindow request that are
12498 immediately obscured by the final MapWindow request. A BadMatch
12499 error results if:
12500 * The new parent window is not on the same screen as the old
12501 parent window.
12502 * The new parent window is the specified window or an
12503 inferior of the specified window.
12504 * The new parent is InputOnly, and the window is not.
12505 * The specified window has a ParentRelative background, and
12506 the new parent window is not the same depth as the
12507 specified window.
12508
12509 XReparentWindow can generate BadMatch and BadWindow errors.
12510
12511Controlling the Lifetime of a Window
12512
12513 The save-set of a client is a list of other clients' windows
12514 that, if they are inferiors of one of the client's windows at
12515 connection close, should not be destroyed and should be
12516 remapped if they are unmapped. For further information about
12517 close-connection processing, see section 2.6. To allow an
12518 application's window to survive when a window manager that has
12519 reparented a window fails, Xlib provides the save-set functions
12520 that you can use to control the longevity of subwindows that
12521 are normally destroyed when the parent is destroyed. For
12522 example, a window manager that wants to add decoration to a
12523 window by adding a frame might reparent an application's
12524 window. When the frame is destroyed, the application's window
12525 should not be destroyed but be returned to its previous place
12526 in the window hierarchy.
12527
12528 The X server automatically removes windows from the save-set
12529 when they are destroyed.
12530
12531 To add or remove a window from the client's save-set, use
12532 XChangeSaveSet.
12533
12534 XChangeSaveSet(Display *display, Window w, int change_mode);
12535
12536 display
12537
12538 Specifies the connection to the X server.
12539
12540 w
12541
12542 Specifies the window that you want to add to or delete from the
12543 client's save-set.
12544
12545 change_mode
12546
12547 Specifies the mode. You can pass SetModeInsert or
12548 SetModeDelete.
12549
12550 Depending on the specified mode, XChangeSaveSet either inserts
12551 or deletes the specified window from the client's save-set. The
12552 specified window must have been created by some other client,
12553 or a BadMatch error results.
12554
12555 XChangeSaveSet can generate BadMatch, BadValue, and BadWindow
12556 errors.
12557
12558 To add a window to the client's save-set, use XAddToSaveSet.
12559
12560 XAddToSaveSet(Display *display, Window w);
12561
12562 display
12563
12564 Specifies the connection to the X server.
12565
12566 w
12567
12568 Specifies the window that you want to add to the client's
12569 save-set.
12570
12571 The XAddToSaveSet function adds the specified window to the
12572 client's save-set. The specified window must have been created
12573 by some other client, or a BadMatch error results.
12574
12575 XAddToSaveSet can generate BadMatch and BadWindow errors.
12576
12577 To remove a window from the client's save-set, use
12578 XRemoveFromSaveSet.
12579
12580 XRemoveFromSaveSet(Display *display, Window w);
12581
12582 display
12583
12584 Specifies the connection to the X server.
12585
12586 w
12587
12588 Specifies the window that you want to delete from the client's
12589 save-set.
12590
12591 The XRemoveFromSaveSet function removes the specified window
12592 from the client's save-set. The specified window must have been
12593 created by some other client, or a BadMatch error results.
12594
12595 XRemoveFromSaveSet can generate BadMatch and BadWindow errors.
12596
12597Managing Installed Colormaps
12598
12599 The X server maintains a list of installed colormaps. Windows
12600 using these colormaps are guaranteed to display with correct
12601 colors; windows using other colormaps may or may not display
12602 with correct colors. Xlib provides functions that you can use
12603 to install a colormap, uninstall a colormap, and obtain a list
12604 of installed colormaps.
12605
12606 At any time, there is a subset of the installed maps that is
12607 viewed as an ordered list and is called the required list. The
12608 length of the required list is at most M, where M is the
12609 minimum number of installed colormaps specified for the screen
12610 in the connection setup. The required list is maintained as
12611 follows. When a colormap is specified to XInstallColormap, it
12612 is added to the head of the list; the list is truncated at the
12613 tail, if necessary, to keep its length to at most M. When a
12614 colormap is specified to XUninstallColormap and it is in the
12615 required list, it is removed from the list. A colormap is not
12616 added to the required list when it is implicitly installed by
12617 the X server, and the X server cannot implicitly uninstall a
12618 colormap that is in the required list.
12619
12620 To install a colormap, use XInstallColormap.
12621
12622 XInstallColormap(Display *display, Colormap colormap);
12623
12624 display
12625
12626 Specifies the connection to the X server.
12627
12628 colormap
12629
12630 Specifies the colormap.
12631
12632 The XInstallColormap function installs the specified colormap
12633 for its associated screen. All windows associated with this
12634 colormap immediately display with true colors. You associated
12635 the windows with this colormap when you created them by calling
12636 XCreateWindow, XCreateSimpleWindow, XChangeWindowAttributes, or
12637 XSetWindowColormap.
12638
12639 If the specified colormap is not already an installed colormap,
12640 the X server generates a ColormapNotify event on each window
12641 that has that colormap. In addition, for every other colormap
12642 that is installed as a result of a call to XInstallColormap,
12643 the X server generates a ColormapNotify event on each window
12644 that has that colormap.
12645
12646 XInstallColormap can generate a BadColor error.
12647
12648 To uninstall a colormap, use XUninstallColormap.
12649
12650 XUninstallColormap(Display *display, Colormap colormap);
12651
12652 display
12653
12654 Specifies the connection to the X server.
12655
12656 colormap
12657
12658 Specifies the colormap.
12659
12660 The XUninstallColormap function removes the specified colormap
12661 from the required list for its screen. As a result, the
12662 specified colormap might be uninstalled, and the X server might
12663 implicitly install or uninstall additional colormaps. Which
12664 colormaps get installed or uninstalled is server dependent
12665 except that the required list must remain installed.
12666
12667 If the specified colormap becomes uninstalled, the X server
12668 generates a ColormapNotify event on each window that has that
12669 colormap. In addition, for every other colormap that is
12670 installed or uninstalled as a result of a call to
12671 XUninstallColormap, the X server generates a ColormapNotify
12672 event on each window that has that colormap.
12673
12674 XUninstallColormap can generate a BadColor error.
12675
12676 To obtain a list of the currently installed colormaps for a
12677 given screen, use XListInstalledColormaps.
12678
12679 Colormap *XListInstalledColormaps(Display *display, Window w,
12680 int *num_return);
12681
12682 display
12683
12684 Specifies the connection to the X server.
12685
12686 w
12687
12688 Specifies the window that determines the screen.
12689
12690 num_return
12691
12692 Returns the number of currently installed colormaps.
12693
12694 The XListInstalledColormaps function returns a list of the
12695 currently installed colormaps for the screen of the specified
12696 window. The order of the colormaps in the list is not
12697 significant and is no explicit indication of the required list.
12698 When the allocated list is no longer needed, free it by using
12699 XFree.
12700
12701 XListInstalledColormaps can generate a BadWindow error.
12702
12703Setting and Retrieving the Font Search Path
12704
12705 The set of fonts available from a server depends on a font
12706 search path. Xlib provides functions to set and retrieve the
12707 search path for a server.
12708
12709 To set the font search path, use XSetFontPath.
12710
12711 XSetFontPath(Display *display, char **directories, int ndirs);
12712
12713 display
12714
12715 Specifies the connection to the X server.
12716
12717 directories
12718
12719 Specifies the directory path used to look for a font. Setting
12720 the path to the empty list restores the default path defined
12721 for the X server.
12722
12723 ndirs
12724
12725 Specifies the number of directories in the path.
12726
12727 The XSetFontPath function defines the directory search path for
12728 font lookup. There is only one search path per X server, not
12729 one per client. The encoding and interpretation of the strings
12730 are implementation-dependent, but typically they specify
12731 directories or font servers to be searched in the order listed.
12732 An X server is permitted to cache font information internally;
12733 for example, it might cache an entire font from a file and not
12734 check on subsequent opens of that font to see if the underlying
12735 font file has changed. However, when the font path is changed,
12736 the X server is guaranteed to flush all cached information
12737 about fonts for which there currently are no explicit resource
12738 IDs allocated. The meaning of an error from this request is
12739 implementation-dependent.
12740
12741 XSetFontPath can generate a BadValue error.
12742
12743 To get the current font search path, use XGetFontPath.
12744
12745 char **XGetFontPath(Display *display, int *npaths_return);
12746
12747 display
12748
12749 Specifies the connection to the X server.
12750
12751 npaths_return
12752
12753 Returns the number of strings in the font path array.
12754
12755 The XGetFontPath function allocates and returns an array of
12756 strings containing the search path. The contents of these
12757 strings are implementation-dependent and are not intended to be
12758 interpreted by client applications. When it is no longer
12759 needed, the data in the font path should be freed by using
12760 XFreeFontPath.
12761
12762 To free data returned by XGetFontPath, use XFreeFontPath.
12763
12764 XFreeFontPath(char **list);
12765
12766 list
12767
12768 Specifies the array of strings you want to free.
12769
12770 The XFreeFontPath function frees the data allocated by
12771 XGetFontPath.
12772
12773Grabbing the Server
12774
12775 Xlib provides functions that you can use to grab and ungrab the
12776 server. These functions can be used to control processing of
12777 output on other connections by the window system server. While
12778 the server is grabbed, no processing of requests or close downs
12779 on any other connection will occur. A client closing its
12780 connection automatically ungrabs the server. Although grabbing
12781 the server is highly discouraged, it is sometimes necessary.
12782
12783 To grab the server, use XGrabServer.
12784
12785 XGrabServer(Display *display);
12786
12787 display
12788
12789 Specifies the connection to the X server.
12790
12791 The XGrabServer function disables processing of requests and
12792 close downs on all other connections than the one this request
12793 arrived on. You should not grab the X server any more than is
12794 absolutely necessary.
12795
12796 To ungrab the server, use XUngrabServer.
12797
12798 XUngrabServer(Display *display);
12799
12800 display
12801
12802 Specifies the connection to the X server.
12803
12804 The XUngrabServer function restarts processing of requests and
12805 close downs on other connections. You should avoid grabbing the
12806 X server as much as possible.
12807
12808Killing Clients
12809
12810 Xlib provides a function to cause the connection to a client to
12811 be closed and its resources to be destroyed. To destroy a
12812 client, use XKillClient.
12813
12814 XKillClient(Display *display, XID resource);
12815
12816 display
12817
12818 Specifies the connection to the X server.
12819
12820 resource
12821
12822 Specifies any resource associated with the client that you want
12823 to destroy or AllTemporary.
12824
12825 The XKillClient function forces a close down of the client that
12826 created the resource if a valid resource is specified. If the
12827 client has already terminated in either RetainPermanent or
12828 RetainTemporary mode, all of the client's resources are
12829 destroyed. If AllTemporary is specified, the resources of all
12830 clients that have terminated in RetainTemporary are destroyed
12831 (see section 2.5). This permits implementation of window
12832 manager facilities that aid debugging. A client can set its
12833 close-down mode to RetainTemporary. If the client then crashes,
12834 its windows would not be destroyed. The programmer can then
12835 inspect the application's window tree and use the window
12836 manager to destroy the zombie windows.
12837
12838 XKillClient can generate a BadValue error.
12839
12840Controlling the Screen Saver
12841
12842 Xlib provides functions that you can use to set or reset the
12843 mode of the screen saver, to force or activate the screen
12844 saver, or to obtain the current screen saver values.
12845
12846 To set the screen saver mode, use XSetScreenSaver.
12847
12848 XSetScreenSaver(Display *display, int timeout, int interval,
12849 int prefer_blanking, int allow_exposures);
12850
12851 display
12852
12853 Specifies the connection to the X server.
12854
12855 timeout
12856
12857 Specifies the timeout, in seconds, until the screen saver turns
12858 on.
12859
12860 interval
12861
12862 Specifies the interval, in seconds, between screen saver
12863 alterations.
12864
12865 prefer_blanking
12866
12867 Specifies how to enable screen blanking. You can pass
12868 DontPreferBlanking, PreferBlanking, or DefaultBlanking.
12869
12870 allow_exposures
12871
12872 Specifies the screen save control values. You can pass
12873 DontAllowExposures, AllowExposures, or DefaultExposures.
12874
12875 Timeout and interval are specified in seconds. A timeout of 0
12876 disables the screen saver (but an activated screen saver is not
12877 deactivated), and a timeout of -1 restores the default. Other
12878 negative values generate a BadValue error. If the timeout value
12879 is nonzero, XSetScreenSaver enables the screen saver. An
12880 interval of 0 disables the random-pattern motion. If no input
12881 from devices (keyboard, mouse, and so on) is generated for the
12882 specified number of timeout seconds once the screen saver is
12883 enabled, the screen saver is activated.
12884
12885 For each screen, if blanking is preferred and the hardware
12886 supports video blanking, the screen simply goes blank.
12887 Otherwise, if either exposures are allowed or the screen can be
12888 regenerated without sending Expose events to clients, the
12889 screen is tiled with the root window background tile randomly
12890 re-origined each interval seconds. Otherwise, the screens'
12891 state do not change, and the screen saver is not activated. The
12892 screen saver is deactivated, and all screen states are restored
12893 at the next keyboard or pointer input or at the next call to
12894 XForceScreenSaver with mode ScreenSaverReset.
12895
12896 If the server-dependent screen saver method supports periodic
12897 change, the interval argument serves as a hint about how long
12898 the change period should be, and zero hints that no periodic
12899 change should be made. Examples of ways to change the screen
12900 include scrambling the colormap periodically, moving an icon
12901 image around the screen periodically, or tiling the screen with
12902 the root window background tile, randomly re-origined
12903 periodically.
12904
12905 XSetScreenSaver can generate a BadValue error.
12906
12907 To force the screen saver on or off, use XForceScreenSaver.
12908
12909 XForceScreenSaver(Display *display, int mode);
12910
12911 display
12912
12913 Specifies the connection to the X server.
12914
12915 mode
12916
12917 Specifies the mode that is to be applied. You can pass
12918 ScreenSaverActive or ScreenSaverReset.
12919
12920 If the specified mode is ScreenSaverActive and the screen saver
12921 currently is deactivated, XForceScreenSaver activates the
12922 screen saver even if the screen saver had been disabled with a
12923 timeout of zero. If the specified mode is ScreenSaverReset and
12924 the screen saver currently is enabled, XForceScreenSaver
12925 deactivates the screen saver if it was activated, and the
12926 activation timer is reset to its initial state (as if device
12927 input had been received).
12928
12929 XForceScreenSaver can generate a BadValue error.
12930
12931 To activate the screen saver, use XActivateScreenSaver.
12932
12933 XActivateScreenSaver(Display *display);
12934
12935 display
12936
12937 Specifies the connection to the X server.
12938
12939 To reset the screen saver, use XResetScreenSaver.
12940
12941 XResetScreenSaver(Display *display);
12942
12943 display
12944
12945 Specifies the connection to the X server.
12946
12947 To get the current screen saver values, use XGetScreenSaver.
12948
12949 XGetScreenSaver(Display *display, int *timeout_return, int
12950 *interval_return, int *prefer_blanking_return, int
12951 *allow_exposures_return);
12952
12953 display
12954
12955 Specifies the connection to the X server.
12956
12957 timeout_return
12958
12959 Returns the timeout, in seconds, until the screen saver turns
12960 on.
12961
12962 interval_return
12963
12964 Returns the interval between screen saver invocations.
12965
12966 prefer_blanking_return
12967
12968 Returns the current screen blanking preference
12969 (DontPreferBlanking, PreferBlanking, or DefaultBlanking).
12970
12971 allow_exposures_return
12972
12973 Returns the current screen save control value
12974 (DontAllowExposures, AllowExposures, or DefaultExposures).
12975
12976Controlling Host Access
12977
12978 This section discusses how to:
12979 * Add, get, or remove hosts from the access control list
12980 * Change, enable, or disable access
12981
12982 X does not provide any protection on a per-window basis. If you
12983 find out the resource ID of a resource, you can manipulate it.
12984 To provide some minimal level of protection, however,
12985 connections are permitted only from machines you trust. This is
12986 adequate on single-user workstations but obviously breaks down
12987 on timesharing machines. Although provisions exist in the X
12988 protocol for proper connection authentication, the lack of a
12989 standard authentication server leaves host-level access control
12990 as the only common mechanism.
12991
12992 The initial set of hosts allowed to open connections typically
12993 consists of:
12994 * The host the window system is running on.
12995 * On POSIX-conformant systems, each host listed in the
12996 /etc/X?.hosts file. The ? indicates the number of the
12997 display. This file should consist of host names separated
12998 by newlines. DECnet nodes must terminate in :: to
12999 distinguish them from Internet hosts.
13000
13001 If a host is not in the access control list when the access
13002 control mechanism is enabled and if the host attempts to
13003 establish a connection, the server refuses the connection. To
13004 change the access list, the client must reside on the same host
13005 as the server and/or must have been granted permission in the
13006 initial authorization at connection setup.
13007
13008 Servers also can implement other access control policies in
13009 addition to or in place of this host access facility. For
13010 further information about other access control implementations,
13011 see X Window System Protocol.
13012
13013Adding, Getting, or Removing Hosts
13014
13015 Xlib provides functions that you can use to add, get, or remove
13016 hosts from the access control list. All the host access control
13017 functions use the XHostAddress structure, which contains:
13018
13019
13020
13021typedef struct {
13022 int family; /* for example FamilyInternet */
13023 int length; /* length of address, in bytes */
13024 char *address; /* pointer to where to find the address */
13025} XHostAddress;
13026
13027 The family member specifies which protocol address family to
13028 use (for example, TCP/IP or DECnet) and can be FamilyInternet,
13029 FamilyInternet6, FamilyServerInterpreted, FamilyDECnet, or
13030 FamilyChaos. The length member specifies the length of the
13031 address in bytes. The address member specifies a pointer to the
13032 address.
13033
13034 For TCP/IP, the address should be in network byte order. For IP
13035 version 4 addresses, the family should be FamilyInternet and
13036 the length should be 4 bytes. For IP version 6 addresses, the
13037 family should be FamilyInternet6 and the length should be 16
13038 bytes.
13039
13040 For the DECnet family, the server performs no automatic
13041 swapping on the address bytes. A Phase IV address is 2 bytes
13042 long. The first byte contains the least significant 8 bits of
13043 the node number. The second byte contains the most significant
13044 2 bits of the node number in the least significant 2 bits of
13045 the byte and the area in the most significant 6 bits of the
13046 byte.
13047
13048 For the ServerInterpreted family, the length is ignored and the
13049 address member is a pointer to a XServerInterpretedAddress
13050 structure, which contains:
13051
13052
13053
13054typedef struct {
13055 int typelength; /* length of type string, in bytes */
13056 int valuelength; /* length of value string, in bytes */
13057 char *type; /* pointer to where to find the type string */
13058 char *value; /* pointer to where to find the address */
13059} XServerInterpretedAddress;
13060
13061 The type and value members point to strings representing the
13062 type and value of the server interpreted entry. These strings
13063 may not be NULL-terminated so care should be used when
13064 accessing them. The typelength and valuelength members specify
13065 the length in byte of the type and value strings.
13066
13067 To add a single host, use XAddHost.
13068
13069 XAddHost(Display *display, XHostAddress *host);
13070
13071 display
13072
13073 Specifies the connection to the X server.
13074
13075 host
13076
13077 Specifies the host that is to be added.
13078
13079 The XAddHost function adds the specified host to the access
13080 control list for that display. The server must be on the same
13081 host as the client issuing the command, or a BadAccess error
13082 results.
13083
13084 XAddHost can generate BadAccess and BadValue errors.
13085
13086 To add multiple hosts at one time, use XAddHosts.
13087
13088 XAddHosts(Display *display, XHostAddress *hosts, int
13089 num_hosts);
13090
13091 display
13092
13093 Specifies the connection to the X server.
13094
13095 hosts
13096
13097 Specifies each host that is to be added.
13098
13099 num_hosts
13100
13101 Specifies the number of hosts.
13102
13103 The XAddHosts function adds each specified host to the access
13104 control list for that display. The server must be on the same
13105 host as the client issuing the command, or a BadAccess error
13106 results.
13107
13108 XAddHosts can generate BadAccess and BadValue errors.
13109
13110 To obtain a host list, use XListHosts.
13111
13112 XHostAddress *XListHosts(Display *display, int *nhosts_return,
13113 Bool *state_return);
13114
13115 display
13116
13117 Specifies the connection to the X server.
13118
13119 nhosts_return
13120
13121 Returns the number of hosts currently in the access control
13122 list.
13123
13124 state_return
13125
13126 Returns the state of the access control.
13127
13128 The XListHosts function returns the current access control list
13129 as well as whether the use of the list at connection setup was
13130 enabled or disabled. XListHosts allows a program to find out
13131 what machines can make connections. It also returns a pointer
13132 to a list of host structures that were allocated by the
13133 function. When no longer needed, this memory should be freed by
13134 calling XFree.
13135
13136 To remove a single host, use XRemoveHost.
13137
13138 XRemoveHost(Display *display, XHostAddress *host);
13139
13140 display
13141
13142 Specifies the connection to the X server.
13143
13144 host
13145
13146 Specifies the host that is to be removed.
13147
13148 The XRemoveHost function removes the specified host from the
13149 access control list for that display. The server must be on the
13150 same host as the client process, or a BadAccess error results.
13151 If you remove your machine from the access list, you can no
13152 longer connect to that server, and this operation cannot be
13153 reversed unless you reset the server.
13154
13155 XRemoveHost can generate BadAccess and BadValue errors.
13156
13157 To remove multiple hosts at one time, use XRemoveHosts.
13158
13159 XRemoveHosts(Display *display, XHostAddress *hosts, int
13160 num_hosts);
13161
13162 display
13163
13164 Specifies the connection to the X server.
13165
13166 hosts
13167
13168 Specifies each host that is to be removed.
13169
13170 num_hosts
13171
13172 Specifies the number of hosts.
13173
13174 The XRemoveHosts function removes each specified host from the
13175 access control list for that display. The X server must be on
13176 the same host as the client process, or a BadAccess error
13177 results. If you remove your machine from the access list, you
13178 can no longer connect to that server, and this operation cannot
13179 be reversed unless you reset the server.
13180
13181 XRemoveHosts can generate BadAccess and BadValue errors.
13182
13183Changing, Enabling, or Disabling Access Control
13184
13185 Xlib provides functions that you can use to enable, disable, or
13186 change access control.
13187
13188 For these functions to execute successfully, the client
13189 application must reside on the same host as the X server and/or
13190 have been given permission in the initial authorization at
13191 connection setup.
13192
13193 To change access control, use XSetAccessControl.
13194
13195 XSetAccessControl(Display *display, int mode);
13196
13197 display
13198
13199 Specifies the connection to the X server.
13200
13201 mode
13202
13203 Specifies the mode. You can pass EnableAccess or DisableAccess.
13204
13205 The XSetAccessControl function either enables or disables the
13206 use of the access control list at each connection setup.
13207
13208 XSetAccessControl can generate BadAccess and BadValue errors.
13209
13210 To enable access control, use XEnableAccessControl.
13211
13212 XEnableAccessControl(Display *display);
13213
13214 display
13215
13216 Specifies the connection to the X server.
13217
13218 The XEnableAccessControl function enables the use of the access
13219 control list at each connection setup.
13220
13221 XEnableAccessControl can generate a BadAccess error.
13222
13223 To disable access control, use XDisableAccessControl.
13224
13225 XDisableAccessControl(Display *display);
13226
13227 display
13228
13229 Specifies the connection to the X server.
13230
13231 The XDisableAccessControl function disables the use of the
13232 access control list at each connection setup.
13233
13234 XDisableAccessControl can generate a BadAccess error.
13235
13236Chapter 10. Events
13237
13238 Table of Contents
13239
13240 Event Types
13241 Event Structures
13242 Event Masks
13243 Event Processing Overview
13244 Keyboard and Pointer Events
13245
13246 Pointer Button Events
13247 Keyboard and Pointer Events
13248
13249 Window Entry/Exit Events
13250
13251 Normal Entry/Exit Events
13252 Grab and Ungrab Entry/Exit Events
13253
13254 Input Focus Events
13255
13256 Normal Focus Events and Focus Events While Grabbed
13257 Focus Events Generated by Grabs
13258
13259 Key Map State Notification Events
13260 Exposure Events
13261
13262 Expose Events
13263 GraphicsExpose and NoExpose Events
13264
13265 Window State Change Events
13266
13267 CirculateNotify Events
13268 ConfigureNotify Events
13269 CreateNotify Events
13270 DestroyNotify Events
13271 GravityNotify Events
13272 MapNotify Events
13273 MappingNotify Events
13274 ReparentNotify Events
13275 UnmapNotify Events
13276 VisibilityNotify Events
13277
13278 Structure Control Events
13279
13280 CirculateRequest Events
13281 ConfigureRequest Events
13282 MapRequest Events
13283 ResizeRequest Events
13284
13285 Colormap State Change Events
13286 Client Communication Events
13287
13288 ClientMessage Events
13289 PropertyNotify Events
13290 SelectionClear Events
13291 SelectionRequest Events
13292 SelectionNotify Events
13293
13294 A client application communicates with the X server through the
13295 connection you establish with the XOpenDisplay function. A
13296 client application sends requests to the X server over this
13297 connection. These requests are made by the Xlib functions that
13298 are called in the client application. Many Xlib functions cause
13299 the X server to generate events, and the user's typing or
13300 moving the pointer can generate events asynchronously. The X
13301 server returns events to the client on the same connection.
13302
13303 This chapter discusses the following topics associated with
13304 events:
13305 * Event types
13306 * Event structures
13307 * Event masks
13308 * Event processing
13309
13310 Functions for handling events are dealt with in the next
13311 chapter.
13312
13313Event Types
13314
13315 An event is data generated asynchronously by the X server as a
13316 result of some device activity or as side effects of a request
13317 sent by an Xlib function. Device-related events propagate from
13318 the source window to ancestor windows until some client
13319 application has selected that event type or until the event is
13320 explicitly discarded. The X server generally sends an event to
13321 a client application only if the client has specifically asked
13322 to be informed of that event type, typically by setting the
13323 event-mask attribute of the window. The mask can also be set
13324 when you create a window or by changing the window's
13325 event-mask. You can also mask out events that would propagate
13326 to ancestor windows by manipulating the do-not-propagate mask
13327 of the window's attributes. However, MappingNotify events are
13328 always sent to all clients.
13329
13330 An event type describes a specific event generated by the X
13331 server. For each event type, a corresponding constant name is
13332 defined in <X11/X.h>, which is used when referring to an event
13333 type. The following table lists the event category and its
13334 associated event type or types. The processing associated with
13335 these events is discussed in section 10.5.
13336
13337 Event Category Event Type
13338 Keyboard events KeyPress, KeyRelease
13339 Pointer events ButtonPress, ButtonRelease, MotionNotify
13340 Window crossing events EnterNotify, LeaveNotify
13341 Input focus events FocusIn, FocusOut
13342 Keymap state notification event KeymapNotify
13343 Exposure events Expose, GraphicsExpose, NoExpose
13344 Structure control events CirculateRequest, ConfigureRequest,
13345 MapRequest, ResizeRequest
13346 Window state notification events CirculateNotify,
13347 ConfigureNotify, CreateNotify, DestroyNotify, GravityNotify,
13348 MapNotify, MappingNotify, ReparentNotify, UnmapNotify,
13349 VisibilityNotify
13350 Colormap state notification event ColormapNotify
13351 Client communication events ClientMessage, PropertyNotify,
13352 SelectionClear, SelectionNotify, SelectionRequest
13353
13354Event Structures
13355
13356 For each event type, a corresponding structure is declared in
13357 <X11/Xlib.h>. All the event structures have the following
13358 common members:
13359
13360
13361
13362typedef struct {
13363 int type;
13364 unsigned long serial; /* # of last request processed by server
13365*/
13366 Bool send_event; /* true if this came from a SendEvent req
13367uest */
13368 Display *display; /* Display the event was read from */
13369 Window window;
13370} XAnyEvent;
13371
13372 The type member is set to the event type constant name that
13373 uniquely identifies it. For example, when the X server reports
13374 a GraphicsExpose event to a client application, it sends an
13375 XGraphicsExposeEvent structure with the type member set to
13376 GraphicsExpose. The display member is set to a pointer to the
13377 display the event was read on. The send_event member is set to
13378 True if the event came from a SendEvent protocol request. The
13379 serial member is set from the serial number reported in the
13380 protocol but expanded from the 16-bit least-significant bits to
13381 a full 32-bit value. The window member is set to the window
13382 that is most useful to toolkit dispatchers.
13383
13384 The X server can send events at any time in the input stream.
13385 Xlib stores any events received while waiting for a reply in an
13386 event queue for later use. Xlib also provides functions that
13387 allow you to check events in the event queue (see section
13388 11.3).
13389
13390 In addition to the individual structures declared for each
13391 event type, the XEvent structure is a union of the individual
13392 structures declared for each event type. Depending on the type,
13393 you should access members of each event by using the XEvent
13394 union.
13395
13396
13397
13398typedef union _XEvent {
13399 int type; /* must not be change
13400d */
13401 XAnyEvent xany;
13402 XKeyEvent xkey;
13403 XButtonEvent xbutton;
13404 XMotionEvent xmotion;
13405 XCrossingEvent xcrossing;
13406 XFocusChangeEvent xfocus;
13407 XExposeEvent xexpose;
13408 XGraphicsExposeEvent xgraphicsexpose;
13409 XNoExposeEvent xnoexpose;
13410 XVisibilityEvent xvisibility;
13411 XCreateWindowEvent xcreatewindow;
13412 XDestroyWindowEvent xdestroywindow;
13413 XUnmapEvent xunmap;
13414 XMapEvent xmap;
13415 XMapRequestEvent xmaprequest;
13416 XReparentEvent xreparent;
13417 XConfigureEvent xconfigure;
13418 XGravityEvent xgravity;
13419 XResizeRequestEvent xresizerequest;
13420 XConfigureRequestEvent xconfigurerequest;
13421 XCirculateEvent xcirculate;
13422 XCirculateRequestEvent xcirculaterequest;
13423 XPropertyEvent xproperty;
13424 XSelectionClearEvent xselectionclear;
13425 XSelectionRequestEvent xselectionrequest;
13426 XSelectionEvent xselection;
13427 XColormapEvent xcolormap;
13428 XClientMessageEvent xclient;
13429 XMappingEvent xmapping;
13430 XErrorEvent xerror;
13431 XKeymapEvent xkeymap;
13432 long pad[24];
13433} XEvent;
13434
13435 An XEvent structure's first entry always is the type member,
13436 which is set to the event type. The second member always is the
13437 serial number of the protocol request that generated the event.
13438 The third member always is send_event, which is a Bool that
13439 indicates if the event was sent by a different client. The
13440 fourth member always is a display, which is the display that
13441 the event was read from. Except for keymap events, the fifth
13442 member always is a window, which has been carefully selected to
13443 be useful to toolkit dispatchers. To avoid breaking toolkits,
13444 the order of these first five entries is not to change. Most
13445 events also contain a time member, which is the time at which
13446 an event occurred. In addition, a pointer to the generic event
13447 must be cast before it is used to access any other information
13448 in the structure.
13449
13450Event Masks
13451
13452 Clients select event reporting of most events relative to a
13453 window. To do this, pass an event mask to an Xlib
13454 event-handling function that takes an event_mask argument. The
13455 bits of the event mask are defined in <X11/X.h>. Each bit in
13456 the event mask maps to an event mask name, which describes the
13457 event or events you want the X server to return to a client
13458 application.
13459
13460 Unless the client has specifically asked for them, most events
13461 are not reported to clients when they are generated. Unless the
13462 client suppresses them by setting graphics-exposures in the GC
13463 to False, GraphicsExpose and NoExpose are reported by default
13464 as a result of XCopyPlane and XCopyArea. SelectionClear,
13465 SelectionRequest, SelectionNotify, or ClientMessage cannot be
13466 masked. Selection-related events are only sent to clients
13467 cooperating with selections (see section 4.5). When the
13468 keyboard or pointer mapping is changed, MappingNotify is always
13469 sent to clients.
13470
13471 The following table lists the event mask constants you can pass
13472 to the event_mask argument and the circumstances in which you
13473 would want to specify the event mask:
13474 Event Mask Circumstances
13475 NoEventMask No events wanted
13476 KeyPressMask Keyboard down events wanted
13477 KeyReleaseMask Keyboard up events wanted
13478 ButtonPressMask Pointer button down events wanted
13479 ButtonReleaseMask Pointer button up events wanted
13480 EnterWindowMask Pointer window entry events wanted
13481 LeaveWindowMask Pointer window leave events wanted
13482 PointerMotionMask Pointer motion events wanted
13483 PointerMotionHintMask Pointer motion hints wanted
13484 Button1MotionMask Pointer motion while button 1 down
13485 Button2MotionMask Pointer motion while button 2 down
13486 Button3MotionMask Pointer motion while button 3 down
13487 Button4MotionMask Pointer motion while button 4 down
13488 Button5MotionMask Pointer motion while button 5 down
13489 ButtonMotionMask Pointer motion while any button down
13490 KeymapStateMask Keyboard state wanted at window entry and focus
13491 in
13492 ExposureMask Any exposure wanted
13493 VisibilityChangeMask Any change in visibility wanted
13494 StructureNotifyMask Any change in window structure wanted
13495 ResizeRedirectMask Redirect resize of this window
13496 SubstructureNotifyMask Substructure notification wanted
13497 SubstructureRedirectMask Redirect structure requests on
13498 children
13499 FocusChangeMask Any change in input focus wanted
13500 PropertyChangeMask Any change in property wanted
13501 ColormapChangeMask Any change in colormap wanted
13502 OwnerGrabButtonMask Automatic grabs should activate with
13503 owner_events set to True
13504
13505Event Processing Overview
13506
13507 The event reported to a client application during event
13508 processing depends on which event masks you provide as the
13509 event-mask attribute for a window. For some event masks, there
13510 is a one-to-one correspondence between the event mask constant
13511 and the event type constant. For example, if you pass the event
13512 mask ButtonPressMask, the X server sends back only ButtonPress
13513 events. Most events contain a time member, which is the time at
13514 which an event occurred.
13515
13516 In other cases, one event mask constant can map to several
13517 event type constants. For example, if you pass the event mask
13518 SubstructureNotifyMask, the X server can send back
13519 CirculateNotify, ConfigureNotify, CreateNotify, DestroyNotify,
13520 GravityNotify, MapNotify, ReparentNotify, or UnmapNotify
13521 events.
13522
13523 In another case, two event masks can map to one event type. For
13524 example, if you pass either PointerMotionMask or
13525 ButtonMotionMask, the X server sends back a MotionNotify event.
13526
13527 The following table lists the event mask, its associated event
13528 type or types, and the structure name associated with the event
13529 type. Some of these structures actually are typedefs to a
13530 generic structure that is shared between two event types. Note
13531 that N.A. appears in columns for which the information is not
13532 applicable.
13533 Event Mask Event Type Structure Generic Structure
13534
13535 ButtonMotionMask
13536
13537 Button1MotionMask
13538
13539 Button2MotionMask
13540
13541 Button3MotionMask
13542
13543 Button4MotionMask
13544
13545 Button5MotionMask
13546 MotionNotify XPointerMovedEvent XMotionEvent
13547 ButtonPressMask ButtonPress XButtonPressedEvent XButtonEvent
13548 ButtonReleaseMask ButtonRelease XButtonReleasedEvent
13549 XButtonEvent
13550 ColormapChangeMask ColormapNotify XColormapEvent
13551 EnterWindowMask EnterNotify XEnterWindowEvent XCrossingEvent
13552 LeaveWindowMask LeaveNotify XLeaveWindowEvent XCrossingEvent
13553 ExposureMask Expose XExposeEvent
13554 GCGraphicsExposures in GC GraphicsExpose XGraphicsExposeEvent
13555 NoExpose XNoExposeEvent
13556 FocusChangeMask FocusIn XFocusInEvent XFocusChangeEvent
13557 FocusOut XFocusOutEvent XFocusChangeEvent
13558 KeymapStateMask KeymapNotify XKeymapEvent
13559 KeyPressMask KeyPress XKeyPressedEvent XKeyEvent
13560 KeyReleaseMask KeyRelease XKeyReleasedEvent XKeyEvent
13561 OwnerGrabButtonMask N.A. N.A.
13562 PointerMotionMask MotionNotify XPointerMovedEvent XMotionEvent
13563 PointerMotionHintMask N.A. N.A.
13564 PropertyChangeMask PropertyNotify XPropertyEvent
13565 ResizeRedirectMask ResizeRequest XResizeRequestEvent
13566 StructureNotifyMask CirculateNotify XCirculateEvent
13567 ConfigureNotify XConfigureEvent
13568 DestroyNotify XDestroyWindowEvent
13569 GravityNotify XGravityEvent
13570 MapNotify XMapEvent
13571 ReparentNotify XReparentEvent
13572 UnmapNotify XUnmapEvent
13573 SubstructureNotifyMask CirculateNotify XCirculateEvent
13574 ConfigureNotify XConfigureEvent
13575 CreateNotify XCreateWindowEvent
13576 DestroyNotify XDestroyWindowEvent
13577 GravityNotify XGravityEvent
13578 MapNotify XMapEvent
13579 ReparentNotify XReparentEvent
13580 UnmapNotify XUnmapEvent
13581 SubstructureRedirectMask CirculateRequest
13582 XCirculateRequestEvent
13583 ConfigureRequest XConfigureRequestEvent
13584 MapRequest XMapRequestEvent
13585 N.A. ClientMessage XClientMessageEvent
13586 N.A. MappingNotify XMappingEvent
13587 N.A. SelectionClear XSelectionClearEvent
13588 N.A. SelectionNotify XSelectionEvent
13589 N.A. SelectionRequest XSelectionRequestEvent
13590 VisibilityChangeMask VisibilityNotify XVisibilityEvent
13591
13592 The sections that follow describe the processing that occurs
13593 when you select the different event masks. The sections are
13594 organized according to these processing categories:
13595 * Keyboard and pointer events
13596 * Window crossing events
13597 * Input focus events
13598 * Keymap state notification events
13599 * Exposure events
13600 * Window state notification events
13601 * Structure control events
13602 * Colormap state notification events
13603 * Client communication events
13604
13605Keyboard and Pointer Events
13606
13607 This section discusses:
13608 * Pointer button events
13609 * Keyboard and pointer events
13610
13611Pointer Button Events
13612
13613 The following describes the event processing that occurs when a
13614 pointer button press is processed with the pointer in some
13615 window w and when no active pointer grab is in progress.
13616
13617 The X server searches the ancestors of w from the root down,
13618 looking for a passive grab to activate. If no matching passive
13619 grab on the button exists, the X server automatically starts an
13620 active grab for the client receiving the event and sets the
13621 last-pointer-grab time to the current server time. The effect
13622 is essentially equivalent to an XGrabButton with these client
13623 passed arguments:
13624 Argument Value
13625 w The event window
13626 event_mask The client's selected pointer events on the event
13627 window
13628 pointer_mode GrabModeAsync
13629 keyboard_mode GrabModeAsync
13630 owner_events True, if the client has selected
13631 OwnerGrabButtonMask on the event window, otherwise False
13632 confine_to None
13633 cursor None
13634
13635 The active grab is automatically terminated when the logical
13636 state of the pointer has all buttons released. Clients can
13637 modify the active grab by calling XUngrabPointer and
13638 XChangeActivePointerGrab.
13639
13640Keyboard and Pointer Events
13641
13642 This section discusses the processing that occurs for the
13643 keyboard events KeyPress and KeyRelease and the pointer events
13644 ButtonPress, ButtonRelease, and MotionNotify. For information
13645 about the keyboard event-handling utilities, see chapter 11.
13646
13647 The X server reports KeyPress or KeyRelease events to clients
13648 wanting information about keys that logically change state.
13649 Note that these events are generated for all keys, even those
13650 mapped to modifier bits. The X server reports ButtonPress or
13651 ButtonRelease events to clients wanting information about
13652 buttons that logically change state.
13653
13654 The X server reports MotionNotify events to clients wanting
13655 information about when the pointer logically moves. The X
13656 server generates this event whenever the pointer is moved and
13657 the pointer motion begins and ends in the window. The
13658 granularity of MotionNotify events is not guaranteed, but a
13659 client that selects this event type is guaranteed to receive at
13660 least one event when the pointer moves and then rests.
13661
13662 The generation of the logical changes lags the physical changes
13663 if device event processing is frozen.
13664
13665 To receive KeyPress, KeyRelease, ButtonPress, and ButtonRelease
13666 events, set KeyPressMask, KeyReleaseMask, ButtonPressMask, and
13667 ButtonReleaseMask bits in the event-mask attribute of the
13668 window.
13669
13670 To receive MotionNotify events, set one or more of the
13671 following event masks bits in the event-mask attribute of the
13672 window.
13673 * Button1MotionMask - Button5MotionMask
13674 * The client application receives MotionNotify events only
13675 when one or more of the specified buttons is pressed.
13676 * ButtonMotionMask
13677 * The client application receives MotionNotify events only
13678 when at least one button is pressed.
13679 * PointerMotionMask
13680 * The client application receives MotionNotify events
13681 independent of the state of the pointer buttons.
13682 * PointerMotionHintMask
13683 * If PointerMotionHintMask is selected in combination with
13684 one or more of the above masks, the X server is free to
13685 send only one MotionNotify event (with the is_hint member
13686 of the XPointerMovedEvent structure set to NotifyHint) to
13687 the client for the event window, until either the key or
13688 button state changes, the pointer leaves the event window,
13689 or the client calls XQueryPointer or . The server still may
13690 send MotionNotify events without is_hint set to NotifyHint.
13691
13692 The source of the event is the viewable window that the pointer
13693 is in. The window used by the X server to report these events
13694 depends on the window's position in the window hierarchy and
13695 whether any intervening window prohibits the generation of
13696 these events. Starting with the source window, the X server
13697 searches up the window hierarchy until it locates the first
13698 window specified by a client as having an interest in these
13699 events. If one of the intervening windows has its
13700 do-not-propagate-mask set to prohibit generation of the event
13701 type, the events of those types will be suppressed. Clients can
13702 modify the actual window used for reporting by performing
13703 active grabs and, in the case of keyboard events, by using the
13704 focus window.
13705
13706 The structures for these event types contain:
13707typedef struct {
13708 int type; /* ButtonPress or ButtonRelease */
13709 unsigned long serial; /* # of last request processed by s
13710erver */
13711 Bool send_event; /* true if this came from a SendEve
13712nt request */
13713 Display *display; /* Display the event was read from
13714*/
13715 Window window; /* ``event'' window it is reported
13716relative to */
13717 Window root; /* root window that the event occur
13718red on */
13719 Window subwindow; /* child window */
13720 Time time; /* milliseconds */
13721 int x, y; /* pointer x, y coordinates in even
13722t window */
13723 int x_root, y_root; /* coordinates relative to root */
13724 unsigned int state; /* key or button mask */
13725 unsigned int button; /* detail */
13726 Bool same_screen; /* same screen flag */
13727} XButtonEvent;
13728typedef XButtonEvent XButtonPressedEvent;
13729typedef XButtonEvent XButtonReleasedEvent;
13730
13731typedef struct {
13732 int type; /* KeyPress or KeyRelease */
13733 unsigned long serial; /* # of last request processed by s
13734erver */
13735 Bool send_event; /* true if this came from a SendEve
13736nt request */
13737 Display *display; /* Display the event was read from
13738*/
13739 Window window; /* ``event'' window it is reported
13740relative to */
13741 Window root; /* root window that the event occur
13742red on */
13743 Window subwindow; /* child window */
13744 Time time; /* milliseconds */
13745 int x, y; /* pointer x, y coordinates in even
13746t window */
13747 int x_root, y_root; /* coordinates relative to root */
13748 unsigned int state; /* key or button mask */
13749 unsigned int keycode; /* detail */
13750 Bool same_screen; /* same screen flag */
13751} XKeyEvent;
13752typedef XKeyEvent XKeyPressedEvent;
13753typedef XKeyEvent XKeyReleasedEvent;
13754
13755typedef struct {
13756 int type; /* MotionNotify */
13757 unsigned long serial; /* # of last request processed by
13758 server */
13759 Bool send_event; /* true if this came from a SendE
13760vent request */
13761 Display *display; /* Display the event was read fro
13762m */
13763 Window window; /* ``event'' window reported rela
13764tive to */
13765 Window root; /* root window that the event occ
13766urred on */
13767 Window subwindow; /* child window */
13768 Time time; /* milliseconds */
13769 int x, y; /* pointer x, y coordinates in ev
13770ent window */
13771 int x_root, y_root; /* coordinates relative to root *
13772/
13773 unsigned int state; /* key or button mask */
13774 char is_hint; /* detail */
13775 Bool same_screen; /* same screen flag */
13776} XMotionEvent;
13777typedef XMotionEvent XPointerMovedEvent;
13778
13779 These structures have the following common members: window,
13780 root, subwindow, time, x, y, x_root, y_root, state, and
13781 same_screen. The window member is set to the window on which
13782 the event was generated and is referred to as the event window.
13783 As long as the conditions previously discussed are met, this is
13784 the window used by the X server to report the event. The root
13785 member is set to the source window's root window. The x_root
13786 and y_root members are set to the pointer's coordinates
13787 relative to the root window's origin at the time of the event.
13788
13789 The same_screen member is set to indicate whether the event
13790 window is on the same screen as the root window and can be
13791 either True or False. If True, the event and root windows are
13792 on the same screen. If False, the event and root windows are
13793 not on the same screen.
13794
13795 If the source window is an inferior of the event window, the
13796 subwindow member of the structure is set to the child of the
13797 event window that is the source window or the child of the
13798 event window that is an ancestor of the source window.
13799 Otherwise, the X server sets the subwindow member to None. The
13800 time member is set to the time when the event was generated and
13801 is expressed in milliseconds.
13802
13803 If the event window is on the same screen as the root window,
13804 the x and y members are set to the coordinates relative to the
13805 event window's origin. Otherwise, these members are set to
13806 zero.
13807
13808 The state member is set to indicate the logical state of the
13809 pointer buttons and modifier keys just prior to the event,
13810 which is the bitwise inclusive OR of one or more of the button
13811 or modifier key masks: Button1Mask, Button2Mask, Button3Mask,
13812 Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask,
13813 Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.
13814
13815 Each of these structures also has a member that indicates the
13816 detail. For the XKeyPressedEvent and XKeyReleasedEvent
13817 structures, this member is called a keycode. It is set to a
13818 number that represents a physical key on the keyboard. The
13819 keycode is an arbitrary representation for any key on the
13820 keyboard (see sections 12.7 and 16.1).
13821
13822 For the XButtonPressedEvent and XButtonReleasedEvent
13823 structures, this member is called button. It represents the
13824 pointer button that changed state and can be the Button1,
13825 Button2, Button3, Button4, or Button5 value. For the
13826 XPointerMovedEvent structure, this member is called is_hint. It
13827 can be set to NotifyNormal or NotifyHint.
13828
13829 Some of the symbols mentioned in this section have fixed
13830 values, as follows:
13831 Symbol Value
13832 Button1MotionMask (1L<<8)
13833 Button2MotionMask (1L<<9)
13834 Button3MotionMask (1L<<10)
13835 Button4MotionMask (1L<<11)
13836 Button5MotionMask (1L<<12)
13837 Button1Mask (1<<8)
13838 Button2Mask (1<<9)
13839 Button3Mask (1<<10)
13840 Button4Mask (1<<11)
13841 Button5Mask (1<<12)
13842 ShiftMask (1<<0)
13843 LockMask (1<<1)
13844 ControlMask (1<<2)
13845 Mod1Mask (1<<3)
13846 Mod2Mask (1<<4)
13847 Mod3Mask (1<<5)
13848 Mod4Mask (1<<6)
13849 Mod5Mask (1<<7)
13850 Button1 1
13851 Button2 2
13852 Button3 3
13853 Button4 4
13854 Button5 5
13855
13856Window Entry/Exit Events
13857
13858 This section describes the processing that occurs for the
13859 window crossing events EnterNotify and LeaveNotify. If a
13860 pointer motion or a window hierarchy change causes the pointer
13861 to be in a different window than before, the X server reports
13862 EnterNotify or LeaveNotify events to clients who have selected
13863 for these events. All EnterNotify and LeaveNotify events caused
13864 by a hierarchy change are generated after any hierarchy event
13865 (UnmapNotify, MapNotify, ConfigureNotify, GravityNotify,
13866 CirculateNotify) caused by that change; however, the X protocol
13867 does not constrain the ordering of EnterNotify and LeaveNotify
13868 events with respect to FocusOut, VisibilityNotify, and Expose
13869 events.
13870
13871 This contrasts with MotionNotify events, which are also
13872 generated when the pointer moves but only when the pointer
13873 motion begins and ends in a single window. An EnterNotify or
13874 LeaveNotify event also can be generated when some client
13875 application calls XGrabPointer and XUngrabPointer.
13876
13877 To receive EnterNotify or LeaveNotify events, set the
13878 EnterWindowMask or LeaveWindowMask bits of the event-mask
13879 attribute of the window.
13880
13881 The structure for these event types contains:
13882
13883
13884typedef struct {
13885 int type; /* EnterNotify or LeaveNotify */
13886 unsigned long serial; /* # of last request processed by ser
13887ver */
13888 Bool send_event; /* true if this came from a SendEvent
13889 request */
13890 Display *display; /* Display the event was read from */
13891 Window window; /* ``event'' window reported relative
13892 to */
13893 Window root; /* root window that the event occurre
13894d on */
13895 Window subwindow; /* child window */
13896 Time time; /* milliseconds */
13897 int x, y; /* pointer x, y coordinates in event
13898window */
13899 int x_root, y_root; /* coordinates relative to root */
13900 int mode; /* NotifyNormal, NotifyGrab, NotifyUn
13901grab */
13902 int detail;
13903 /*
13904 * NotifyAncestor, NotifyVirtual, NotifyInferior,
13905 * NotifyNonlinear,NotifyNonlinearVirtual
13906 */
13907 Bool same_screen; /* same screen flag */
13908 Bool focus; /* boolean focus */
13909 unsigned int state; /* key or button mask */
13910} XCrossingEvent;
13911typedef XCrossingEvent XEnterWindowEvent;
13912typedef XCrossingEvent XLeaveWindowEvent;
13913
13914 The window member is set to the window on which the EnterNotify
13915 or LeaveNotify event was generated and is referred to as the
13916 event window. This is the window used by the X server to report
13917 the event, and is relative to the root window on which the
13918 event occurred. The root member is set to the root window of
13919 the screen on which the event occurred.
13920
13921 For a LeaveNotify event, if a child of the event window
13922 contains the initial position of the pointer, the subwindow
13923 component is set to that child. Otherwise, the X server sets
13924 the subwindow member to None. For an EnterNotify event, if a
13925 child of the event window contains the final pointer position,
13926 the subwindow component is set to that child or None.
13927
13928 The time member is set to the time when the event was generated
13929 and is expressed in milliseconds. The x and y members are set
13930 to the coordinates of the pointer position in the event window.
13931 This position is always the pointer's final position, not its
13932 initial position. If the event window is on the same screen as
13933 the root window, x and y are the pointer coordinates relative
13934 to the event window's origin. Otherwise, x and y are set to
13935 zero. The x_root and y_root members are set to the pointer's
13936 coordinates relative to the root window's origin at the time of
13937 the event.
13938
13939 The same_screen member is set to indicate whether the event
13940 window is on the same screen as the root window and can be
13941 either True or False. If True, the event and root windows are
13942 on the same screen. If False, the event and root windows are
13943 not on the same screen.
13944
13945 The focus member is set to indicate whether the event window is
13946 the focus window or an inferior of the focus window. The X
13947 server can set this member to either True or False. If True,
13948 the event window is the focus window or an inferior of the
13949 focus window. If False, the event window is not the focus
13950 window or an inferior of the focus window.
13951
13952 The state member is set to indicate the state of the pointer
13953 buttons and modifier keys just prior to the event. The X server
13954 can set this member to the bitwise inclusive OR of one or more
13955 of the button or modifier key masks: Button1Mask, Button2Mask,
13956 Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask,
13957 ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask.
13958
13959 The mode member is set to indicate whether the events are
13960 normal events, pseudo-motion events when a grab activates, or
13961 pseudo-motion events when a grab deactivates. The X server can
13962 set this member to NotifyNormal, NotifyGrab, or NotifyUngrab.
13963
13964 The detail member is set to indicate the notify detail and can
13965 be NotifyAncestor, NotifyVirtual, NotifyInferior,
13966 NotifyNonlinear, or NotifyNonlinearVirtual.
13967
13968Normal Entry/Exit Events
13969
13970 EnterNotify and LeaveNotify events are generated when the
13971 pointer moves from one window to another window. Normal events
13972 are identified by XEnterWindowEvent or XLeaveWindowEvent
13973 structures whose mode member is set to NotifyNormal.
13974 * When the pointer moves from window A to window B and A is
13975 an inferior of B, the X server does the following:
13976 * It generates a LeaveNotify event on window A, with the
13977 detail member of the XLeaveWindowEvent structure set to
13978 NotifyAncestor.
13979 * It generates a LeaveNotify event on each window between
13980 window A and window B, exclusive, with the detail member of
13981 each XLeaveWindowEvent structure set to NotifyVirtual.
13982 * It generates an EnterNotify event on window B, with the
13983 detail member of the XEnterWindowEvent structure set to
13984 NotifyInferior.
13985 * When the pointer moves from window A to window B and B is
13986 an inferior of A, the X server does the following:
13987 * It generates a LeaveNotify event on window A, with the
13988 detail member of the XLeaveWindowEvent structure set to
13989 NotifyInferior.
13990 * It generates an EnterNotify event on each window between
13991 window A and window B, exclusive, with the detail member of
13992 each XEnterWindowEvent structure set to NotifyVirtual.
13993 * It generates an EnterNotify event on window B, with the
13994 detail member of the XEnterWindowEvent structure set to
13995 NotifyAncestor.
13996 * When the pointer moves from window A to window B and window
13997 C is their least common ancestor, the X server does the
13998 following:
13999 * It generates a LeaveNotify event on window A, with the
14000 detail member of the XLeaveWindowEvent structure set to
14001 NotifyNonlinear.
14002 * It generates a LeaveNotify event on each window between
14003 window A and window C, exclusive, with the detail member of
14004 each XLeaveWindowEvent structure set to
14005 NotifyNonlinearVirtual.
14006 * It generates an EnterNotify event on each window between
14007 window C and window B, exclusive, with the detail member of
14008 each XEnterWindowEvent structure set to
14009 NotifyNonlinearVirtual.
14010 * It generates an EnterNotify event on window B, with the
14011 detail member of the XEnterWindowEvent structure set to
14012 NotifyNonlinear.
14013 * When the pointer moves from window A to window B on
14014 different screens, the X server does the following:
14015 * It generates a LeaveNotify event on window A, with the
14016 detail member of the XLeaveWindowEvent structure set to
14017 NotifyNonlinear.
14018 * If window A is not a root window, it generates a
14019 LeaveNotify event on each window above window A up to and
14020 including its root, with the detail member of each
14021 XLeaveWindowEvent structure set to NotifyNonlinearVirtual.
14022 * If window B is not a root window, it generates an
14023 EnterNotify event on each window from window B's root down
14024 to but not including window B, with the detail member of
14025 each XEnterWindowEvent structure set to
14026 NotifyNonlinearVirtual.
14027 * It generates an EnterNotify event on window B, with the
14028 detail member of the XEnterWindowEvent structure set to
14029 NotifyNonlinear.
14030
14031Grab and Ungrab Entry/Exit Events
14032
14033 Pseudo-motion mode EnterNotify and LeaveNotify events are
14034 generated when a pointer grab activates or deactivates. Events
14035 in which the pointer grab activates are identified by
14036 XEnterWindowEvent or XLeaveWindowEvent structures whose mode
14037 member is set to NotifyGrab. Events in which the pointer grab
14038 deactivates are identified by XEnterWindowEvent or
14039 XLeaveWindowEvent structures whose mode member is set to
14040 NotifyUngrab (see XGrabPointer).
14041 * When a pointer grab activates after any initial warp into a
14042 confine_to window and before generating any actual
14043 ButtonPress event that activates the grab, G is the
14044 grab_window for the grab, and P is the window the pointer
14045 is in, the X server does the following:
14046 * It generates EnterNotify and LeaveNotify events (see
14047 section 10.6.1) with the mode members of the
14048 XEnterWindowEvent and XLeaveWindowEvent structures set to
14049 NotifyGrab. These events are generated as if the pointer
14050 were to suddenly warp from its current position in P to
14051 some position in G. However, the pointer does not warp, and
14052 the X server uses the pointer position as both the initial
14053 and final positions for the events.
14054 * When a pointer grab deactivates after generating any actual
14055 ButtonRelease event that deactivates the grab, G is the
14056 grab_window for the grab, and P is the window the pointer
14057 is in, the X server does the following:
14058 * It generates EnterNotify and LeaveNotify events (see
14059 section 10.6.1) with the mode members of the
14060 XEnterWindowEvent and XLeaveWindowEvent structures set to
14061 NotifyUngrab. These events are generated as if the pointer
14062 were to suddenly warp from some position in G to its
14063 current position in P. However, the pointer does not warp,
14064 and the X server uses the current pointer position as both
14065 the initial and final positions for the events.
14066
14067Input Focus Events
14068
14069 This section describes the processing that occurs for the input
14070 focus events FocusIn and FocusOut. The X server can report
14071 FocusIn or FocusOut events to clients wanting information about
14072 when the input focus changes. The keyboard is always attached
14073 to some window (typically, the root window or a top-level
14074 window), which is called the focus window. The focus window and
14075 the position of the pointer determine the window that receives
14076 keyboard input. Clients may need to know when the input focus
14077 changes to control highlighting of areas on the screen.
14078
14079 To receive FocusIn or FocusOut events, set the FocusChangeMask
14080 bit in the event-mask attribute of the window.
14081
14082 The structure for these event types contains:
14083
14084
14085typedef struct {
14086 int type; /* FocusIn or FocusOut */
14087 unsigned long serial; /* # of last request processed by server
14088*/
14089 Bool send_event; /* true if this came from a SendEvent req
14090uest */
14091 Display *display; /* Display the event was read from */
14092 Window window; /* window of event */
14093 int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab
14094 */
14095 int detail;
14096 /*
14097 * NotifyAncestor, NotifyVirtual, NotifyInferior,
14098 * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPoin
14099ter,
14100 * NotifyPointerRoot, NotifyDetailNone
14101 */
14102} XFocusChangeEvent;
14103typedef XFocusChangeEvent XFocusInEvent;
14104typedef XFocusChangeEvent XFocusOutEvent;
14105
14106 The window member is set to the window on which the FocusIn or
14107 FocusOut event was generated. This is the window used by the X
14108 server to report the event. The mode member is set to indicate
14109 whether the focus events are normal focus events, focus events
14110 while grabbed, focus events when a grab activates, or focus
14111 events when a grab deactivates. The X server can set the mode
14112 member to NotifyNormal, NotifyWhileGrabbed, NotifyGrab, or
14113 NotifyUngrab.
14114
14115 All FocusOut events caused by a window unmap are generated
14116 after any UnmapNotify event; however, the X protocol does not
14117 constrain the ordering of FocusOut events with respect to
14118 generated EnterNotify, LeaveNotify, VisibilityNotify, and
14119 Expose events.
14120
14121 Depending on the event mode, the detail member is set to
14122 indicate the notify detail and can be NotifyAncestor,
14123 NotifyVirtual, NotifyInferior, NotifyNonlinear,
14124 NotifyNonlinearVirtual, NotifyPointer, NotifyPointerRoot, or
14125 NotifyDetailNone.
14126
14127Normal Focus Events and Focus Events While Grabbed
14128
14129 Normal focus events are identified by XFocusInEvent or
14130 XFocusOutEvent structures whose mode member is set to
14131 NotifyNormal. Focus events while grabbed are identified by
14132 XFocusInEvent or XFocusOutEvent structures whose mode member is
14133 set to NotifyWhileGrabbed. The X server processes normal focus
14134 and focus events while grabbed according to the following:
14135 * When the focus moves from window A to window B, A is an
14136 inferior of B, and the pointer is in window P, the X server
14137 does the following:
14138 * It generates a FocusOut event on window A, with the detail
14139 member of the XFocusOutEvent structure set to
14140 NotifyAncestor.
14141 * It generates a FocusOut event on each window between window
14142 A and window B, exclusive, with the detail member of each
14143 XFocusOutEvent structure set to NotifyVirtual.
14144 * It generates a FocusIn event on window B, with the detail
14145 member of the XFocusOutEvent structure set to
14146 NotifyInferior.
14147 * If window P is an inferior of window B but window P is not
14148 window A or an inferior or ancestor of window A, it
14149 generates a FocusIn event on each window below window B,
14150 down to and including window P, with the detail member of
14151 each XFocusInEvent structure set to NotifyPointer.
14152 * When the focus moves from window A to window B, B is an
14153 inferior of A, and the pointer is in window P, the X server
14154 does the following:
14155 * If window P is an inferior of window A but P is not an
14156 inferior of window B or an ancestor of B, it generates a
14157 FocusOut event on each window from window P up to but not
14158 including window A, with the detail member of each
14159 XFocusOutEvent structure set to NotifyPointer.
14160 * It generates a FocusOut event on window A, with the detail
14161 member of the XFocusOutEvent structure set to
14162 NotifyInferior.
14163 * It generates a FocusIn event on each window between window
14164 A and window B, exclusive, with the detail member of each
14165 XFocusInEvent structure set to NotifyVirtual.
14166 * It generates a FocusIn event on window B, with the detail
14167 member of the XFocusInEvent structure set to
14168 NotifyAncestor.
14169 * When the focus moves from window A to window B, window C is
14170 their least common ancestor, and the pointer is in window
14171 P, the X server does the following:
14172 * If window P is an inferior of window A, it generates a
14173 FocusOut event on each window from window P up to but not
14174 including window A, with the detail member of the
14175 XFocusOutEvent structure set to NotifyPointer.
14176 * It generates a FocusOut event on window A, with the detail
14177 member of the XFocusOutEvent structure set to
14178 NotifyNonlinear.
14179 * It generates a FocusOut event on each window between window
14180 A and window C, exclusive, with the detail member of each
14181 XFocusOutEvent structure set to NotifyNonlinearVirtual.
14182 * It generates a FocusIn event on each window between C and
14183 B, exclusive, with the detail member of each XFocusInEvent
14184 structure set to NotifyNonlinearVirtual.
14185 * It generates a FocusIn event on window B, with the detail
14186 member of the XFocusInEvent structure set to
14187 NotifyNonlinear.
14188 * If window P is an inferior of window B, it generates a
14189 FocusIn event on each window below window B down to and
14190 including window P, with the detail member of the
14191 XFocusInEvent structure set to NotifyPointer.
14192 * When the focus moves from window A to window B on different
14193 screens and the pointer is in window P, the X server does
14194 the following:
14195 * If window P is an inferior of window A, it generates a
14196 FocusOut event on each window from window P up to but not
14197 including window A, with the detail member of each
14198 XFocusOutEvent structure set to NotifyPointer.
14199 * It generates a FocusOut event on window A, with the detail
14200 member of the XFocusOutEvent structure set to
14201 NotifyNonlinear.
14202 * If window A is not a root window, it generates a FocusOut
14203 event on each window above window A up to and including its
14204 root, with the detail member of each XFocusOutEvent
14205 structure set to NotifyNonlinearVirtual.
14206 * If window B is not a root window, it generates a FocusIn
14207 event on each window from window B's root down to but not
14208 including window B, with the detail member of each
14209 XFocusInEvent structure set to NotifyNonlinearVirtual.
14210 * It generates a FocusIn event on window B, with the detail
14211 member of each XFocusInEvent structure set to
14212 NotifyNonlinear.
14213 * If window P is an inferior of window B, it generates a
14214 FocusIn event on each window below window B down to and
14215 including window P, with the detail member of each
14216 XFocusInEvent structure set to NotifyPointer.
14217 * When the focus moves from window A to PointerRoot (events
14218 sent to the window under the pointer) or None (discard),
14219 and the pointer is in window P, the X server does the
14220 following:
14221 * If window P is an inferior of window A, it generates a
14222 FocusOut event on each window from window P up to but not
14223 including window A, with the detail member of each
14224 XFocusOutEvent structure set to NotifyPointer.
14225 * It generates a FocusOut event on window A, with the detail
14226 member of the XFocusOutEvent structure set to
14227 NotifyNonlinear.
14228 * If window A is not a root window, it generates a FocusOut
14229 event on each window above window A up to and including its
14230 root, with the detail member of each XFocusOutEvent
14231 structure set to NotifyNonlinearVirtual.
14232 * It generates a FocusIn event on the root window of all
14233 screens, with the detail member of each XFocusInEvent
14234 structure set to NotifyPointerRoot (or NotifyDetailNone).
14235 * If the new focus is PointerRoot, it generates a FocusIn
14236 event on each window from window P's root down to and
14237 including window P, with the detail member of each
14238 XFocusInEvent structure set to NotifyPointer.
14239 * When the focus moves from PointerRoot (events sent to the
14240 window under the pointer) or None to window A, and the
14241 pointer is in window P, the X server does the following:
14242 * If the old focus is PointerRoot, it generates a FocusOut
14243 event on each window from window P up to and including
14244 window P's root, with the detail member of each
14245 XFocusOutEvent structure set to NotifyPointer.
14246 * It generates a FocusOut event on all root windows, with the
14247 detail member of each XFocusOutEvent structure set to
14248 NotifyPointerRoot (or NotifyDetailNone).
14249 * If window A is not a root window, it generates a FocusIn
14250 event on each window from window A's root down to but not
14251 including window A, with the detail member of each
14252 XFocusInEvent structure set to NotifyNonlinearVirtual.
14253 * It generates a FocusIn event on window A, with the detail
14254 member of the XFocusInEvent structure set to
14255 NotifyNonlinear.
14256 * If window P is an inferior of window A, it generates a
14257 FocusIn event on each window below window A down to and
14258 including window P, with the detail member of each
14259 XFocusInEvent structure set to NotifyPointer.
14260 * When the focus moves from PointerRoot (events sent to the
14261 window under the pointer) to None (or vice versa), and the
14262 pointer is in window P, the X server does the following:
14263 * If the old focus is PointerRoot, it generates a FocusOut
14264 event on each window from window P up to and including
14265 window P's root, with the detail member of each
14266 XFocusOutEvent structure set to NotifyPointer.
14267 * It generates a FocusOut event on all root windows, with the
14268 detail member of each XFocusOutEvent structure set to
14269 either NotifyPointerRoot or NotifyDetailNone.
14270 * It generates a FocusIn event on all root windows, with the
14271 detail member of each XFocusInEvent structure set to
14272 NotifyDetailNone or NotifyPointerRoot.
14273 * If the new focus is PointerRoot, it generates a FocusIn
14274 event on each window from window P's root down to and
14275 including window P, with the detail member of each
14276 XFocusInEvent structure set to NotifyPointer.
14277
14278Focus Events Generated by Grabs
14279
14280 Focus events in which the keyboard grab activates are
14281 identified by XFocusInEvent or XFocusOutEvent structures whose
14282 mode member is set to NotifyGrab. Focus events in which the
14283 keyboard grab deactivates are identified by XFocusInEvent or
14284 XFocusOutEvent structures whose mode member is set to
14285 NotifyUngrab (see XGrabKeyboard).
14286 * When a keyboard grab activates before generating any actual
14287 KeyPress event that activates the grab, G is the
14288 grab_window, and F is the current focus, the X server does
14289 the following:
14290 * It generates FocusIn and FocusOut events, with the mode
14291 members of the XFocusInEvent and XFocusOutEvent structures
14292 set to NotifyGrab. These events are generated as if the
14293 focus were to change from F to G.
14294 * When a keyboard grab deactivates after generating any
14295 actual KeyRelease event that deactivates the grab, G is the
14296 grab_window, and F is the current focus, the X server does
14297 the following:
14298 * It generates FocusIn and FocusOut events, with the mode
14299 members of the XFocusInEvent and XFocusOutEvent structures
14300 set to NotifyUngrab. These events are generated as if the
14301 focus were to change from G to F.
14302
14303Key Map State Notification Events
14304
14305 The X server can report KeymapNotify events to clients that
14306 want information about changes in their keyboard state.
14307
14308 To receive KeymapNotify events, set the KeymapStateMask bit in
14309 the event-mask attribute of the window. The X server generates
14310 this event immediately after every EnterNotify and FocusIn
14311 event.
14312
14313 The structure for this event type contains:
14314
14315
14316
14317/* generated on EnterWindow and FocusIn when KeymapState selected */
14318typedef struct {
14319 int type; /* KeymapNotify */
14320 unsigned long serial; /* # of last request processed by se
14321rver */
14322 Bool send_event; /* true if this came from a SendEven
14323t request */
14324 Display *display; /* Display the event was read from *
14325/
14326 Window window;
14327 char key_vector[32];
14328} XKeymapEvent;
14329
14330 The window member is not used but is present to aid some
14331 toolkits. The key_vector member is set to the bit vector of the
14332 keyboard. Each bit set to 1 indicates that the corresponding
14333 key is currently pressed. The vector is represented as 32
14334 bytes. Byte N (from 0) contains the bits for keys 8N to 8N + 7
14335 with the least significant bit in the byte representing key 8N.
14336
14337Exposure Events
14338
14339 The X protocol does not guarantee to preserve the contents of
14340 window regions when the windows are obscured or reconfigured.
14341 Some implementations may preserve the contents of windows.
14342 Other implementations are free to destroy the contents of
14343 windows when exposed. X expects client applications to assume
14344 the responsibility for restoring the contents of an exposed
14345 window region. (An exposed window region describes a formerly
14346 obscured window whose region becomes visible.) Therefore, the X
14347 server sends Expose events describing the window and the region
14348 of the window that has been exposed. A naive client application
14349 usually redraws the entire window. A more sophisticated client
14350 application redraws only the exposed region.
14351
14352Expose Events
14353
14354 The X server can report Expose events to clients wanting
14355 information about when the contents of window regions have been
14356 lost. The circumstances in which the X server generates Expose
14357 events are not as definite as those for other events. However,
14358 the X server never generates Expose events on windows whose
14359 class you specified as InputOnly. The X server can generate
14360 Expose events when no valid contents are available for regions
14361 of a window and either the regions are visible, the regions are
14362 viewable and the server is (perhaps newly) maintaining backing
14363 store on the window, or the window is not viewable but the
14364 server is (perhaps newly) honoring the window's backing-store
14365 attribute of Always or WhenMapped. The regions decompose into
14366 an (arbitrary) set of rectangles, and an Expose event is
14367 generated for each rectangle. For any given window, the X
14368 server guarantees to report contiguously all of the regions
14369 exposed by some action that causes Expose events, such as
14370 raising a window.
14371
14372 To receive Expose events, set the ExposureMask bit in the
14373 event-mask attribute of the window.
14374
14375 The structure for this event type contains:
14376
14377
14378
14379typedef struct {
14380 int type; /* Expose */
14381 unsigned long serial; /* # of last request processed by ser
14382ver */
14383 Bool send_event; /* true if this came from a SendEvent
14384 request */
14385 Display *display; /* Display the event was read from */
14386 Window window;
14387 int x, y;
14388 int width, height;
14389 int count; /* if nonzero, at least this many mor
14390e */
14391} XExposeEvent;
14392
14393 The window member is set to the exposed (damaged) window. The x
14394 and y members are set to the coordinates relative to the
14395 window's origin and indicate the upper-left corner of the
14396 rectangle. The width and height members are set to the size
14397 (extent) of the rectangle. The count member is set to the
14398 number of Expose events that are to follow. If count is zero,
14399 no more Expose events follow for this window. However, if count
14400 is nonzero, at least that number of Expose events (and possibly
14401 more) follow for this window. Simple applications that do not
14402 want to optimize redisplay by distinguishing between subareas
14403 of its window can just ignore all Expose events with nonzero
14404 counts and perform full redisplays on events with zero counts.
14405
14406GraphicsExpose and NoExpose Events
14407
14408 The X server can report GraphicsExpose events to clients
14409 wanting information about when a destination region could not
14410 be computed during certain graphics requests: XCopyArea or
14411 XCopyPlane. The X server generates this event whenever a
14412 destination region could not be computed because of an obscured
14413 or out-of-bounds source region. In addition, the X server
14414 guarantees to report contiguously all of the regions exposed by
14415 some graphics request (for example, copying an area of a
14416 drawable to a destination drawable).
14417
14418 The X server generates a NoExpose event whenever a graphics
14419 request that might produce a GraphicsExpose event does not
14420 produce any. In other words, the client is really asking for a
14421 GraphicsExpose event but instead receives a NoExpose event.
14422
14423 To receive GraphicsExpose or NoExpose events, you must first
14424 set the graphics-exposure attribute of the graphics context to
14425 True. You also can set the graphics-expose attribute when
14426 creating a graphics context using XCreateGC or by calling
14427 XSetGraphicsExposures.
14428
14429 The structures for these event types contain:
14430
14431
14432
14433typedef struct {
14434 int type; /* GraphicsExpose */
14435 unsigned long serial; /* # of last request processed by se
14436rver */
14437 Bool send_event; /* true if this came from a SendEven
14438t request */
14439 Display *display; /* Display the event was read from *
14440/
14441 Drawable drawable;
14442 int x, y;
14443 int width, height;
14444 int count; /* if nonzero, at least this many mo
14445re */
14446 int major_code; /* core is CopyArea or CopyPlane */
14447 int minor_code; /* not defined in the core */
14448} XGraphicsExposeEvent;
14449
14450
14451
14452typedef struct {
14453 int type; /* NoExpose */
14454 unsigned long serial; /* # of last request processed by serve
14455r */
14456 Bool send_event; /* true if this came from a SendEvent r
14457equest */
14458 Display *display; /* Display the event was read from */
14459 Drawable drawable;
14460 int major_code; /* core is CopyArea or CopyPlane */
14461 int minor_code; /* not defined in the core */
14462} XNoExposeEvent;
14463
14464 Both structures have these common members: drawable,
14465 major_code, and minor_code. The drawable member is set to the
14466 drawable of the destination region on which the graphics
14467 request was to be performed. The major_code member is set to
14468 the graphics request initiated by the client and can be either
14469 X_CopyArea or X_CopyPlane. If it is X_CopyArea, a call to
14470 XCopyArea initiated the request. If it is X_CopyPlane, a call
14471 to XCopyPlane initiated the request. These constants are
14472 defined in <X11/Xproto.h>. The minor_code member, like the
14473 major_code member, indicates which graphics request was
14474 initiated by the client. However, the minor_code member is not
14475 defined by the core X protocol and will be zero in these cases,
14476 although it may be used by an extension.
14477
14478 The XGraphicsExposeEvent structure has these additional
14479 members: x, y, width, height, and count. The x and y members
14480 are set to the coordinates relative to the drawable's origin
14481 and indicate the upper-left corner of the rectangle. The width
14482 and height members are set to the size (extent) of the
14483 rectangle. The count member is set to the number of
14484 GraphicsExpose events to follow. If count is zero, no more
14485 GraphicsExpose events follow for this window. However, if count
14486 is nonzero, at least that number of GraphicsExpose events (and
14487 possibly more) are to follow for this window.
14488
14489Window State Change Events
14490
14491 The following sections discuss:
14492 * CirculateNotify events
14493 * ConfigureNotify events
14494 * CreateNotify events
14495 * DestroyNotify events
14496 * GravityNotify events
14497 * MapNotify events
14498 * MappingNotify events
14499 * ReparentNotify events
14500 * UnmapNotify events
14501 * VisibilityNotify events
14502
14503CirculateNotify Events
14504
14505 The X server can report CirculateNotify events to clients
14506 wanting information about when a window changes its position in
14507 the stack. The X server generates this event type whenever a
14508 window is actually restacked as a result of a client
14509 application calling XCirculateSubwindows,
14510 XCirculateSubwindowsUp, or XCirculateSubwindowsDown.
14511
14512 To receive CirculateNotify events, set the StructureNotifyMask
14513 bit in the event-mask attribute of the window or the
14514 SubstructureNotifyMask bit in the event-mask attribute of the
14515 parent window (in which case, circulating any child generates
14516 an event).
14517
14518 The structure for this event type contains:
14519
14520
14521
14522typedef struct {
14523 int type; /* CirculateNotify */
14524 unsigned long serial; /* # of last request processed by server
14525*/
14526 Bool send_event; /* true if this came from a SendEvent request
14527*/
14528 Display *display; /* Display the event was read from */
14529 Window event;
14530 Window window;
14531 int place; /* PlaceOnTop, PlaceOnBottom */
14532} XCirculateEvent;
14533
14534 The event member is set either to the restacked window or to
14535 its parent, depending on whether StructureNotify or
14536 SubstructureNotify was selected. The window member is set to
14537 the window that was restacked. The place member is set to the
14538 window's position after the restack occurs and is either
14539 PlaceOnTop or PlaceOnBottom. If it is PlaceOnTop, the window is
14540 now on top of all siblings. If it is PlaceOnBottom, the window
14541 is now below all siblings.
14542
14543ConfigureNotify Events
14544
14545 The X server can report ConfigureNotify events to clients
14546 wanting information about actual changes to a window's state,
14547 such as size, position, border, and stacking order. The X
14548 server generates this event type whenever one of the following
14549 configure window requests made by a client application actually
14550 completes:
14551 * A window's size, position, border, and/or stacking order is
14552 reconfigured by calling XConfigureWindow.
14553 * The window's position in the stacking order is changed by
14554 calling XLowerWindow, XRaiseWindow, or XRestackWindows.
14555 * A window is moved by calling XMoveWindow.
14556 * A window's size is changed by calling XResizeWindow.
14557 * A window's size and location is changed by calling
14558 XMoveResizeWindow.
14559 * A window is mapped and its position in the stacking order
14560 is changed by calling XMapRaised.
14561 * A window's border width is changed by calling
14562 XSetWindowBorderWidth.
14563
14564 To receive ConfigureNotify events, set the StructureNotifyMask
14565 bit in the event-mask attribute of the window or the
14566 SubstructureNotifyMask bit in the event-mask attribute of the
14567 parent window (in which case, configuring any child generates
14568 an event).
14569
14570 The structure for this event type contains:
14571
14572
14573typedef struct {
14574 int type; /* ConfigureNotify */
14575 unsigned long serial; /* # of last request processed by server
14576*/
14577 Bool send_event; /* true if this came from a SendEvent req
14578uest */
14579 Display *display; /* Display the event was read from */
14580 Window event;
14581 Window window;
14582 int x, y;
14583 int width, height;
14584 int border_width;
14585 Window above;
14586 Bool override_redirect;
14587} XConfigureEvent;
14588
14589 The event member is set either to the reconfigured window or to
14590 its parent, depending on whether StructureNotify or
14591 SubstructureNotify was selected. The window member is set to
14592 the window whose size, position, border, and/or stacking order
14593 was changed.
14594
14595 The x and y members are set to the coordinates relative to the
14596 parent window's origin and indicate the position of the
14597 upper-left outside corner of the window. The width and height
14598 members are set to the inside size of the window, not including
14599 the border. The border_width member is set to the width of the
14600 window's border, in pixels.
14601
14602 The above member is set to the sibling window and is used for
14603 stacking operations. If the X server sets this member to None,
14604 the window whose state was changed is on the bottom of the
14605 stack with respect to sibling windows. However, if this member
14606 is set to a sibling window, the window whose state was changed
14607 is placed on top of this sibling window.
14608
14609 The override_redirect member is set to the override-redirect
14610 attribute of the window. Window manager clients normally should
14611 ignore this window if the override_redirect member is True.
14612
14613CreateNotify Events
14614
14615 The X server can report CreateNotify events to clients wanting
14616 information about creation of windows. The X server generates
14617 this event whenever a client application creates a window by
14618 calling XCreateWindow or XCreateSimpleWindow.
14619
14620 To receive CreateNotify events, set the SubstructureNotifyMask
14621 bit in the event-mask attribute of the window. Creating any
14622 children then generates an event.
14623
14624 The structure for the event type contains:
14625
14626
14627
14628typedef struct {
14629 int type; /* CreateNotify */
14630 unsigned long serial; /* # of last request processed by
14631 server */
14632 Bool send_event; /* true if this came from a SendE
14633vent request */
14634 Display *display; /* Display the event was read fro
14635m */
14636 Window parent; /* parent of the window */
14637 Window window; /* window id of window created */
14638 int x, y; /* window location */
14639 int width, height; /* size of window */
14640 int border_width; /* border width */
14641 Bool override_redirect; /* creation should be overridden
14642*/
14643} XCreateWindowEvent;
14644
14645 The parent member is set to the created window's parent. The
14646 window member specifies the created window. The x and y members
14647 are set to the created window's coordinates relative to the
14648 parent window's origin and indicate the position of the
14649 upper-left outside corner of the created window. The width and
14650 height members are set to the inside size of the created window
14651 (not including the border) and are always nonzero. The
14652 border_width member is set to the width of the created window's
14653 border, in pixels. The override_redirect member is set to the
14654 override-redirect attribute of the window. Window manager
14655 clients normally should ignore this window if the
14656 override_redirect member is True.
14657
14658DestroyNotify Events
14659
14660 The X server can report DestroyNotify events to clients wanting
14661 information about which windows are destroyed. The X server
14662 generates this event whenever a client application destroys a
14663 window by calling XDestroyWindow or XDestroySubwindows.
14664
14665 The ordering of the DestroyNotify events is such that for any
14666 given window, DestroyNotify is generated on all inferiors of
14667 the window before being generated on the window itself. The X
14668 protocol does not constrain the ordering among siblings and
14669 across subhierarchies.
14670
14671 To receive DestroyNotify events, set the StructureNotifyMask
14672 bit in the event-mask attribute of the window or the
14673 SubstructureNotifyMask bit in the event-mask attribute of the
14674 parent window (in which case, destroying any child generates an
14675 event).
14676
14677 The structure for this event type contains:
14678
14679
14680
14681typedef struct {
14682 int type; /* DestroyNotify */
14683 unsigned long serial; /* # of last request processed by server
14684*/
14685 Bool send_event; /* true if this came from a SendEvent req
14686uest */
14687 Display *display; /* Display the event was read from */
14688 Window event;
14689 Window window;
14690} XDestroyWindowEvent;
14691
14692 The event member is set either to the destroyed window or to
14693 its parent, depending on whether StructureNotify or
14694 SubstructureNotify was selected. The window member is set to
14695 the window that is destroyed.
14696
14697GravityNotify Events
14698
14699 The X server can report GravityNotify events to clients wanting
14700 information about when a window is moved because of a change in
14701 the size of its parent. The X server generates this event
14702 whenever a client application actually moves a child window as
14703 a result of resizing its parent by calling XConfigureWindow,
14704 XMoveResizeWindow, or XResizeWindow.
14705
14706 To receive GravityNotify events, set the StructureNotifyMask
14707 bit in the event-mask attribute of the window or the
14708 SubstructureNotifyMask bit in the event-mask attribute of the
14709 parent window (in which case, any child that is moved because
14710 its parent has been resized generates an event).
14711
14712 The structure for this event type contains:
14713
14714
14715
14716typedef struct {
14717 int type; /* GravityNotify */
14718 unsigned long serial; /* # of last request processed by server
14719*/
14720 Bool send_event; /* true if this came from a SendEvent req
14721uest */
14722 Display *display; /* Display the event was read from */
14723 Window event;
14724 Window window;
14725 int x, y;
14726} XGravityEvent;
14727
14728 The event member is set either to the window that was moved or
14729 to its parent, depending on whether StructureNotify or
14730 SubstructureNotify was selected. The window member is set to
14731 the child window that was moved. The x and y members are set to
14732 the coordinates relative to the new parent window's origin and
14733 indicate the position of the upper-left outside corner of the
14734 window.
14735
14736MapNotify Events
14737
14738 The X server can report MapNotify events to clients wanting
14739 information about which windows are mapped. The X server
14740 generates this event type whenever a client application changes
14741 the window's state from unmapped to mapped by calling
14742 XMapWindow, XMapRaised, XMapSubwindows, XReparentWindow, or as
14743 a result of save-set processing.
14744
14745 To receive MapNotify events, set the StructureNotifyMask bit in
14746 the event-mask attribute of the window or the
14747 SubstructureNotifyMask bit in the event-mask attribute of the
14748 parent window (in which case, mapping any child generates an
14749 event).
14750
14751 The structure for this event type contains:
14752
14753
14754
14755typedef struct {
14756 int type; /* MapNotify */
14757 unsigned long serial; /* # of last request processed
14758 by server */
14759 Bool send_event; /* true if this came from a Se
14760ndEvent request */
14761 Display *display; /* Display the event was read
14762from */
14763 Window event;
14764 Window window;
14765 Bool override_redirect; /* boolean, is override set...
14766 */
14767} XMapEvent;
14768
14769 The event member is set either to the window that was mapped or
14770 to its parent, depending on whether StructureNotify or
14771 SubstructureNotify was selected. The window member is set to
14772 the window that was mapped. The override_redirect member is set
14773 to the override-redirect attribute of the window. Window
14774 manager clients normally should ignore this window if the
14775 override-redirect attribute is True, because these events
14776 usually are generated from pop-ups, which override structure
14777 control.
14778
14779MappingNotify Events
14780
14781 The X server reports MappingNotify events to all clients. There
14782 is no mechanism to express disinterest in this event. The X
14783 server generates this event type whenever a client application
14784 successfully calls:
14785 * XSetModifierMapping to indicate which KeyCodes are to be
14786 used as modifiers
14787 * XChangeKeyboardMapping to change the keyboard mapping
14788 * XSetPointerMapping to set the pointer mapping
14789
14790 The structure for this event type contains:
14791
14792
14793
14794typedef struct {
14795 int type; /* MappingNotify */
14796 unsigned long serial; /* # of last request processed by ser
14797ver */
14798 Bool send_event; /* true if this came from a SendEvent
14799 request */
14800 Display *display; /* Display the event was read from */
14801 Window window; /* unused */
14802 int request; /* one of MappingModifier, MappingKey
14803board,
14804 MappingPointer */
14805 int first_keycode; /* first keycode */
14806 int count; /* defines range of change w. first_k
14807eycode*/
14808} XMappingEvent;
14809
14810 The request member is set to indicate the kind of mapping
14811 change that occurred and can be MappingModifier,
14812 MappingKeyboard, or MappingPointer. If it is MappingModifier,
14813 the modifier mapping was changed. If it is MappingKeyboard, the
14814 keyboard mapping was changed. If it is MappingPointer, the
14815 pointer button mapping was changed. The first_keycode and count
14816 members are set only if the request member was set to
14817 MappingKeyboard. The number in first_keycode represents the
14818 first number in the range of the altered mapping, and count
14819 represents the number of keycodes altered.
14820
14821 To update the client application's knowledge of the keyboard,
14822 you should call XRefreshKeyboardMapping.
14823
14824ReparentNotify Events
14825
14826 The X server can report ReparentNotify events to clients
14827 wanting information about changing a window's parent. The X
14828 server generates this event whenever a client application calls
14829 XReparentWindow and the window is actually reparented.
14830
14831 To receive ReparentNotify events, set the StructureNotifyMask
14832 bit in the event-mask attribute of the window or the
14833 SubstructureNotifyMask bit in the event-mask attribute of
14834 either the old or the new parent window (in which case,
14835 reparenting any child generates an event).
14836
14837 The structure for this event type contains:
14838
14839
14840
14841typedef struct {
14842 int type; /* ReparentNotify */
14843 unsigned long serial; /* # of last request processed by server
14844*/
14845 Bool send_event; /* true if this came from a SendEvent req
14846uest */
14847 Display *display; /* Display the event was read from */
14848 Window event;
14849 Window window;
14850 Window parent;
14851 int x, y;
14852 Bool override_redirect;
14853} XReparentEvent;
14854
14855 The event member is set either to the reparented window or to
14856 the old or the new parent, depending on whether StructureNotify
14857 or SubstructureNotify was selected. The window member is set to
14858 the window that was reparented. The parent member is set to the
14859 new parent window. The x and y members are set to the
14860 reparented window's coordinates relative to the new parent
14861 window's origin and define the upper-left outer corner of the
14862 reparented window. The override_redirect member is set to the
14863 override-redirect attribute of the window specified by the
14864 window member. Window manager clients normally should ignore
14865 this window if the override_redirect member is True.
14866
14867UnmapNotify Events
14868
14869 The X server can report UnmapNotify events to clients wanting
14870 information about which windows are unmapped. The X server
14871 generates this event type whenever a client application changes
14872 the window's state from mapped to unmapped.
14873
14874 To receive UnmapNotify events, set the StructureNotifyMask bit
14875 in the event-mask attribute of the window or the
14876 SubstructureNotifyMask bit in the event-mask attribute of the
14877 parent window (in which case, unmapping any child window
14878 generates an event).
14879
14880 The structure for this event type contains:
14881
14882
14883
14884typedef struct {
14885 int type; /* UnmapNotify */
14886 unsigned long serial; /* # of last request processed by server
14887*/
14888 Bool send_event; /* true if this came from a SendEvent req
14889uest */
14890 Display *display; /* Display the event was read from */
14891 Window event;
14892 Window window;
14893 Bool from_configure;
14894} XUnmapEvent;
14895
14896 The event member is set either to the unmapped window or to its
14897 parent, depending on whether StructureNotify or
14898 SubstructureNotify was selected. This is the window used by the
14899 X server to report the event. The window member is set to the
14900 window that was unmapped. The from_configure member is set to
14901 True if the event was generated as a result of a resizing of
14902 the window's parent when the window itself had a win_gravity of
14903 UnmapGravity.
14904
14905VisibilityNotify Events
14906
14907 The X server can report VisibilityNotify events to clients
14908 wanting any change in the visibility of the specified window. A
14909 region of a window is visible if someone looking at the screen
14910 can actually see it. The X server generates this event whenever
14911 the visibility changes state. However, this event is never
14912 generated for windows whose class is InputOnly.
14913
14914 All VisibilityNotify events caused by a hierarchy change are
14915 generated after any hierarchy event (UnmapNotify, MapNotify,
14916 ConfigureNotify, GravityNotify, CirculateNotify) caused by that
14917 change. Any VisibilityNotify event on a given window is
14918 generated before any Expose events on that window, but it is
14919 not required that all VisibilityNotify events on all windows be
14920 generated before all Expose events on all windows. The X
14921 protocol does not constrain the ordering of VisibilityNotify
14922 events with respect to FocusOut, EnterNotify, and LeaveNotify
14923 events.
14924
14925 To receive VisibilityNotify events, set the
14926 VisibilityChangeMask bit in the event-mask attribute of the
14927 window.
14928
14929 The structure for this event type contains:
14930
14931
14932
14933typedef struct {
14934 int type; /* VisibilityNotify */
14935 unsigned long serial; /* # of last request processed by server
14936*/
14937 Bool send_event; /* true if this came from a SendEvent req
14938uest */
14939 Display *display; /* Display the event was read from */
14940 Window window;
14941 int state;
14942} XVisibilityEvent;
14943
14944 The window member is set to the window whose visibility state
14945 changes. The state member is set to the state of the window's
14946 visibility and can be VisibilityUnobscured,
14947 VisibilityPartiallyObscured, or VisibilityFullyObscured. The X
14948 server ignores all of a window's subwindows when determining
14949 the visibility state of the window and processes
14950 VisibilityNotify events according to the following:
14951 * When the window changes state from partially obscured,
14952 fully obscured, or not viewable to viewable and completely
14953 unobscured, the X server generates the event with the state
14954 member of the XVisibilityEvent structure set to
14955 VisibilityUnobscured.
14956 * When the window changes state from viewable and completely
14957 unobscured or not viewable to viewable and partially
14958 obscured, the X server generates the event with the state
14959 member of the XVisibilityEvent structure set to
14960 VisibilityPartiallyObscured.
14961 * When the window changes state from viewable and completely
14962 unobscured, viewable and partially obscured, or not
14963 viewable to viewable and fully obscured, the X server
14964 generates the event with the state member of the
14965 XVisibilityEvent structure set to VisibilityFullyObscured.
14966
14967Structure Control Events
14968
14969 This section discusses:
14970 * CirculateRequest events
14971 * ConfigureRequest events
14972 * MapRequest events
14973 * ResizeRequest events
14974
14975CirculateRequest Events
14976
14977 The X server can report CirculateRequest events to clients
14978 wanting information about when another client initiates a
14979 circulate window request on a specified window. The X server
14980 generates this event type whenever a client initiates a
14981 circulate window request on a window and a subwindow actually
14982 needs to be restacked. The client initiates a circulate window
14983 request on the window by calling XCirculateSubwindows,
14984 XCirculateSubwindowsUp, or XCirculateSubwindowsDown.
14985
14986 To receive CirculateRequest events, set the
14987 SubstructureRedirectMask in the event-mask attribute of the
14988 window. Then, in the future, the circulate window request for
14989 the specified window is not executed, and thus, any subwindow's
14990 position in the stack is not changed. For example, suppose a
14991 client application calls XCirculateSubwindowsUp to raise a
14992 subwindow to the top of the stack. If you had selected
14993 SubstructureRedirectMask on the window, the X server reports to
14994 you a CirculateRequest event and does not raise the subwindow
14995 to the top of the stack.
14996
14997 The structure for this event type contains:
14998
14999
15000
15001typedef struct {
15002 int type; /* CirculateRequest */
15003 unsigned long serial; /* # of last request processed by server
15004*/
15005 Bool send_event; /* true if this came from a SendEvent req
15006uest */
15007 Display *display; /* Display the event was read from */
15008 Window parent;
15009 Window window;
15010 int place; /* PlaceOnTop, PlaceOnBottom */
15011} XCirculateRequestEvent;
15012
15013 The parent member is set to the parent window. The window
15014 member is set to the subwindow to be restacked. The place
15015 member is set to what the new position in the stacking order
15016 should be and is either PlaceOnTop or PlaceOnBottom. If it is
15017 PlaceOnTop, the subwindow should be on top of all siblings. If
15018 it is PlaceOnBottom, the subwindow should be below all
15019 siblings.
15020
15021ConfigureRequest Events
15022
15023 The X server can report ConfigureRequest events to clients
15024 wanting information about when a different client initiates a
15025 configure window request on any child of a specified window.
15026 The configure window request attempts to reconfigure a window's
15027 size, position, border, and stacking order. The X server
15028 generates this event whenever a different client initiates a
15029 configure window request on a window by calling
15030 XConfigureWindow, XLowerWindow, XRaiseWindow, XMapRaised,
15031 XMoveResizeWindow, XMoveWindow, XResizeWindow, XRestackWindows,
15032 or XSetWindowBorderWidth.
15033
15034 To receive ConfigureRequest events, set the
15035 SubstructureRedirectMask bit in the event-mask attribute of the
15036 window. ConfigureRequest events are generated when a
15037 ConfigureWindow protocol request is issued on a child window by
15038 another client. For example, suppose a client application calls
15039 XLowerWindow to lower a window. If you had selected
15040 SubstructureRedirectMask on the parent window and if the
15041 override-redirect attribute of the window is set to False, the
15042 X server reports a ConfigureRequest event to you and does not
15043 lower the specified window.
15044
15045 The structure for this event type contains:
15046
15047
15048
15049typedef struct {
15050 int type; /* ConfigureRequest */
15051 unsigned long serial; /* # of last request processed by serve
15052r */
15053 Bool send_event; /* true if this came from a SendEvent r
15054equest */
15055 Display *display; /* Display the event was read from */
15056 Window parent;
15057 Window window;
15058 int x, y;
15059 int width, height;
15060 int border_width;
15061 Window above;
15062 int detail; /* Above, Below, TopIf, BottomIf, Oppos
15063ite */
15064 unsigned long value_mask;
15065} XConfigureRequestEvent;
15066
15067 The parent member is set to the parent window. The window
15068 member is set to the window whose size, position, border width,
15069 and/or stacking order is to be reconfigured. The value_mask
15070 member indicates which components were specified in the
15071 ConfigureWindow protocol request. The corresponding values are
15072 reported as given in the request. The remaining values are
15073 filled in from the current geometry of the window, except in
15074 the case of above (sibling) and detail (stack-mode), which are
15075 reported as None and Above, respectively, if they are not given
15076 in the request.
15077
15078MapRequest Events
15079
15080 The X server can report MapRequest events to clients wanting
15081 information about a different client's desire to map windows. A
15082 window is considered mapped when a map window request
15083 completes. The X server generates this event whenever a
15084 different client initiates a map window request on an unmapped
15085 window whose override_redirect member is set to False. Clients
15086 initiate map window requests by calling XMapWindow, XMapRaised,
15087 or XMapSubwindows.
15088
15089 To receive MapRequest events, set the SubstructureRedirectMask
15090 bit in the event-mask attribute of the window. This means
15091 another client's attempts to map a child window by calling one
15092 of the map window request functions is intercepted, and you are
15093 sent a MapRequest instead. For example, suppose a client
15094 application calls XMapWindow to map a window. If you (usually a
15095 window manager) had selected SubstructureRedirectMask on the
15096 parent window and if the override-redirect attribute of the
15097 window is set to False, the X server reports a MapRequest event
15098 to you and does not map the specified window. Thus, this event
15099 gives your window manager client the ability to control the
15100 placement of subwindows.
15101
15102 The structure for this event type contains:
15103
15104
15105
15106typedef struct {
15107 int type; /* MapRequest */
15108 unsigned long serial; /* # of last request processed by server
15109*/
15110 Bool send_event; /* true if this came from a SendEvent req
15111uest */
15112 Display *display; /* Display the event was read from */
15113 Window parent;
15114 Window window;
15115} XMapRequestEvent;
15116
15117 The parent member is set to the parent window. The window
15118 member is set to the window to be mapped.
15119
15120ResizeRequest Events
15121
15122 The X server can report ResizeRequest events to clients wanting
15123 information about another client's attempts to change the size
15124 of a window. The X server generates this event whenever some
15125 other client attempts to change the size of the specified
15126 window by calling XConfigureWindow, XResizeWindow, or
15127 XMoveResizeWindow.
15128
15129 To receive ResizeRequest events, set the ResizeRedirect bit in
15130 the event-mask attribute of the window. Any attempts to change
15131 the size by other clients are then redirected.
15132
15133 The structure for this event type contains:
15134
15135
15136
15137typedef struct {
15138 int type; /* ResizeRequest */
15139 unsigned long serial; /* # of last request processed by server
15140 */
15141 Bool send_event; /* true if this came from a SendEvent re
15142quest */
15143 Display *display; /* Display the event was read from */
15144 Window window;
15145 int width, height;
15146} XResizeRequestEvent;
15147
15148 The window member is set to the window whose size another
15149 client attempted to change. The width and height members are
15150 set to the inside size of the window, excluding the border.
15151
15152Colormap State Change Events
15153
15154 The X server can report ColormapNotify events to clients
15155 wanting information about when the colormap changes and when a
15156 colormap is installed or uninstalled. The X server generates
15157 this event type whenever a client application:
15158 * Changes the colormap member of the XSetWindowAttributes
15159 structure by calling XChangeWindowAttributes,
15160 XFreeColormap, or XSetWindowColormap
15161 * Installs or uninstalls the colormap by calling
15162 XInstallColormap or XUninstallColormap
15163
15164 To receive ColormapNotify events, set the ColormapChangeMask
15165 bit in the event-mask attribute of the window.
15166
15167 The structure for this event type contains:
15168
15169
15170
15171typedef struct {
15172 int type; /* ColormapNotify */
15173 unsigned long serial; /* # of last request processed by server
15174*/
15175 Bool send_event; /* true if this came from a SendEvent req
15176uest */
15177 Display *display; /* Display the event was read from */
15178 Window window;
15179 Colormap colormap; /* colormap or None */
15180 Bool new;
15181 int state; /* ColormapInstalled, ColormapUninstalled
15182 */
15183} XColormapEvent;
15184
15185 The window member is set to the window whose associated
15186 colormap is changed, installed, or uninstalled. For a colormap
15187 that is changed, installed, or uninstalled, the colormap member
15188 is set to the colormap associated with the window. For a
15189 colormap that is changed by a call to XFreeColormap, the
15190 colormap member is set to None. The new member is set to
15191 indicate whether the colormap for the specified window was
15192 changed or installed or uninstalled and can be True or False.
15193 If it is True, the colormap was changed. If it is False, the
15194 colormap was installed or uninstalled. The state member is
15195 always set to indicate whether the colormap is installed or
15196 uninstalled and can be ColormapInstalled or
15197 ColormapUninstalled.
15198
15199Client Communication Events
15200
15201 This section discusses:
15202 * ClientMessage events
15203 * PropertyNotify events
15204 * SelectionClear events
15205 * SelectionNotify events
15206 * SelectionRequest events
15207
15208ClientMessage Events
15209
15210 The X server generates ClientMessage events only when a client
15211 calls the function XSendEvent.
15212
15213 The structure for this event type contains:
15214
15215
15216
15217typedef struct {
15218 int type; /* ClientMessage */
15219 unsigned long serial; /* # of last request processed by ser
15220ver */
15221 Bool send_event; /* true if this came from a SendEvent
15222 request */
15223 Display *display; /* Display the event was read from */
15224 Window window;
15225 Atom message_type;
15226 int format;
15227 union {
15228 char b[20];
15229 short s[10];
15230 long l[5];
15231 } data;
15232} XClientMessageEvent;
15233
15234 The message_type member is set to an atom that indicates how
15235 the data should be interpreted by the receiving client. The
15236 format member is set to 8, 16, or 32 and specifies whether the
15237 data should be viewed as a list of bytes, shorts, or longs. The
15238 data member is a union that contains the members b, s, and l.
15239 The b, s, and l members represent data of twenty 8-bit values,
15240 ten 16-bit values, and five 32-bit values. Particular message
15241 types might not make use of all these values. The X server
15242 places no interpretation on the values in the window,
15243 message_type, or data members.
15244
15245PropertyNotify Events
15246
15247 The X server can report PropertyNotify events to clients
15248 wanting information about property changes for a specified
15249 window.
15250
15251 To receive PropertyNotify events, set the PropertyChangeMask
15252 bit in the event-mask attribute of the window.
15253
15254 The structure for this event type contains:
15255
15256
15257
15258typedef struct {
15259 int type; /* PropertyNotify */
15260 unsigned long serial; /* # of last request processed by server
15261*/
15262 Bool send_event; /* true if this came from a SendEvent req
15263uest */
15264 Display *display; /* Display the event was read from */
15265 Window window;
15266 Atom atom;
15267 Time time;
15268 int state; /* PropertyNewValue or PropertyDelete */
15269} XPropertyEvent;
15270
15271 The window member is set to the window whose associated
15272 property was changed. The atom member is set to the property's
15273 atom and indicates which property was changed or desired. The
15274 time member is set to the server time when the property was
15275 changed. The state member is set to indicate whether the
15276 property was changed to a new value or deleted and can be
15277 PropertyNewValue or PropertyDelete. The state member is set to
15278 PropertyNewValue when a property of the window is changed using
15279 XChangeProperty or XRotateWindowProperties (even when adding
15280 zero-length data using XChangeProperty) and when replacing all
15281 or part of a property with identical data using XChangeProperty
15282 or XRotateWindowProperties. The state member is set to
15283 PropertyDelete when a property of the window is deleted using
15284 XDeleteProperty or, if the delete argument is True,
15285 XGetWindowProperty.
15286
15287SelectionClear Events
15288
15289 The X server reports SelectionClear events to the client losing
15290 ownership of a selection. The X server generates this event
15291 type when another client asserts ownership of the selection by
15292 calling XSetSelectionOwner.
15293
15294 The structure for this event type contains:
15295
15296
15297
15298typedef struct {
15299 int type; /* SelectionClear */
15300 unsigned long serial; /* # of last request processed by server
15301*/
15302 Bool send_event; /* true if this came from a SendEvent req
15303uest */
15304 Display *display; /* Display the event was read from */
15305 Window window;
15306 Atom selection;
15307 Time time;
15308} XSelectionClearEvent;
15309
15310 The selection member is set to the selection atom. The time
15311 member is set to the last change time recorded for the
15312 selection. The window member is the window that was specified
15313 by the current owner (the owner losing the selection) in its
15314 XSetSelectionOwner call.
15315
15316SelectionRequest Events
15317
15318 The X server reports SelectionRequest events to the owner of a
15319 selection. The X server generates this event whenever a client
15320 requests a selection conversion by calling XConvertSelection
15321 for the owned selection.
15322
15323 The structure for this event type contains:
15324
15325
15326
15327typedef struct {
15328 int type; /* SelectionRequest */
15329 unsigned long serial; /* # of last request processed by server
15330*/
15331 Bool send_event; /* true if this came from a SendEvent req
15332uest */
15333 Display *display; /* Display the event was read from */
15334 Window owner;
15335 Window requestor;
15336 Atom selection;
15337 Atom target;
15338 Atom property;
15339 Time time;
15340} XSelectionRequestEvent;
15341
15342 The owner member is set to the window that was specified by the
15343 current owner in its XSetSelectionOwner call. The requestor
15344 member is set to the window requesting the selection. The
15345 selection member is set to the atom that names the selection.
15346 For example, PRIMARY is used to indicate the primary selection.
15347 The target member is set to the atom that indicates the type
15348 the selection is desired in. The property member can be a
15349 property name or None. The time member is set to the timestamp
15350 or CurrentTime value from the ConvertSelection request.
15351
15352 The owner should convert the selection based on the specified
15353 target type and send a SelectionNotify event back to the
15354 requestor. A complete specification for using selections is
15355 given in the X Consortium standard Inter-Client Communication
15356 Conventions Manual.
15357
15358SelectionNotify Events
15359
15360 This event is generated by the X server in response to a
15361 ConvertSelection protocol request when there is no owner for
15362 the selection. When there is an owner, it should be generated
15363 by the owner of the selection by using XSendEvent. The owner of
15364 a selection should send this event to a requestor when a
15365 selection has been converted and stored as a property or when a
15366 selection conversion could not be performed (which is indicated
15367 by setting the property member to None).
15368
15369 If None is specified as the property in the ConvertSelection
15370 protocol request, the owner should choose a property name,
15371 store the result as that property on the requestor window, and
15372 then send a SelectionNotify giving that actual property name.
15373
15374 The structure for this event type contains:
15375
15376
15377
15378typedef struct {
15379 int type; /* SelectionNotify */
15380 unsigned long serial; /* # of last request processed by server
15381*/
15382 Bool send_event; /* true if this came from a SendEvent req
15383uest */
15384 Display *display; /* Display the event was read from */
15385 Window requestor;
15386 Atom selection;
15387 Atom target;
15388 Atom property; /* atom or None */
15389 Time time;
15390} XSelectionEvent;
15391
15392 The requestor member is set to the window associated with the
15393 requestor of the selection. The selection member is set to the
15394 atom that indicates the selection. For example, PRIMARY is used
15395 for the primary selection. The target member is set to the atom
15396 that indicates the converted type. For example, PIXMAP is used
15397 for a pixmap. The property member is set to the atom that
15398 indicates which property the result was stored on. If the
15399 conversion failed, the property member is set to None. The time
15400 member is set to the time the conversion took place and can be
15401 a timestamp or CurrentTime.
15402
15403Chapter 11. Event Handling Functions
15404
15405 Table of Contents
15406
15407 Selecting Events
15408 Handling the Output Buffer
15409 Event Queue Management
15410 Manipulating the Event Queue
15411
15412 Returning the Next Event
15413 Selecting Events Using a Predicate Procedure
15414 Selecting Events Using a Window or Event Mask
15415
15416 Putting an Event Back into the Queue
15417 Sending Events to Other Applications
15418 Getting Pointer Motion History
15419 Handling Protocol Errors
15420
15421 Enabling or Disabling Synchronization
15422 Using the Default Error Handlers
15423
15424 This chapter discusses the Xlib functions you can use to:
15425 * Select events
15426 * Handle the output buffer and the event queue
15427 * Select events from the event queue
15428 * Send and get events
15429 * Handle protocol errors
15430
15431Note
15432
15433 Some toolkits use their own event-handling functions and do not
15434 allow you to interchange these event-handling functions with
15435 those in Xlib. For further information, see the documentation
15436 supplied with the toolkit.
15437
15438 Most applications simply are event loops: they wait for an
15439 event, decide what to do with it, execute some amount of code
15440 that results in changes to the display, and then wait for the
15441 next event.
15442
15443Selecting Events
15444
15445 There are two ways to select the events you want reported to
15446 your client application. One way is to set the event_mask
15447 member of the XSetWindowAttributes structure when you call
15448 XCreateWindow and XChangeWindowAttributes. Another way is to
15449 use XSelectInput.
15450
15451 XSelectInput(Display *display, Window w, long event_mask);
15452
15453 display
15454
15455 Specifies the connection to the X server.
15456
15457 w
15458
15459 Specifies the window whose events you are interested in.
15460
15461 event_mask
15462
15463 Specifies the event mask.
15464
15465 The XSelectInput function requests that the X server report the
15466 events associated with the specified event mask. Initially, X
15467 will not report any of these events. Events are reported
15468 relative to a window. If a window is not interested in a device
15469 event, it usually propagates to the closest ancestor that is
15470 interested, unless the do_not_propagate mask prohibits it.
15471
15472 Setting the event-mask attribute of a window overrides any
15473 previous call for the same window but not for other clients.
15474 Multiple clients can select for the same events on the same
15475 window with the following restrictions:
15476 * Multiple clients can select events on the same window
15477 because their event masks are disjoint. When the X server
15478 generates an event, it reports it to all interested
15479 clients.
15480 * Only one client at a time can select CirculateRequest,
15481 ConfigureRequest, or MapRequest events, which are
15482 associated with the event mask SubstructureRedirectMask.
15483 * Only one client at a time can select a ResizeRequest event,
15484 which is associated with the event mask ResizeRedirectMask.
15485 * Only one client at a time can select a ButtonPress event,
15486 which is associated with the event mask ButtonPressMask.
15487
15488 The server reports the event to all interested clients.
15489
15490 XSelectInput can generate a BadWindow error.
15491
15492Handling the Output Buffer
15493
15494 The output buffer is an area used by Xlib to store requests.
15495 The functions described in this section flush the output buffer
15496 if the function would block or not return an event. That is,
15497 all requests residing in the output buffer that have not yet
15498 been sent are transmitted to the X server. These functions
15499 differ in the additional tasks they might perform.
15500
15501 To flush the output buffer, use XFlush.
15502
15503 XFlush(Display *display);
15504
15505 display
15506
15507 Specifies the connection to the X server.
15508
15509 The XFlush function flushes the output buffer. Most client
15510 applications need not use this function because the output
15511 buffer is automatically flushed as needed by calls to XPending,
15512 XNextEvent, and XWindowEvent. Events generated by the server
15513 may be enqueued into the library's event queue.
15514
15515 To flush the output buffer and then wait until all requests
15516 have been processed, use XSync.
15517
15518 XSync(Display *display, Bool discard);
15519
15520 display
15521
15522 Specifies the connection to the X server.
15523
15524 discard
15525
15526 Specifies a Boolean value that indicates whether XSync discards
15527 all events on the event queue.
15528
15529 The XSync function flushes the output buffer and then waits
15530 until all requests have been received and processed by the X
15531 server. Any errors generated must be handled by the error
15532 handler. For each protocol error received by Xlib, XSync calls
15533 the client application's error handling routine (see section
15534 11.8.2). Any events generated by the server are enqueued into
15535 the library's event queue.
15536
15537 Finally, if you passed False, XSync does not discard the events
15538 in the queue. If you passed True, XSync discards all events in
15539 the queue, including those events that were on the queue before
15540 XSync was called. Client applications seldom need to call
15541 XSync.
15542
15543Event Queue Management
15544
15545 Xlib maintains an event queue. However, the operating system
15546 also may be buffering data in its network connection that is
15547 not yet read into the event queue.
15548
15549 To check the number of events in the event queue, use
15550 XEventsQueued.
15551
15552 int XEventsQueued(Display *display, int mode);
15553
15554 display
15555
15556 Specifies the connection to the X server.
15557
15558 mode
15559
15560 Specifies the mode. You can pass QueuedAlready,
15561 QueuedAfterFlush, or QueuedAfterReading.
15562
15563 If mode is QueuedAlready, XEventsQueued returns the number of
15564 events already in the event queue (and never performs a system
15565 call). If mode is QueuedAfterFlush, XEventsQueued returns the
15566 number of events already in the queue if the number is nonzero.
15567 If there are no events in the queue, XEventsQueued flushes the
15568 output buffer, attempts to read more events out of the
15569 application's connection, and returns the number read. If mode
15570 is QueuedAfterReading, XEventsQueued returns the number of
15571 events already in the queue if the number is nonzero. If there
15572 are no events in the queue, XEventsQueued attempts to read more
15573 events out of the application's connection without flushing the
15574 output buffer and returns the number read.
15575
15576 XEventsQueued always returns immediately without I/O if there
15577 are events already in the queue. XEventsQueued with mode
15578 QueuedAfterFlush is identical in behavior to XPending.
15579 XEventsQueued with mode QueuedAlready is identical to the
15580 XQLength function.
15581
15582 To return the number of events that are pending, use XPending.
15583
15584 int XPending(Display *display);
15585
15586 display
15587
15588 Specifies the connection to the X server.
15589
15590 The XPending function returns the number of events that have
15591 been received from the X server but have not been removed from
15592 the event queue. XPending is identical to XEventsQueued with
15593 the mode QueuedAfterFlush specified.
15594
15595Manipulating the Event Queue
15596
15597 Xlib provides functions that let you manipulate the event
15598 queue. This section discusses how to:
15599 * Obtain events, in order, and remove them from the queue
15600 * Peek at events in the queue without removing them
15601 * Obtain events that match the event mask or the arbitrary
15602 predicate procedures that you provide
15603
15604Returning the Next Event
15605
15606 To get the next event and remove it from the queue, use
15607 XNextEvent.
15608
15609 XNextEvent(Display *display, XEvent *event_return);
15610
15611 display
15612
15613 Specifies the connection to the X server.
15614
15615 event_return
15616
15617 Returns the next event in the queue.
15618
15619 The XNextEvent function copies the first event from the event
15620 queue into the specified XEvent structure and then removes it
15621 from the queue. If the event queue is empty, XNextEvent flushes
15622 the output buffer and blocks until an event is received.
15623
15624 To peek at the event queue, use XPeekEvent.
15625
15626 XPeekEvent(Display *display, XEvent *event_return);
15627
15628 display
15629
15630 Specifies the connection to the X server.
15631
15632 event_return
15633
15634 Returns a copy of the matched event's associated structure.
15635
15636 The XPeekEvent function returns the first event from the event
15637 queue, but it does not remove the event from the queue. If the
15638 queue is empty, XPeekEvent flushes the output buffer and blocks
15639 until an event is received. It then copies the event into the
15640 client-supplied XEvent structure without removing it from the
15641 event queue.
15642
15643Selecting Events Using a Predicate Procedure
15644
15645 Each of the functions discussed in this section requires you to
15646 pass a predicate procedure that determines if an event matches
15647 what you want. Your predicate procedure must decide if the
15648 event is useful without calling any Xlib functions. If the
15649 predicate directly or indirectly causes the state of the event
15650 queue to change, the result is not defined. If Xlib has been
15651 initialized for threads, the predicate is called with the
15652 display locked and the result of a call by the predicate to any
15653 Xlib function that locks the display is not defined unless the
15654 caller has first called XLockDisplay.
15655
15656 The predicate procedure and its associated arguments are:
15657
15658 Bool(Display *display, XEvent *event, XPointer arg);
15659
15660 display
15661
15662 Specifies the connection to the X server.
15663
15664 event
15665
15666 Specifies the XEvent structure.
15667
15668 arg
15669
15670 Specifies the argument passed in from the XIfEvent,
15671 XCheckIfEvent, or XPeekIfEvent function.
15672
15673 The predicate procedure is called once for each event in the
15674 queue until it finds a match. After finding a match, the
15675 predicate procedure must return True. If it did not find a
15676 match, it must return False.
15677
15678 To check the event queue for a matching event and, if found,
15679 remove the event from the queue, use XIfEvent.
15680
15681 XIfEvent(Display *display, XEvent *event_return, Bool
15682 (*predicate)(), XPointer arg);
15683
15684 display
15685
15686 Specifies the connection to the X server.
15687
15688 event_return
15689
15690 Returns the matched event's associated structure.
15691
15692 predicate
15693
15694 Specifies the procedure that is to be called to determine if
15695 the next event in the queue matches what you want.
15696
15697 arg
15698
15699 Specifies the user-supplied argument that will be passed to the
15700 predicate procedure.
15701
15702 The XIfEvent function completes only when the specified
15703 predicate procedure returns True for an event, which indicates
15704 an event in the queue matches. XIfEvent flushes the output
15705 buffer if it blocks waiting for additional events. XIfEvent
15706 removes the matching event from the queue and copies the
15707 structure into the client-supplied XEvent structure.
15708
15709 To check the event queue for a matching event without blocking,
15710 use XCheckIfEvent.
15711
15712 Bool XCheckIfEvent(Display *display, XEvent *event_return, Bool
15713 (*predicate)(), XPointer arg);
15714
15715 display
15716
15717 Specifies the connection to the X server.
15718
15719 event_return
15720
15721 Returns a copy of the matched event's associated structure.
15722
15723 predicate
15724
15725 Specifies the procedure that is to be called to determine if
15726 the next event in the queue matches what you want.
15727
15728 arg
15729
15730 Specifies the user-supplied argument that will be passed to the
15731 predicate procedure.
15732
15733 When the predicate procedure finds a match, XCheckIfEvent
15734 copies the matched event into the client-supplied XEvent
15735 structure and returns True. (This event is removed from the
15736 queue.) If the predicate procedure finds no match,
15737 XCheckIfEvent returns False, and the output buffer will have
15738 been flushed. All earlier events stored in the queue are not
15739 discarded.
15740
15741 To check the event queue for a matching event without removing
15742 the event from the queue, use XPeekIfEvent.
15743
15744 XPeekIfEvent(Display *display, XEvent *event_return, Bool
15745 (*predicate)(), XPointer arg);
15746
15747 display
15748
15749 Specifies the connection to the X server.
15750
15751 event_return
15752
15753 Returns a copy of the matched event's associated structure.
15754
15755 predicate
15756
15757 Specifies the procedure that is to be called to determine if
15758 the next event in the queue matches what you want.
15759
15760 arg
15761
15762 Specifies the user-supplied argument that will be passed to the
15763 predicate procedure.
15764
15765 The XPeekIfEvent function returns only when the specified
15766 predicate procedure returns True for an event. After the
15767 predicate procedure finds a match, XPeekIfEvent copies the
15768 matched event into the client-supplied XEvent structure without
15769 removing the event from the queue. XPeekIfEvent flushes the
15770 output buffer if it blocks waiting for additional events.
15771
15772Selecting Events Using a Window or Event Mask
15773
15774 The functions discussed in this section let you select events
15775 by window or event types, allowing you to process events out of
15776 order.
15777
15778 To remove the next event that matches both a window and an
15779 event mask, use XWindowEvent.
15780
15781 XWindowEvent(Display *display, Window w, long event_mask,
15782 XEvent *event_return);
15783
15784 display
15785
15786 Specifies the connection to the X server.
15787
15788 w
15789
15790 Specifies the window whose events you are interested in.
15791
15792 event_mask
15793
15794 Specifies the event mask.
15795
15796 event_return
15797
15798 Returns the matched event's associated structure.
15799
15800 The XWindowEvent function searches the event queue for an event
15801 that matches both the specified window and event mask. When it
15802 finds a match, XWindowEvent removes that event from the queue
15803 and copies it into the specified XEvent structure. The other
15804 events stored in the queue are not discarded. If a matching
15805 event is not in the queue, XWindowEvent flushes the output
15806 buffer and blocks until one is received.
15807
15808 To remove the next event that matches both a window and an
15809 event mask (if any), use XCheckWindowEvent. This function is
15810 similar to XWindowEvent except that it never blocks and it
15811 returns a Bool indicating if the event was returned.
15812
15813 Bool XCheckWindowEvent(Display *display, Window w, long
15814 event_mask, XEvent *event_return);
15815
15816 display
15817
15818 Specifies the connection to the X server.
15819
15820 w
15821
15822 Specifies the window whose events you are interested in.
15823
15824 event_mask
15825
15826 Specifies the event mask.
15827
15828 event_return
15829
15830 Returns the matched event's associated structure.
15831
15832 The XCheckWindowEvent function searches the event queue and
15833 then the events available on the server connection for the
15834 first event that matches the specified window and event mask.
15835 If it finds a match, XCheckWindowEvent removes that event,
15836 copies it into the specified XEvent structure, and returns
15837 True. The other events stored in the queue are not discarded.
15838 If the event you requested is not available, XCheckWindowEvent
15839 returns False, and the output buffer will have been flushed.
15840
15841 To remove the next event that matches an event mask, use
15842 XMaskEvent.
15843
15844 XMaskEvent(Display *display, long event_mask, XEvent
15845 *event_return);
15846
15847 display
15848
15849 Specifies the connection to the X server.
15850
15851 event_mask
15852
15853 Specifies the event mask.
15854
15855 event_return
15856
15857 Returns the matched event's associated structure.
15858
15859 The XMaskEvent function searches the event queue for the events
15860 associated with the specified mask. When it finds a match,
15861 XMaskEvent removes that event and copies it into the specified
15862 XEvent structure. The other events stored in the queue are not
15863 discarded. If the event you requested is not in the queue,
15864 XMaskEvent flushes the output buffer and blocks until one is
15865 received.
15866
15867 To return and remove the next event that matches an event mask
15868 (if any), use XCheckMaskEvent. This function is similar to
15869 XMaskEvent except that it never blocks and it returns a Bool
15870 indicating if the event was returned.
15871
15872 Bool XCheckMaskEvent(Display *display, long event_mask, XEvent
15873 *event_return);
15874
15875 display
15876
15877 Specifies the connection to the X server.
15878
15879 event_mask
15880
15881 Specifies the event mask.
15882
15883 event_return
15884
15885 Returns the matched event's associated structure.
15886
15887 The XCheckMaskEvent function searches the event queue and then
15888 any events available on the server connection for the first
15889 event that matches the specified mask. If it finds a match,
15890 XCheckMaskEvent removes that event, copies it into the
15891 specified XEvent structure, and returns True. The other events
15892 stored in the queue are not discarded. If the event you
15893 requested is not available, XCheckMaskEvent returns False, and
15894 the output buffer will have been flushed.
15895
15896 To return and remove the next event in the queue that matches
15897 an event type, use XCheckTypedEvent.
15898
15899 Bool XCheckTypedEvent(Display *display, int event_type, XEvent
15900 *event_return);
15901
15902 display
15903
15904 Specifies the connection to the X server.
15905
15906 event_type
15907
15908 Specifies the event type to be compared.
15909
15910 event_return
15911
15912 Returns the matched event's associated structure.
15913
15914 The XCheckTypedEvent function searches the event queue and then
15915 any events available on the server connection for the first
15916 event that matches the specified type. If it finds a match,
15917 XCheckTypedEvent removes that event, copies it into the
15918 specified XEvent structure, and returns True. The other events
15919 in the queue are not discarded. If the event is not available,
15920 XCheckTypedEvent returns False, and the output buffer will have
15921 been flushed.
15922
15923 To return and remove the next event in the queue that matches
15924 an event type and a window, use XCheckTypedWindowEvent.
15925
15926 Bool XCheckTypedWindowEvent(Display *display, Window w, int
15927 event_type, XEvent *event_return);
15928
15929 display
15930
15931 Specifies the connection to the X server.
15932
15933 w
15934
15935 Specifies the window.
15936
15937 event_type
15938
15939 Specifies the event type to be compared.
15940
15941 event_return
15942
15943 Returns the matched event's associated structure.
15944
15945 The XCheckTypedWindowEvent function searches the event queue
15946 and then any events available on the server connection for the
15947 first event that matches the specified type and window. If it
15948 finds a match, XCheckTypedWindowEvent removes the event from
15949 the queue, copies it into the specified XEvent structure, and
15950 returns True. The other events in the queue are not discarded.
15951 If the event is not available, XCheckTypedWindowEvent returns
15952 False, and the output buffer will have been flushed.
15953
15954Putting an Event Back into the Queue
15955
15956 To push an event back into the event queue, use XPutBackEvent.
15957
15958 XPutBackEvent(Display *display, XEvent *event);
15959
15960 display
15961
15962 Specifies the connection to the X server.
15963
15964 event
15965
15966 Specifies the event.
15967
15968 The XPutBackEvent function pushes an event back onto the head
15969 of the display's event queue by copying the event into the
15970 queue. This can be useful if you read an event and then decide
15971 that you would rather deal with it later. There is no limit to
15972 the number of times in succession that you can call
15973 XPutBackEvent.
15974
15975Sending Events to Other Applications
15976
15977 To send an event to a specified window, use XSendEvent. This
15978 function is often used in selection processing. For example,
15979 the owner of a selection should use XSendEvent to send a
15980 SelectionNotify event to a requestor when a selection has been
15981 converted and stored as a property.
15982
15983 Status XSendEvent(Display *display, Window w, Bool propagate,
15984 long event_mask, XEvent *event_send);
15985
15986 display
15987
15988 Specifies the connection to the X server.
15989
15990 w
15991
15992 Specifies the window the event is to be sent to, or
15993 PointerWindow, or InputFocus.
15994
15995 propagate
15996
15997 Specifies a Boolean value.
15998
15999 event_mask
16000
16001 Specifies the event mask.
16002
16003 event_send
16004
16005 Specifies the event that is to be sent.
16006
16007 The XSendEvent function identifies the destination window,
16008 determines which clients should receive the specified events,
16009 and ignores any active grabs. This function requires you to
16010 pass an event mask. For a discussion of the valid event mask
16011 names, see section 10.3. This function uses the w argument to
16012 identify the destination window as follows:
16013 * If w is PointerWindow, the destination window is the window
16014 that contains the pointer.
16015 * If w is InputFocus and if the focus window contains the
16016 pointer, the destination window is the window that contains
16017 the pointer; otherwise, the destination window is the focus
16018 window.
16019
16020 To determine which clients should receive the specified events,
16021 XSendEvent uses the propagate argument as follows:
16022 * If event_mask is the empty set, the event is sent to the
16023 client that created the destination window. If that client
16024 no longer exists, no event is sent.
16025 * If propagate is False, the event is sent to every client
16026 selecting on destination any of the event types in the
16027 event_mask argument.
16028 * If propagate is True and no clients have selected on
16029 destination any of the event types in event-mask, the
16030 destination is replaced with the closest ancestor of
16031 destination for which some client has selected a type in
16032 event-mask and for which no intervening window has that
16033 type in its do-not-propagate-mask. If no such window exists
16034 or if the window is an ancestor of the focus window and
16035 InputFocus was originally specified as the destination, the
16036 event is not sent to any clients. Otherwise, the event is
16037 reported to every client selecting on the final destination
16038 any of the types specified in event_mask.
16039
16040 The event in the XEvent structure must be one of the core
16041 events or one of the events defined by an extension (or a
16042 BadValue error results) so that the X server can correctly
16043 byte-swap the contents as necessary. The contents of the event
16044 are otherwise unaltered and unchecked by the X server except to
16045 force send_event to True in the forwarded event and to set the
16046 serial number in the event correctly; therefore these fields
16047 and the display field are ignored by XSendEvent.
16048
16049 XSendEvent returns zero if the conversion to wire protocol
16050 format failed and returns nonzero otherwise.
16051
16052 XSendEvent can generate BadValue and BadWindow errors.
16053
16054Getting Pointer Motion History
16055
16056 Some X server implementations will maintain a more complete
16057 history of pointer motion than is reported by event
16058 notification. The pointer position at each pointer hardware
16059 interrupt may be stored in a buffer for later retrieval. This
16060 buffer is called the motion history buffer. For example, a few
16061 applications, such as paint programs, want to have a precise
16062 history of where the pointer traveled. However, this historical
16063 information is highly excessive for most applications.
16064
16065 To determine the approximate maximum number of elements in the
16066 motion buffer, use XDisplayMotionBufferSize.
16067
16068 unsigned long(Display *display);
16069
16070 display
16071
16072 Specifies the connection to the X server.
16073
16074 The server may retain the recent history of the pointer motion
16075 and do so to a finer granularity than is reported by
16076 MotionNotify events. The function makes this history available.
16077
16078 To get the motion history for a specified window and time, use
16079 .
16080
16081 XTimeCoord *XGetMotionEvents(Display *display, Window w, Time
16082 start, Time stop, int *nevents_return);
16083
16084 display
16085
16086 Specifies the connection to the X server.
16087
16088 w
16089
16090 Specifies the window.
16091
16092 start
16093
16094 stop
16095
16096 Specify the time interval in which the events are returned from
16097 the motion history buffer. You can pass a timestamp or
16098 CurrentTime.
16099
16100 nevents_return
16101
16102 Returns the number of events from the motion history buffer.
16103
16104 The function returns all events in the motion history buffer
16105 that fall between the specified start and stop times,
16106 inclusive, and that have coordinates that lie within the
16107 specified window (including its borders) at its present
16108 placement. If the server does not support motion history, if
16109 the start time is later than the stop time, or if the start
16110 time is in the future, no events are returned; returns NULL. If
16111 the stop time is in the future, it is equivalent to specifying
16112 CurrentTime. The return type for this function is a structure
16113 defined as follows:
16114
16115
16116
16117typedef struct {
16118 Time time;
16119 short x, y;
16120} XTimeCoord;
16121
16122 The time member is set to the time, in milliseconds. The x and
16123 y members are set to the coordinates of the pointer and are
16124 reported relative to the origin of the specified window. To
16125 free the data returned from this call, use XFree.
16126
16127 can generate a BadWindow error.
16128
16129Handling Protocol Errors
16130
16131 Xlib provides functions that you can use to enable or disable
16132 synchronization and to use the default error handlers.
16133
16134Enabling or Disabling Synchronization
16135
16136 When debugging X applications, it often is very convenient to
16137 require Xlib to behave synchronously so that errors are
16138 reported as they occur. The following function lets you disable
16139 or enable synchronous behavior. Note that graphics may occur 30
16140 or more times more slowly when synchronization is enabled. On
16141 POSIX-conformant systems, there is also a global variable
16142 _Xdebug that, if set to nonzero before starting a program under
16143 a debugger, will force synchronous library behavior.
16144
16145 After completing their work, all Xlib functions that generate
16146 protocol requests call what is known as an after function. sets
16147 which function is to be called.
16148
16149 int(Display *display, int (*procedure)());
16150
16151 display
16152
16153 Specifies the connection to the X server.
16154
16155 procedure
16156
16157 Specifies the procedure to be called.
16158
16159 The specified procedure is called with only a display pointer.
16160 returns the previous after function.
16161
16162 To enable or disable synchronization, use XSynchronize.
16163
16164 int(Display *display, Bool onoff);
16165
16166 display
16167
16168 Specifies the connection to the X server.
16169
16170 onoff
16171
16172 Specifies a Boolean value that indicates whether to enable or
16173 disable synchronization.
16174
16175 The XSynchronize function returns the previous after function.
16176 If onoff is True, XSynchronize turns on synchronous behavior.
16177 If onoff is False, XSynchronize turns off synchronous behavior.
16178
16179Using the Default Error Handlers
16180
16181 There are two default error handlers in Xlib: one to handle
16182 typically fatal conditions (for example, the connection to a
16183 display server dying because a machine crashed) and one to
16184 handle protocol errors from the X server. These error handlers
16185 can be changed to user-supplied routines if you prefer your own
16186 error handling and can be changed as often as you like. If
16187 either function is passed a NULL pointer, it will reinvoke the
16188 default handler. The action of the default handlers is to print
16189 an explanatory message and exit.
16190
16191 To set the error handler, use XSetErrorHandler.
16192
16193 int *XSetErrorHandler(int *handler);
16194
16195 handler
16196
16197 Specifies the program's supplied error handler.
16198
16199 Xlib generally calls the program's supplied error handler
16200 whenever an error is received. It is not called on BadName
16201 errors from OpenFont, LookupColor, or AllocNamedColor protocol
16202 requests or on BadFont errors from a QueryFont protocol
16203 request. These errors generally are reflected back to the
16204 program through the procedural interface. Because this
16205 condition is not assumed to be fatal, it is acceptable for your
16206 error handler to return; the returned value is ignored.
16207 However, the error handler should not call any functions
16208 (directly or indirectly) on the display that will generate
16209 protocol requests or that will look for input events. The
16210 previous error handler is returned.
16211
16212 The XErrorEvent structure contains:
16213
16214
16215
16216typedef struct {
16217 int type;
16218 Display *display; /* Display the event was read from */
16219 unsigned long serial; /* serial number of failed reque
16220st */
16221 unsigned char error_code; /* error code of failed request
16222*/
16223 unsigned char request_code; /* Major op-code of failed reque
16224st */
16225 unsigned char minor_code; /* Minor op-code of failed reque
16226st */
16227 XID resourceid; /* resource id */
16228} XErrorEvent;
16229
16230 The serial member is the number of requests, starting from one,
16231 sent over the network connection since it was opened. It is the
16232 number that was the value of NextRequest immediately before the
16233 failing call was made. The request_code member is a protocol
16234 request of the procedure that failed, as defined in
16235 <X11/Xproto.h>. The following error codes can be returned by
16236 the functions described in this chapter:
16237 Error Code Description
16238 BadAccess
16239
16240 A client attempts to grab a key/button combination already
16241 grabbed by another client.
16242
16243 A client attempts to free a colormap entry that it had not
16244 already allocated or to free an entry in a colormap that was
16245 created with all entries writable.
16246
16247 A client attempts to store into a read-only or unallocated
16248 colormap entry.
16249
16250 A client attempts to modify the access control list from other
16251 than the local (or otherwise authorized) host.
16252
16253 A client attempts to select an event type that another client
16254 has already selected.
16255 BadAlloc The server fails to allocate the requested resource.
16256 Note that the explicit listing of BadAlloc errors in requests
16257 only covers allocation errors at a very coarse level and is not
16258 intended to (nor can it in practice hope to) cover all cases of
16259 a server running out of allocation space in the middle of
16260 service. The semantics when a server runs out of allocation
16261 space are left unspecified, but a server may generate a
16262 BadAlloc error on any request for this reason, and clients
16263 should be prepared to receive such errors and handle or discard
16264 them.
16265 BadAtom A value for an atom argument does not name a defined
16266 atom.
16267 BadColor A value for a colormap argument does not name a
16268 defined colormap.
16269 BadCursor A value for a cursor argument does not name a defined
16270 cursor.
16271 BadDrawable A value for a drawable argument does not name a
16272 defined window or pixmap.
16273 BadFont A value for a font argument does not name a defined
16274 font (or, in some cases, GContext).
16275 BadGC A value for a GContext argument does not name a defined
16276 GContext.
16277 BadIDChoice The value chosen for a resource identifier either
16278 is not included in the range assigned to the client or is
16279 already in use. Under normal circumstances, this cannot occur
16280 and should be considered a server or Xlib error.
16281 BadImplementation The server does not implement some aspect of
16282 the request. A server that generates this error for a core
16283 request is deficient. As such, this error is not listed for any
16284 of the requests, but clients should be prepared to receive such
16285 errors and handle or discard them.
16286 BadLength
16287
16288 The length of a request is shorter or longer than that required
16289 to contain the arguments. This is an internal Xlib or server
16290 error.
16291
16292 The length of a request exceeds the maximum length accepted by
16293 the server.
16294 BadMatch
16295
16296 In a graphics request, the root and depth of the graphics
16297 context do not match those of the drawable.
16298
16299 An InputOnly window is used as a drawable.
16300
16301 Some argument or pair of arguments has the correct type and
16302 range, but it fails to match in some other way required by the
16303 request.
16304
16305 An InputOnly window lacks this attribute.
16306 BadName A font or color of the specified name does not exist.
16307 BadPixmap A value for a pixmap argument does not name a defined
16308 pixmap.
16309 BadRequest The major or minor opcode does not specify a valid
16310 request. This usually is an Xlib or server error.
16311 BadValue Some numeric value falls outside of the range of
16312 values accepted by the request. Unless a specific range is
16313 specified for an argument, the full range defined by the
16314 argument's type is accepted. Any argument defined as a set of
16315 alternatives typically can generate this error (due to the
16316 encoding).
16317 BadWindow A value for a window argument does not name a defined
16318 window.
16319
16320Note
16321
16322 The BadAtom, BadColor, BadCursor, BadDrawable, BadFont, BadGC,
16323 BadPixmap, and BadWindow errors are also used when the argument
16324 type is extended by a set of fixed alternatives.
16325
16326 To obtain textual descriptions of the specified error code, use
16327 XGetErrorText.
16328
16329 XGetErrorText(Display *display, int code, char *buffer_return,
16330 int length);
16331
16332 display
16333
16334 Specifies the connection to the X server.
16335
16336 code
16337
16338 Specifies the error code for which you want to obtain a
16339 description.
16340
16341 buffer_return
16342
16343 Returns the error description.
16344
16345 length
16346
16347 Specifies the size of the buffer.
16348
16349 The XGetErrorText function copies a null-terminated string
16350 describing the specified error code into the specified buffer.
16351 The returned text is in the encoding of the current locale. It
16352 is recommended that you use this function to obtain an error
16353 description because extensions to Xlib may define their own
16354 error codes and error strings.
16355
16356 To obtain error messages from the error database, use
16357 XGetErrorDatabaseText.
16358
16359 XGetErrorDatabaseText(Display *display, char *name, char
16360 *message, char *default_string, char *buffer_return, int
16361 length);
16362
16363 display
16364
16365 Specifies the connection to the X server.
16366
16367 name
16368
16369 Specifies the name of the application.
16370
16371 message
16372
16373 Specifies the type of the error message.
16374
16375 default_string
16376
16377 Specifies the default error message if none is found in the
16378 database.
16379
16380 buffer_return
16381
16382 Returns the error description.
16383
16384 length
16385
16386 Specifies the size of the buffer.
16387
16388 The XGetErrorDatabaseText function returns a null-terminated
16389 message (or the default message) from the error message
16390 database. Xlib uses this function internally to look up its
16391 error messages. The text in the default_string argument is
16392 assumed to be in the encoding of the current locale, and the
16393 text stored in the buffer_return argument is in the encoding of
16394 the current locale.
16395
16396 The name argument should generally be the name of your
16397 application. The message argument should indicate which type of
16398 error message you want. If the name and message are not in the
16399 Host Portable Character Encoding, the result is
16400 implementation-dependent. Xlib uses three predefined
16401 ``application names'' to report errors. In these names,
16402 uppercase and lowercase matter.
16403
16404 XProtoError
16405
16406 The protocol error number is used as a string for the message
16407 argument.
16408
16409 XlibMessage
16410
16411 These are the message strings that are used internally by the
16412 library.
16413
16414 XRequest
16415
16416 For a core protocol request, the major request protocol number
16417 is used for the message argument. For an extension request, the
16418 extension name (as given by InitExtension) followed by a period
16419 (.) and the minor request protocol number is used for the
16420 message argument. If no string is found in the error database,
16421 the default_string is returned to the buffer argument.
16422
16423 To report an error to the user when the requested display does
16424 not exist, use XDisplayName.
16425
16426 char *XDisplayName(char *string);
16427
16428 string
16429
16430 Specifies the character string.
16431
16432 The XDisplayName function returns the name of the display that
16433 XOpenDisplay would attempt to use. If a NULL string is
16434 specified, XDisplayName looks in the environment for the
16435 display and returns the display name that XOpenDisplay would
16436 attempt to use. This makes it easier to report to the user
16437 precisely which display the program attempted to open when the
16438 initial connection attempt failed.
16439
16440 To handle fatal I/O errors, use XSetIOErrorHandler.
16441
16442 int(int(*handler)(Display *));
16443
16444 handler
16445
16446 Specifies the program's supplied error handler.
16447
16448 The XSetIOErrorHandler sets the fatal I/O error handler. Xlib
16449 calls the program's supplied error handler if any sort of
16450 system call error occurs (for example, the connection to the
16451 server was lost). This is assumed to be a fatal condition, and
16452 the called routine should not return. If the I/O error handler
16453 does return, the client process exits.
16454
16455 Note that the previous error handler is returned.
16456
16457Chapter 12. Input Device Functions
16458
16459 Table of Contents
16460
16461 Pointer Grabbing
16462 Keyboard Grabbing
16463 Resuming Event Processing
16464 Moving the Pointer
16465 Controlling Input Focus
16466 Manipulating the Keyboard and Pointer Settings
16467 Manipulating the Keyboard Encoding
16468
16469 You can use the Xlib input device functions to:
16470 * Grab the pointer and individual buttons on the pointer
16471 * Grab the keyboard and individual keys on the keyboard
16472 * Resume event processing
16473 * Move the pointer
16474 * Set the input focus
16475 * Manipulate the keyboard and pointer settings
16476 * Manipulate the keyboard encoding
16477
16478Pointer Grabbing
16479
16480 Xlib provides functions that you can use to control input from
16481 the pointer, which usually is a mouse. Usually, as soon as
16482 keyboard and mouse events occur, the X server delivers them to
16483 the appropriate client, which is determined by the window and
16484 input focus. The X server provides sufficient control over
16485 event delivery to allow window managers to support mouse ahead
16486 and various other styles of user interface. Many of these user
16487 interfaces depend on synchronous delivery of events. The
16488 delivery of pointer and keyboard events can be controlled
16489 independently.
16490
16491 When mouse buttons or keyboard keys are grabbed, events will be
16492 sent to the grabbing client rather than the normal client who
16493 would have received the event. If the keyboard or pointer is in
16494 asynchronous mode, further mouse and keyboard events will
16495 continue to be processed. If the keyboard or pointer is in
16496 synchronous mode, no further events are processed until the
16497 grabbing client allows them (see XAllowEvents). The keyboard or
16498 pointer is considered frozen during this interval. The event
16499 that triggered the grab can also be replayed.
16500
16501 Note that the logical state of a device (as seen by client
16502 applications) may lag the physical state if device event
16503 processing is frozen.
16504
16505 There are two kinds of grabs: active and passive. An active
16506 grab occurs when a single client grabs the keyboard and/or
16507 pointer explicitly (see XGrabPointer and XGrabKeyboard). A
16508 passive grab occurs when clients grab a particular keyboard key
16509 or pointer button in a window, and the grab will activate when
16510 the key or button is actually pressed. Passive grabs are
16511 convenient for implementing reliable pop-up menus. For example,
16512 you can guarantee that the pop-up is mapped before the up
16513 pointer button event occurs by grabbing a button requesting
16514 synchronous behavior. The down event will trigger the grab and
16515 freeze further processing of pointer events until you have the
16516 chance to map the pop-up window. You can then allow further
16517 event processing. The up event will then be correctly processed
16518 relative to the pop-up window.
16519
16520 For many operations, there are functions that take a time
16521 argument. The X server includes a timestamp in various events.
16522 One special time, called CurrentTime, represents the current
16523 server time. The X server maintains the time when the input
16524 focus was last changed, when the keyboard was last grabbed,
16525 when the pointer was last grabbed, or when a selection was last
16526 changed. Your application may be slow reacting to an event. You
16527 often need some way to specify that your request should not
16528 occur if another application has in the meanwhile taken control
16529 of the keyboard, pointer, or selection. By providing the
16530 timestamp from the event in the request, you can arrange that
16531 the operation not take effect if someone else has performed an
16532 operation in the meanwhile.
16533
16534 A timestamp is a time value, expressed in milliseconds. It
16535 typically is the time since the last server reset. Timestamp
16536 values wrap around (after about 49.7 days). The server, given
16537 its current time is represented by timestamp T, always
16538 interprets timestamps from clients by treating half of the
16539 timestamp space as being later in time than T. One timestamp
16540 value, named CurrentTime, is never generated by the server.
16541 This value is reserved for use in requests to represent the
16542 current server time.
16543
16544 For many functions in this section, you pass pointer event mask
16545 bits. The valid pointer event mask bits are: ButtonPressMask,
16546 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
16547 PointerMotionMask, PointerMotionHintMask, Button1MotionMask,
16548 Button2MotionMask, Button3MotionMask, Button4MotionMask,
16549 Button5MotionMask, ButtonMotionMask, and KeymapStateMask. For
16550 other functions in this section, you pass keymask bits. The
16551 valid keymask bits are: ShiftMask, LockMask, ControlMask,
16552 Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.
16553
16554 To grab the pointer, use XGrabPointer.
16555
16556 int XGrabPointer(Display *display, Window grab_window, Bool
16557 owner_events, unsigned int event_mask, int pointer_mode, int
16558 keyboard_mode, Window confine_to, Cursor cursor, Time time);
16559
16560 display
16561
16562 Specifies the connection to the X server.
16563
16564 grab_window
16565
16566 Specifies the grab window.
16567
16568 owner_events
16569
16570 Specifies a Boolean value that indicates whether the pointer
16571 events are to be reported as usual or reported with respect to
16572 the grab window if selected by the event mask.
16573
16574 event_mask
16575
16576 Specifies which pointer events are reported to the client. The
16577 mask is the bitwise inclusive OR of the valid pointer event
16578 mask bits.
16579
16580 pointer_mode
16581
16582 Specifies further processing of pointer events. You can pass
16583 GrabModeSync or GrabModeAsync.
16584
16585 keyboard_mode
16586
16587 Specifies further processing of keyboard events. You can pass
16588 GrabModeSync or GrabModeAsync.
16589
16590 confine_to
16591
16592 Specifies the window to confine the pointer in or None.
16593
16594 cursor
16595
16596 Specifies the cursor that is to be displayed during the grab or
16597 None.
16598
16599 time
16600
16601 Specifies the time. You can pass either a timestamp or
16602 CurrentTime.
16603
16604 The XGrabPointer function actively grabs control of the pointer
16605 and returns GrabSuccess if the grab was successful. Further
16606 pointer events are reported only to the grabbing client.
16607 XGrabPointer overrides any active pointer grab by this client.
16608 If owner_events is False, all generated pointer events are
16609 reported with respect to grab_window and are reported only if
16610 selected by event_mask. If owner_events is True and if a
16611 generated pointer event would normally be reported to this
16612 client, it is reported as usual. Otherwise, the event is
16613 reported with respect to the grab_window and is reported only
16614 if selected by event_mask. For either value of owner_events,
16615 unreported events are discarded.
16616
16617 If the pointer_mode is GrabModeAsync, pointer event processing
16618 continues as usual. If the pointer is currently frozen by this
16619 client, the processing of events for the pointer is resumed. If
16620 the pointer_mode is GrabModeSync, the state of the pointer, as
16621 seen by client applications, appears to freeze, and the X
16622 server generates no further pointer events until the grabbing
16623 client calls XAllowEvents or until the pointer grab is
16624 released. Actual pointer changes are not lost while the pointer
16625 is frozen; they are simply queued in the server for later
16626 processing.
16627
16628 If the keyboard_mode is GrabModeAsync, keyboard event
16629 processing is unaffected by activation of the grab. If the
16630 keyboard_mode is GrabModeSync, the state of the keyboard, as
16631 seen by client applications, appears to freeze, and the X
16632 server generates no further keyboard events until the grabbing
16633 client calls XAllowEvents or until the pointer grab is
16634 released. Actual keyboard changes are not lost while the
16635 pointer is frozen; they are simply queued in the server for
16636 later processing.
16637
16638 If a cursor is specified, it is displayed regardless of what
16639 window the pointer is in. If None is specified, the normal
16640 cursor for that window is displayed when the pointer is in
16641 grab_window or one of its subwindows; otherwise, the cursor for
16642 grab_window is displayed.
16643
16644 If a confine_to window is specified, the pointer is restricted
16645 to stay contained in that window. The confine_to window need
16646 have no relationship to the grab_window. If the pointer is not
16647 initially in the confine_to window, it is warped automatically
16648 to the closest edge just before the grab activates and
16649 enter/leave events are generated as usual. If the confine_to
16650 window is subsequently reconfigured, the pointer is warped
16651 automatically, as necessary, to keep it contained in the
16652 window.
16653
16654 The time argument allows you to avoid certain circumstances
16655 that come up if applications take a long time to respond or if
16656 there are long network delays. Consider a situation where you
16657 have two applications, both of which normally grab the pointer
16658 when clicked on. If both applications specify the timestamp
16659 from the event, the second application may wake up faster and
16660 successfully grab the pointer before the first application. The
16661 first application then will get an indication that the other
16662 application grabbed the pointer before its request was
16663 processed.
16664
16665 XGrabPointer generates EnterNotify and LeaveNotify events.
16666
16667 Either if grab_window or confine_to window is not viewable or
16668 if the confine_to window lies completely outside the boundaries
16669 of the root window, XGrabPointer fails and returns
16670 GrabNotViewable. If the pointer is actively grabbed by some
16671 other client, it fails and returns AlreadyGrabbed. If the
16672 pointer is frozen by an active grab of another client, it fails
16673 and returns GrabFrozen. If the specified time is earlier than
16674 the last-pointer-grab time or later than the current X server
16675 time, it fails and returns GrabInvalidTime. Otherwise, the
16676 last-pointer-grab time is set to the specified time
16677 (CurrentTime is replaced by the current X server time).
16678
16679 XGrabPointer can generate BadCursor, BadValue, and BadWindow
16680 errors.
16681
16682 To ungrab the pointer, use XUngrabPointer.
16683
16684 XUngrabPointer(Display *display, Time time);
16685
16686 display
16687
16688 Specifies the connection to the X server.
16689
16690 time
16691
16692 Specifies the time. You can pass either a timestamp or
16693 CurrentTime.
16694
16695 The XUngrabPointer function releases the pointer and any queued
16696 events if this client has actively grabbed the pointer from
16697 XGrabPointer, XGrabButton, or from a normal button press.
16698 XUngrabPointer does not release the pointer if the specified
16699 time is earlier than the last-pointer-grab time or is later
16700 than the current X server time. It also generates EnterNotify
16701 and LeaveNotify events. The X server performs an UngrabPointer
16702 request automatically if the event window or confine_to window
16703 for an active pointer grab becomes not viewable or if window
16704 reconfiguration causes the confine_to window to lie completely
16705 outside the boundaries of the root window.
16706
16707 To change an active pointer grab, use XChangeActivePointerGrab.
16708
16709 XChangeActivePointerGrab(Display *display, unsigned int
16710 event_mask, Cursor cursor, Time time);
16711
16712 display
16713
16714 Specifies the connection to the X server.
16715
16716 event_mask
16717
16718 Specifies which pointer events are reported to the client. The
16719 mask is the bitwise inclusive OR of the valid pointer event
16720 mask bits.
16721
16722 cursor
16723
16724 Specifies the cursor that is to be displayed or None.
16725
16726 time
16727
16728 Specifies the time. You can pass either a timestamp or
16729 CurrentTime.
16730
16731 The XChangeActivePointerGrab function changes the specified
16732 dynamic parameters if the pointer is actively grabbed by the
16733 client and if the specified time is no earlier than the
16734 last-pointer-grab time and no later than the current X server
16735 time. This function has no effect on the passive parameters of
16736 an XGrabButton. The interpretation of event_mask and cursor is
16737 the same as described in XGrabPointer.
16738
16739 XChangeActivePointerGrab can generate BadCursor and BadValue
16740 errors.
16741
16742 To grab a pointer button, use XGrabButton.
16743
16744 XGrabButton(Display *display, unsigned int button, unsigned int
16745 modifiers, Window grab_window, Bool owner_events, unsigned int
16746 event_mask, int pointer_mode, int keyboard_mode, Window
16747 confine_to, Cursor cursor);
16748
16749 display
16750
16751 Specifies the connection to the X server.
16752
16753 button
16754
16755 Specifies the pointer button that is to be grabbed or
16756 AnyButton.
16757
16758 modifiers
16759
16760 Specifies the set of keymasks or AnyModifier. The mask is the
16761 bitwise inclusive OR of the valid keymask bits.
16762
16763 grab_window
16764
16765 Specifies the grab window.
16766
16767 owner_events
16768
16769 Specifies a Boolean value that indicates whether the pointer
16770 events are to be reported as usual or reported with respect to
16771 the grab window if selected by the event mask.
16772
16773 event_mask
16774
16775 Specifies which pointer events are reported to the client. The
16776 mask is the bitwise inclusive OR of the valid pointer event
16777 mask bits.
16778
16779 pointer_mode
16780
16781 Specifies further processing of pointer events. You can pass
16782 GrabModeSync or GrabModeAsync.
16783
16784 keyboard_mode
16785
16786 Specifies further processing of keyboard events. You can pass
16787 GrabModeSync or GrabModeAsync.
16788
16789 confine_to
16790
16791 Specifies the window to confine the pointer in or None.
16792
16793 cursor
16794
16795 Specifies the cursor that is to be displayed or None.
16796
16797 The XGrabButton function establishes a passive grab. In the
16798 future, the pointer is actively grabbed (as for XGrabPointer),
16799 the last-pointer-grab time is set to the time at which the
16800 button was pressed (as transmitted in the ButtonPress event),
16801 and the ButtonPress event is reported if all of the following
16802 conditions are true:
16803 * The pointer is not grabbed, and the specified button is
16804 logically pressed when the specified modifier keys are
16805 logically down, and no other buttons or modifier keys are
16806 logically down.
16807 * The grab_window contains the pointer.
16808 * The confine_to window (if any) is viewable.
16809 * A passive grab on the same button/key combination does not
16810 exist on any ancestor of grab_window.
16811
16812 The interpretation of the remaining arguments is as for
16813 XGrabPointer. The active grab is terminated automatically when
16814 the logical state of the pointer has all buttons released
16815 (independent of the state of the logical modifier keys).
16816
16817 Note that the logical state of a device (as seen by client
16818 applications) may lag the physical state if device event
16819 processing is frozen.
16820
16821 This request overrides all previous grabs by the same client on
16822 the same button/key combinations on the same window. A
16823 modifiers of AnyModifier is equivalent to issuing the grab
16824 request for all possible modifier combinations (including the
16825 combination of no modifiers). It is not required that all
16826 modifiers specified have currently assigned KeyCodes. A button
16827 of AnyButton is equivalent to issuing the request for all
16828 possible buttons. Otherwise, it is not required that the
16829 specified button currently be assigned to a physical button.
16830
16831 If some other client has already issued an XGrabButton with the
16832 same button/key combination on the same window, a BadAccess
16833 error results. When using AnyModifier or AnyButton, the request
16834 fails completely, and a BadAccess error results (no grabs are
16835 established) if there is a conflicting grab for any
16836 combination. XGrabButton has no effect on an active grab.
16837
16838 XGrabButton can generate BadCursor, BadValue, and BadWindow
16839 errors.
16840
16841 To ungrab a pointer button, use XUngrabButton.
16842
16843 XUngrabButton(Display *display, unsigned int button, unsigned
16844 int modifiers, Window grab_window);
16845
16846 display
16847
16848 Specifies the connection to the X server.
16849
16850 button
16851
16852 Specifies the pointer button that is to be released or
16853 AnyButton.
16854
16855 modifiers
16856
16857 Specifies the set of keymasks or AnyModifier. The mask is the
16858 bitwise inclusive OR of the valid keymask bits.
16859
16860 grab_window
16861
16862 Specifies the grab window.
16863
16864 The XUngrabButton function releases the passive button/key
16865 combination on the specified window if it was grabbed by this
16866 client. A modifiers of AnyModifier is equivalent to issuing the
16867 ungrab request for all possible modifier combinations,
16868 including the combination of no modifiers. A button of
16869 AnyButton is equivalent to issuing the request for all possible
16870 buttons. XUngrabButton has no effect on an active grab.
16871
16872 XUngrabButton can generate BadValue and BadWindow errors.
16873
16874Keyboard Grabbing
16875
16876 Xlib provides functions that you can use to grab or ungrab the
16877 keyboard as well as allow events.
16878
16879 For many functions in this section, you pass keymask bits. The
16880 valid keymask bits are: ShiftMask, LockMask, ControlMask,
16881 Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.
16882
16883 To grab the keyboard, use XGrabKeyboard.
16884
16885 int XGrabKeyboard(Display *display, Window grab_window, Bool
16886 owner_events, int pointer_mode, int keyboard_mode, Time time);
16887
16888 display
16889
16890 Specifies the connection to the X server.
16891
16892 grab_window
16893
16894 Specifies the grab window.
16895
16896 owner_events
16897
16898 Specifies a Boolean value that indicates whether the keyboard
16899 events are to be reported as usual.
16900
16901 pointer_mode
16902
16903 Specifies further processing of pointer events. You can pass
16904 GrabModeSync or GrabModeAsync.
16905
16906 keyboard_mode
16907
16908 Specifies further processing of keyboard events. You can pass
16909 GrabModeSync or GrabModeAsync.
16910
16911 time
16912
16913 Specifies the time. You can pass either a timestamp or
16914 CurrentTime.
16915
16916 The XGrabKeyboard function actively grabs control of the
16917 keyboard and generates FocusIn and FocusOut events. Further key
16918 events are reported only to the grabbing client. XGrabKeyboard
16919 overrides any active keyboard grab by this client. If
16920 owner_events is False, all generated key events are reported
16921 with respect to grab_window. If owner_events is True and if a
16922 generated key event would normally be reported to this client,
16923 it is reported normally; otherwise, the event is reported with
16924 respect to the grab_window. Both KeyPress and KeyRelease events
16925 are always reported, independent of any event selection made by
16926 the client.
16927
16928 If the keyboard_mode argument is GrabModeAsync, keyboard event
16929 processing continues as usual. If the keyboard is currently
16930 frozen by this client, then processing of keyboard events is
16931 resumed. If the keyboard_mode argument is GrabModeSync, the
16932 state of the keyboard (as seen by client applications) appears
16933 to freeze, and the X server generates no further keyboard
16934 events until the grabbing client issues a releasing
16935 XAllowEvents call or until the keyboard grab is released.
16936 Actual keyboard changes are not lost while the keyboard is
16937 frozen; they are simply queued in the server for later
16938 processing.
16939
16940 If pointer_mode is GrabModeAsync, pointer event processing is
16941 unaffected by activation of the grab. If pointer_mode is
16942 GrabModeSync, the state of the pointer (as seen by client
16943 applications) appears to freeze, and the X server generates no
16944 further pointer events until the grabbing client issues a
16945 releasing XAllowEvents call or until the keyboard grab is
16946 released. Actual pointer changes are not lost while the pointer
16947 is frozen; they are simply queued in the server for later
16948 processing.
16949
16950 If the keyboard is actively grabbed by some other client,
16951 XGrabKeyboard fails and returns AlreadyGrabbed. If grab_window
16952 is not viewable, it fails and returns GrabNotViewable. If the
16953 keyboard is frozen by an active grab of another client, it
16954 fails and returns GrabFrozen. If the specified time is earlier
16955 than the last-keyboard-grab time or later than the current X
16956 server time, it fails and returns GrabInvalidTime. Otherwise,
16957 the last-keyboard-grab time is set to the specified time
16958 (CurrentTime is replaced by the current X server time).
16959
16960 XGrabKeyboard can generate BadValue and BadWindow errors.
16961
16962 To ungrab the keyboard, use XUngrabKeyboard.
16963
16964 XUngrabKeyboard(Display *display, Time time);
16965
16966 display
16967
16968 Specifies the connection to the X server.
16969
16970 time
16971
16972 Specifies the time. You can pass either a timestamp or
16973 CurrentTime.
16974
16975 The XUngrabKeyboard function releases the keyboard and any
16976 queued events if this client has it actively grabbed from
16977 either XGrabKeyboard or XGrabKey. XUngrabKeyboard does not
16978 release the keyboard and any queued events if the specified
16979 time is earlier than the last-keyboard-grab time or is later
16980 than the current X server time. It also generates FocusIn and
16981 FocusOut events. The X server automatically performs an
16982 UngrabKeyboard request if the event window for an active
16983 keyboard grab becomes not viewable.
16984
16985 To passively grab a single key of the keyboard, use XGrabKey.
16986
16987 XGrabKey(Display *display, int keycode, unsigned int modifiers,
16988 Window grab_window, Bool owner_events, int pointer_mode, int
16989 keyboard_mode);
16990
16991 display
16992
16993 Specifies the connection to the X server.
16994
16995 keycode
16996
16997 Specifies the KeyCode or AnyKey.
16998
16999 modifiers
17000
17001 Specifies the set of keymasks or AnyModifier. The mask is the
17002 bitwise inclusive OR of the valid keymask bits.
17003
17004 grab_window
17005
17006 Specifies the grab window.
17007
17008 owner_events
17009
17010 Specifies a Boolean value that indicates whether the keyboard
17011 events are to be reported as usual.
17012
17013 pointer_mode
17014
17015 Specifies further processing of pointer events. You can pass
17016 GrabModeSync or GrabModeAsync.
17017
17018 keyboard_mode
17019
17020 Specifies further processing of keyboard events. You can pass
17021 GrabModeSync or GrabModeAsync.
17022
17023 The XGrabKey function establishes a passive grab on the
17024 keyboard. In the future, the keyboard is actively grabbed (as
17025 for XGrabKeyboard), the last-keyboard-grab time is set to the
17026 time at which the key was pressed (as transmitted in the
17027 KeyPress event), and the KeyPress event is reported if all of
17028 the following conditions are true:
17029 * The keyboard is not grabbed and the specified key (which
17030 can itself be a modifier key) is logically pressed when the
17031 specified modifier keys are logically down, and no other
17032 modifier keys are logically down.
17033 * Either the grab_window is an ancestor of (or is) the focus
17034 window, or the grab_window is a descendant of the focus
17035 window and contains the pointer.
17036 * A passive grab on the same key combination does not exist
17037 on any ancestor of grab_window.
17038
17039 The interpretation of the remaining arguments is as for
17040 XGrabKeyboard. The active grab is terminated automatically when
17041 the logical state of the keyboard has the specified key
17042 released (independent of the logical state of the modifier
17043 keys).
17044
17045 Note that the logical state of a device (as seen by client
17046 applications) may lag the physical state if device event
17047 processing is frozen.
17048
17049 A modifiers argument of AnyModifier is equivalent to issuing
17050 the request for all possible modifier combinations (including
17051 the combination of no modifiers). It is not required that all
17052 modifiers specified have currently assigned KeyCodes. A keycode
17053 argument of AnyKey is equivalent to issuing the request for all
17054 possible KeyCodes. Otherwise, the specified keycode must be in
17055 the range specified by min_keycode and max_keycode in the
17056 connection setup, or a BadValue error results.
17057
17058 If some other client has issued a XGrabKey with the same key
17059 combination on the same window, a BadAccess error results. When
17060 using AnyModifier or AnyKey, the request fails completely, and
17061 a BadAccess error results (no grabs are established) if there
17062 is a conflicting grab for any combination.
17063
17064 XGrabKey can generate BadAccess, BadValue, and BadWindow
17065 errors.
17066
17067 To ungrab a key, use XUngrabKey.
17068
17069 XUngrabKey(Display *display, int keycode, unsigned int
17070 modifiers, Window grab_window);
17071
17072 display
17073
17074 Specifies the connection to the X server.
17075
17076 keycode
17077
17078 Specifies the KeyCode or AnyKey.
17079
17080 modifiers
17081
17082 Specifies the set of keymasks or AnyModifier. The mask is the
17083 bitwise inclusive OR of the valid keymask bits.
17084
17085 grab_window
17086
17087 Specifies the grab window.
17088
17089 The XUngrabKey function releases the key combination on the
17090 specified window if it was grabbed by this client. It has no
17091 effect on an active grab. A modifiers of AnyModifier is
17092 equivalent to issuing the request for all possible modifier
17093 combinations (including the combination of no modifiers). A
17094 keycode argument of AnyKey is equivalent to issuing the request
17095 for all possible key codes.
17096
17097 XUngrabKey can generate BadValue and BadWindow errors.
17098
17099Resuming Event Processing
17100
17101 The previous sections discussed grab mechanisms with which
17102 processing of events by the server can be temporarily
17103 suspended. This section describes the mechanism for resuming
17104 event processing.
17105
17106 To allow further events to be processed when the device has
17107 been frozen, use XAllowEvents.
17108
17109 XAllowEvents(Display *display, int event_mode, Time time);
17110
17111 display
17112
17113 Specifies the connection to the X server.
17114
17115 event_mode
17116
17117 Specifies the event mode. You can pass AsyncPointer,
17118 SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer,
17119 ReplayKeyboard, AsyncBoth, or SyncBoth.
17120
17121 time
17122
17123 Specifies the time. You can pass either a timestamp or
17124 CurrentTime.
17125
17126 The XAllowEvents function releases some queued events if the
17127 client has caused a device to freeze. It has no effect if the
17128 specified time is earlier than the last-grab time of the most
17129 recent active grab for the client or if the specified time is
17130 later than the current X server time. Depending on the
17131 event_mode argument, the following occurs:
17132 AsyncPointer If the pointer is frozen by the client, pointer
17133 event processing continues as usual. If the pointer is frozen
17134 twice by the client on behalf of two separate grabs,
17135 AsyncPointer thaws for both. AsyncPointer has no effect if the
17136 pointer is not frozen by the client, but the pointer need not
17137 be grabbed by the client.
17138 SyncPointer If the pointer is frozen and actively grabbed by
17139 the client, pointer event processing continues as usual until
17140 the next ButtonPress or ButtonRelease event is reported to the
17141 client. At this time, the pointer again appears to freeze.
17142 However, if the reported event causes the pointer grab to be
17143 released, the pointer does not freeze. SyncPointer has no
17144 effect if the pointer is not frozen by the client or if the
17145 pointer is not grabbed by the client.
17146 ReplayPointer If the pointer is actively grabbed by the client
17147 and is frozen as the result of an event having been sent to the
17148 client (either from the activation of an XGrabButton or from a
17149 previous XAllowEvents with mode SyncPointer but not from an
17150 XGrabPointer), the pointer grab is released and that event is
17151 completely reprocessed. This time, however, the function
17152 ignores any passive grabs at or above (toward the root of) the
17153 grab_window of the grab just released. The request has no
17154 effect if the pointer is not grabbed by the client or if the
17155 pointer is not frozen as the result of an event.
17156 AsyncKeyboard If the keyboard is frozen by the client, keyboard
17157 event processing continues as usual. If the keyboard is frozen
17158 twice by the client on behalf of two separate grabs,
17159 AsyncKeyboard thaws for both. AsyncKeyboard has no effect if
17160 the keyboard is not frozen by the client, but the keyboard need
17161 not be grabbed by the client.
17162 SyncKeyboard If the keyboard is frozen and actively grabbed by
17163 the client, keyboard event processing continues as usual until
17164 the next KeyPress or KeyRelease event is reported to the
17165 client. At this time, the keyboard again appears to freeze.
17166 However, if the reported event causes the keyboard grab to be
17167 released, the keyboard does not freeze. SyncKeyboard has no
17168 effect if the keyboard is not frozen by the client or if the
17169 keyboard is not grabbed by the client.
17170 ReplayKeyboard If the keyboard is actively grabbed by the
17171 client and is frozen as the result of an event having been sent
17172 to the client (either from the activation of an XGrabKey or
17173 from a previous XAllowEvents with mode SyncKeyboard but not
17174 from an XGrabKeyboard), the keyboard grab is released and that
17175 event is completely reprocessed. This time, however, the
17176 function ignores any passive grabs at or above (toward the root
17177 of) the grab_window of the grab just released. The request has
17178 no effect if the keyboard is not grabbed by the client or if
17179 the keyboard is not frozen as the result of an event.
17180 SyncBoth If both pointer and keyboard are frozen by the client,
17181 event processing for both devices continues as usual until the
17182 next ButtonPress, ButtonRelease, KeyPress, or KeyRelease event
17183 is reported to the client for a grabbed device (button event
17184 for the pointer, key event for the keyboard), at which time the
17185 devices again appear to freeze. However, if the reported event
17186 causes the grab to be released, then the devices do not freeze
17187 (but if the other device is still grabbed, then a subsequent
17188 event for it will still cause both devices to freeze). SyncBoth
17189 has no effect unless both pointer and keyboard are frozen by
17190 the client. If the pointer or keyboard is frozen twice by the
17191 client on behalf of two separate grabs, SyncBoth thaws for both
17192 (but a subsequent freeze for SyncBoth will only freeze each
17193 device once).
17194 AsyncBoth If the pointer and the keyboard are frozen by the
17195 client, event processing for both devices continues as usual.
17196 If a device is frozen twice by the client on behalf of two
17197 separate grabs, AsyncBoth thaws for both. AsyncBoth has no
17198 effect unless both pointer and keyboard are frozen by the
17199 client.
17200
17201 AsyncPointer, SyncPointer, and ReplayPointer have no effect on
17202 the processing of keyboard events. AsyncKeyboard, SyncKeyboard,
17203 and ReplayKeyboard have no effect on the processing of pointer
17204 events. It is possible for both a pointer grab and a keyboard
17205 grab (by the same or different clients) to be active
17206 simultaneously. If a device is frozen on behalf of either grab,
17207 no event processing is performed for the device. It is possible
17208 for a single device to be frozen because of both grabs. In this
17209 case, the freeze must be released on behalf of both grabs
17210 before events can again be processed. If a device is frozen
17211 twice by a single client, then a single XAllowEvents releases
17212 both.
17213
17214 XAllowEvents can generate a BadValue error.
17215
17216Moving the Pointer
17217
17218 Although movement of the pointer normally should be left to the
17219 control of the end user, sometimes it is necessary to move the
17220 pointer to a new position under program control.
17221
17222 To move the pointer to an arbitrary point in a window, use
17223 XWarpPointer.
17224
17225 XWarpPointer(Display *display, Window src_w, Window dest_w, int
17226 src_x, int src_y, unsigned int src_width, unsigned int
17227 src_height, int dest_x, int dest_y);
17228
17229 display
17230
17231 Specifies the connection to the X server.
17232
17233 src_w
17234
17235 Specifies the source window or None.
17236
17237 dest_w
17238
17239 Specifies the destination window or None.
17240
17241 src_x
17242
17243 src_y
17244
17245 src_width
17246
17247 src_height
17248
17249 Specify a rectangle in the source window.
17250
17251 dest_x
17252
17253 dest_y
17254
17255 Specify the x and y coordinates within the destination window.
17256
17257 If dest_w is None, XWarpPointer moves the pointer by the
17258 offsets (dest_x, dest_y) relative to the current position of
17259 the pointer. If dest_w is a window, XWarpPointer moves the
17260 pointer to the offsets (dest_x, dest_y) relative to the origin
17261 of dest_w. However, if src_w is a window, the move only takes
17262 place if the window src_w contains the pointer and if the
17263 specified rectangle of src_w contains the pointer.
17264
17265 The src_x and src_y coordinates are relative to the origin of
17266 src_w. If src_height is zero, it is replaced with the current
17267 height of src_w minus src_y. If src_width is zero, it is
17268 replaced with the current width of src_w minus src_x.
17269
17270 There is seldom any reason for calling this function. The
17271 pointer should normally be left to the user. If you do use this
17272 function, however, it generates events just as if the user had
17273 instantaneously moved the pointer from one position to another.
17274 Note that you cannot use XWarpPointer to move the pointer
17275 outside the confine_to window of an active pointer grab. An
17276 attempt to do so will only move the pointer as far as the
17277 closest edge of the confine_to window.
17278
17279 XWarpPointer can generate a BadWindow error.
17280
17281Controlling Input Focus
17282
17283 Xlib provides functions that you can use to set and get the
17284 input focus. The input focus is a shared resource, and
17285 cooperation among clients is required for correct interaction.
17286 See the Inter-Client Communication Conventions Manual for input
17287 focus policy.
17288
17289 To set the input focus, use XSetInputFocus.
17290
17291 XSetInputFocus(Display *display, Window focus, int revert_to,
17292 Time time);
17293
17294 display
17295
17296 Specifies the connection to the X server.
17297
17298 focus
17299
17300 Specifies the window, PointerRoot, or None.
17301
17302 revert_to
17303
17304 Specifies where the input focus reverts to if the window
17305 becomes not viewable. You can pass RevertToParent,
17306 RevertToPointerRoot, or RevertToNone.
17307
17308 time
17309
17310 Specifies the time. You can pass either a timestamp or
17311 CurrentTime.
17312
17313 The XSetInputFocus function changes the input focus and the
17314 last-focus-change time. It has no effect if the specified time
17315 is earlier than the current last-focus-change time or is later
17316 than the current X server time. Otherwise, the
17317 last-focus-change time is set to the specified time
17318 (CurrentTime is replaced by the current X server time).
17319 XSetInputFocus causes the X server to generate FocusIn and
17320 FocusOut events.
17321
17322 Depending on the focus argument, the following occurs:
17323 * If focus is None, all keyboard events are discarded until a
17324 new focus window is set, and the revert_to argument is
17325 ignored.
17326 * If focus is a window, it becomes the keyboard's focus
17327 window. If a generated keyboard event would normally be
17328 reported to this window or one of its inferiors, the event
17329 is reported as usual. Otherwise, the event is reported
17330 relative to the focus window.
17331 * If focus is PointerRoot, the focus window is dynamically
17332 taken to be the root window of whatever screen the pointer
17333 is on at each keyboard event. In this case, the revert_to
17334 argument is ignored.
17335
17336 The specified focus window must be viewable at the time
17337 XSetInputFocus is called, or a BadMatch error results. If the
17338 focus window later becomes not viewable, the X server evaluates
17339 the revert_to argument to determine the new focus window as
17340 follows:
17341 * If revert_to is RevertToParent, the focus reverts to the
17342 parent (or the closest viewable ancestor), and the new
17343 revert_to value is taken to be RevertToNone.
17344 * If revert_to is RevertToPointerRoot or RevertToNone, the
17345 focus reverts to PointerRoot or None, respectively. When
17346 the focus reverts, the X server generates FocusIn and
17347 FocusOut events, but the last-focus-change time is not
17348 affected.
17349
17350 XSetInputFocus can generate BadMatch, BadValue, and BadWindow
17351 errors.
17352
17353 To obtain the current input focus, use XGetInputFocus.
17354
17355 XGetInputFocus(Display *display, Window *focus_return, int
17356 *revert_to_return);
17357
17358 display
17359
17360 Specifies the connection to the X server.
17361
17362 focus_return
17363
17364 Returns the focus window, PointerRoot, or None.
17365
17366 revert_to_return
17367
17368 Returns the current focus state (RevertToParent,
17369 RevertToPointerRoot, or RevertToNone).
17370
17371 The XGetInputFocus function returns the focus window and the
17372 current focus state.
17373
17374Manipulating the Keyboard and Pointer Settings
17375
17376 Xlib provides functions that you can use to change the keyboard
17377 control, obtain a list of the auto-repeat keys, turn keyboard
17378 auto-repeat on or off, ring the bell, set or obtain the pointer
17379 button or keyboard mapping, and obtain a bit vector for the
17380 keyboard.
17381
17382 This section discusses the user-preference options of bell, key
17383 click, pointer behavior, and so on. The default values for many
17384 of these options are server dependent. Not all implementations
17385 will actually be able to control all of these parameters.
17386
17387 The XChangeKeyboardControl function changes control of a
17388 keyboard and operates on a XKeyboardControl structure:
17389/* Mask bits for ChangeKeyboardControl */
17390
17391
17392#define KBBellPercent (1L<<0)
17393#define KBBellPitch (1L<<1)
17394#define KBBellDuration (1L<<2)
17395#define KBLed (1L<<3)
17396#define KBLedMode (1L<<4)
17397#define KBKey (1L<<5)
17398#define KBAutoRepeatMode (1L<<6)
17399
17400
17401/* Values */
17402
17403typedef struct {
17404int key_click_percent;
17405int bell_percent;
17406int bell_pitch;
17407int bell_duration;
17408int led;
17409int led_mode; /* LedModeOn, LedModeOff */
17410int key;
17411int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn,
17412 AutoRepeatModeDefault */
17413} XKeyboardControl;
17414
17415
17416 The key_click_percent member sets the volume for key clicks
17417 between 0 (off) and 100 (loud) inclusive, if possible. A
17418 setting of -1 restores the default. Other negative values
17419 generate a BadValue error.
17420
17421 The bell_percent sets the base volume for the bell between 0
17422 (off) and 100 (loud) inclusive, if possible. A setting of -1
17423 restores the default. Other negative values generate a BadValue
17424 error. The bell_pitch member sets the pitch (specified in Hz)
17425 of the bell, if possible. A setting of -1 restores the default.
17426 Other negative values generate a BadValue error. The
17427 bell_duration member sets the duration of the bell specified in
17428 milliseconds, if possible. A setting of -1 restores the
17429 default. Other negative values generate a BadValue error.
17430
17431 If both the led_mode and led members are specified, the state
17432 of that LED is changed, if possible. The led_mode member can be
17433 set to LedModeOn or LedModeOff. If only led_mode is specified,
17434 the state of all LEDs are changed, if possible. At most 32 LEDs
17435 numbered from one are supported. No standard interpretation of
17436 LEDs is defined. If led is specified without led_mode, a
17437 BadMatch error results.
17438
17439 If both the auto_repeat_mode and key members are specified, the
17440 auto_repeat_mode of that key is changed (according to
17441 AutoRepeatModeOn, AutoRepeatModeOff, or AutoRepeatModeDefault),
17442 if possible. If only auto_repeat_mode is specified, the global
17443 auto_repeat_mode for the entire keyboard is changed, if
17444 possible, and does not affect the per-key settings. If a key is
17445 specified without an auto_repeat_mode, a BadMatch error
17446 results. Each key has an individual mode of whether or not it
17447 should auto-repeat and a default setting for the mode. In
17448 addition, there is a global mode of whether auto-repeat should
17449 be enabled or not and a default setting for that mode. When
17450 global mode is AutoRepeatModeOn, keys should obey their
17451 individual auto-repeat modes. When global mode is
17452 AutoRepeatModeOff, no keys should auto-repeat. An
17453 auto-repeating key generates alternating KeyPress and
17454 KeyRelease events. When a key is used as a modifier, it is
17455 desirable for the key not to auto-repeat, regardless of its
17456 auto-repeat setting.
17457
17458 A bell generator connected with the console but not directly on
17459 a keyboard is treated as if it were part of the keyboard. The
17460 order in which controls are verified and altered is
17461 server-dependent. If an error is generated, a subset of the
17462 controls may have been altered.
17463
17464 XChangeKeyboardControl(Display *display, unsigned long
17465 value_mask, XKeyboardControl *values);
17466
17467 display
17468
17469 Specifies the connection to the X server.
17470
17471 value_mask
17472
17473 Specifies which controls to change. This mask is the bitwise
17474 inclusive OR of the valid control mask bits.
17475
17476 values
17477
17478 Specifies one value for each bit set to 1 in the mask.
17479
17480 The XChangeKeyboardControl function controls the keyboard
17481 characteristics defined by the XKeyboardControl structure. The
17482 value_mask argument specifies which values are to be changed.
17483
17484 XChangeKeyboardControl can generate BadMatch and BadValue
17485 errors.
17486
17487 To obtain the current control values for the keyboard, use
17488 XGetKeyboardControl.
17489
17490 XGetKeyboardControl(Display *display, XKeyboardState
17491 *values_return);
17492
17493 display
17494
17495 Specifies the connection to the X server.
17496
17497 values_return
17498
17499 Returns the current keyboard controls in the specified
17500 XKeyboardState structure.
17501
17502 The XGetKeyboardControl function returns the current control
17503 values for the keyboard to the XKeyboardState structure.
17504
17505
17506
17507typedef struct {
17508 int key_click_percent;
17509 int bell_percent;
17510 unsigned int bell_pitch, bell_duration;
17511 unsigned long led_mask;
17512 int global_auto_repeat;
17513 char auto_repeats[32];
17514} XKeyboardState;
17515
17516 For the LEDs, the least significant bit of led_mask corresponds
17517 to LED one, and each bit set to 1 in led_mask indicates an LED
17518 that is lit. The global_auto_repeat member can be set to
17519 AutoRepeatModeOn or AutoRepeatModeOff. The auto_repeats member
17520 is a bit vector. Each bit set to 1 indicates that auto-repeat
17521 is enabled for the corresponding key. The vector is represented
17522 as 32 bytes. Byte N (from 0) contains the bits for keys 8N to
17523 8N + 7 with the least significant bit in the byte representing
17524 key 8N.
17525
17526 To turn on keyboard auto-repeat, use XAutoRepeatOn.
17527
17528 XAutoRepeatOn(Display *display);
17529
17530 display
17531
17532 Specifies the connection to the X server.
17533
17534 The XAutoRepeatOn function turns on auto-repeat for the
17535 keyboard on the specified display.
17536
17537 To turn off keyboard auto-repeat, use XAutoRepeatOff.
17538
17539 XAutoRepeatOff(Display *display);
17540
17541 display
17542
17543 Specifies the connection to the X server.
17544
17545 The XAutoRepeatOff function turns off auto-repeat for the
17546 keyboard on the specified display.
17547
17548 To ring the bell, use XBell.
17549
17550 XBell(Display *display, int percent);
17551
17552 display
17553
17554 Specifies the connection to the X server.
17555
17556 percent
17557
17558 Specifies the volume for the bell, which can range from -100 to
17559 100 inclusive.
17560
17561 The XBell function rings the bell on the keyboard on the
17562 specified display, if possible. The specified volume is
17563 relative to the base volume for the keyboard. If the value for
17564 the percent argument is not in the range -100 to 100 inclusive,
17565 a BadValue error results. The volume at which the bell rings
17566 when the percent argument is nonnegative is:
17567 * base - [(base * percent) / 100] + percent
17568
17569 The volume at which the bell rings when the percent argument is
17570 negative is:
17571 * base + [(base * percent) / 100]
17572
17573 To change the base volume of the bell, use
17574 XChangeKeyboardControl.
17575
17576 XBell can generate a BadValue error.
17577
17578 To obtain a bit vector that describes the state of the
17579 keyboard, use XQueryKeymap.
17580
17581 XQueryKeymap(Display *display, char keys_return[32]);
17582
17583 display
17584
17585 Specifies the connection to the X server.
17586
17587 keys_return
17588
17589 Returns an array of bytes that identifies which keys are
17590 pressed down. Each bit represents one key of the keyboard.
17591
17592 The XQueryKeymap function returns a bit vector for the logical
17593 state of the keyboard, where each bit set to 1 indicates that
17594 the corresponding key is currently pressed down. The vector is
17595 represented as 32 bytes. Byte N (from 0) contains the bits for
17596 keys 8N to 8N + 7 with the least significant bit in the byte
17597 representing key 8N.
17598
17599 Note that the logical state of a device (as seen by client
17600 applications) may lag the physical state if device event
17601 processing is frozen.
17602
17603 To set the mapping of the pointer buttons, use
17604 XSetPointerMapping.
17605
17606 int XSetPointerMapping(Display *display, unsignedchar map[],
17607 int nmap);
17608
17609 display
17610
17611 Specifies the connection to the X server.
17612
17613 map
17614
17615 Specifies the mapping list.
17616
17617 nmap
17618
17619 Specifies the number of items in the mapping list.
17620
17621 The XSetPointerMapping function sets the mapping of the
17622 pointer. If it succeeds, the X server generates a MappingNotify
17623 event, and XSetPointerMapping returns MappingSuccess. Element
17624 map[i] defines the logical button number for the physical
17625 button i+1. The length of the list must be the same as
17626 XGetPointerMapping would return, or a BadValue error results. A
17627 zero element disables a button, and elements are not restricted
17628 in value by the number of physical buttons. However, no two
17629 elements can have the same nonzero value, or a BadValue error
17630 results. If any of the buttons to be altered are logically in
17631 the down state, XSetPointerMapping returns MappingBusy, and the
17632 mapping is not changed.
17633
17634 XSetPointerMapping can generate a BadValue error.
17635
17636 To get the pointer mapping, use XGetPointerMapping.
17637
17638 int XGetPointerMapping(Display *display, unsignedchar
17639 map_return[], int nmap);
17640
17641 display
17642
17643 Specifies the connection to the X server.
17644
17645 map_return
17646
17647 Returns the mapping list.
17648
17649 nmap
17650
17651 Specifies the number of items in the mapping list.
17652
17653 The XGetPointerMapping function returns the current mapping of
17654 the pointer. Pointer buttons are numbered starting from one.
17655 XGetPointerMapping returns the number of physical buttons
17656 actually on the pointer. The nominal mapping for a pointer is
17657 map[i]=i+1. The nmap argument specifies the length of the array
17658 where the pointer mapping is returned, and only the first nmap
17659 elements are returned in map_return.
17660
17661 To control the pointer's interactive feel, use
17662 XChangePointerControl.
17663
17664 XChangePointerControl(Display *display, Bool do_accel, Bool
17665 do_threshold, int accel_numerator, int accel_denominator, int
17666 threshold);
17667
17668 display
17669
17670 Specifies the connection to the X server.
17671
17672 do_accel
17673
17674 Specifies a Boolean value that controls whether the values for
17675 the accel_numerator or accel_denominator are used.
17676
17677 do_threshold
17678
17679 Specifies a Boolean value that controls whether the value for
17680 the threshold is used.
17681
17682 accel_numerator
17683
17684 Specifies the numerator for the acceleration multiplier.
17685
17686 accel_denominator
17687
17688 Specifies the denominator for the acceleration multiplier.
17689
17690 threshold
17691
17692 Specifies the acceleration threshold.
17693
17694 The XChangePointerControl function defines how the pointing
17695 device moves. The acceleration, expressed as a fraction, is a
17696 multiplier for movement. For example, specifying 3/1 means the
17697 pointer moves three times as fast as normal. The fraction may
17698 be rounded arbitrarily by the X server. Acceleration only takes
17699 effect if the pointer moves more than threshold pixels at once
17700 and only applies to the amount beyond the value in the
17701 threshold argument. Setting a value to -1 restores the default.
17702 The values of the do_accel and do_threshold arguments must be
17703 True for the pointer values to be set, or the parameters are
17704 unchanged. Negative values (other than -1) generate a BadValue
17705 error, as does a zero value for the accel_denominator argument.
17706
17707 XChangePointerControl can generate a BadValue error.
17708
17709 To get the current pointer parameters, use XGetPointerControl.
17710
17711 XGetPointerControl(Display *display, int
17712 *accel_numerator_return, int *accel_denominator_return, int
17713 *threshold_return);
17714
17715 display
17716
17717 Specifies the connection to the X server.
17718
17719 accel_numerator_return
17720
17721 Returns the numerator for the acceleration multiplier.
17722
17723 accel_denominator_return
17724
17725 Returns the denominator for the acceleration multiplier.
17726
17727 threshold_return
17728
17729 Returns the acceleration threshold.
17730
17731 The XGetPointerControl function returns the pointer's current
17732 acceleration multiplier and acceleration threshold.
17733
17734Manipulating the Keyboard Encoding
17735
17736 A KeyCode represents a physical (or logical) key. KeyCodes lie
17737 in the inclusive range [8,255]. A KeyCode value carries no
17738 intrinsic information, although server implementors may attempt
17739 to encode geometry (for example, matrix) information in some
17740 fashion so that it can be interpreted in a server-dependent
17741 fashion. The mapping between keys and KeyCodes cannot be
17742 changed.
17743
17744 A KeySym is an encoding of a symbol on the cap of a key. The
17745 set of defined KeySyms includes the ISO Latin character sets
17746 (1-4), Katakana, Arabic, Cyrillic, Greek, Technical, Special,
17747 Publishing, APL, Hebrew, Thai, Korean and a miscellany of keys
17748 found on keyboards (Return, Help, Tab, and so on). To the
17749 extent possible, these sets are derived from international
17750 standards. In areas where no standards exist, some of these
17751 sets are derived from Digital Equipment Corporation standards.
17752 The list of defined symbols can be found in <X11/keysymdef.h>.
17753 Unfortunately, some C preprocessors have limits on the number
17754 of defined symbols. If you must use KeySyms not in the Latin
17755 1-4, Greek, and miscellaneous classes, you may have to define a
17756 symbol for those sets. Most applications usually only include
17757 <X11/keysym.h>, which defines symbols for ISO Latin 1-4, Greek,
17758 and miscellaneous.
17759
17760 A list of KeySyms is associated with each KeyCode. The list is
17761 intended to convey the set of symbols on the corresponding key.
17762 If the list (ignoring trailing NoSymbol entries) is a single
17763 KeySym ``K'', then the list is treated as if it were the list
17764 ``K NoSymbol K NoSymbol''. If the list (ignoring trailing
17765 NoSymbol entries) is a pair of KeySyms ``K1 K2'', then the list
17766 is treated as if it were the list ``K1 K2 K1 K2''. If the list
17767 (ignoring trailing NoSymbol entries) is a triple of KeySyms
17768 ``K1 K2 K3'', then the list is treated as if it were the list
17769 ``K1 K2 K3 NoSymbol''. When an explicit ``void'' element is
17770 desired in the list, the value VoidSymbol can be used.
17771
17772 The first four elements of the list are split into two groups
17773 of KeySyms. Group 1 contains the first and second KeySyms;
17774 Group 2 contains the third and fourth KeySyms. Within each
17775 group, if the second element of the group is NoSymbol, then the
17776 group should be treated as if the second element were the same
17777 as the first element, except when the first element is an
17778 alphabetic KeySym ``K'' for which both lowercase and uppercase
17779 forms are defined. In that case, the group should be treated as
17780 if the first element were the lowercase form of ``K'' and the
17781 second element were the uppercase form of ``K''.
17782
17783 The standard rules for obtaining a KeySym from a KeyPress event
17784 make use of only the Group 1 and Group 2 KeySyms; no
17785 interpretation of other KeySyms in the list is given. Which
17786 group to use is determined by the modifier state. Switching
17787 between groups is controlled by the KeySym named MODE SWITCH,
17788 by attaching that KeySym to some KeyCode and attaching that
17789 KeyCode to any one of the modifiers Mod1 through Mod5. This
17790 modifier is called the group modifier. For any KeyCode, Group 1
17791 is used when the group modifier is off, and Group 2 is used
17792 when the group modifier is on.
17793
17794 The Lock modifier is interpreted as CapsLock when the KeySym
17795 named XK_Caps_Lock is attached to some KeyCode and that KeyCode
17796 is attached to the Lock modifier. The Lock modifier is
17797 interpreted as ShiftLock when the KeySym named XK_Shift_Lock is
17798 attached to some KeyCode and that KeyCode is attached to the
17799 Lock modifier. If the Lock modifier could be interpreted as
17800 both CapsLock and ShiftLock, the CapsLock interpretation is
17801 used.
17802
17803 The operation of keypad keys is controlled by the KeySym named
17804 XK_Num_Lock, by attaching that KeySym to some KeyCode and
17805 attaching that KeyCode to any one of the modifiers Mod1 through
17806 Mod5. This modifier is called the numlock modifier. The
17807 standard KeySyms with the prefix ``XK_KP_'' in their name are
17808 called keypad KeySyms; these are KeySyms with numeric value in
17809 the hexadecimal range 0xFF80 to 0xFFBD inclusive. In addition,
17810 vendor-specific KeySyms in the hexadecimal range 0x11000000 to
17811 0x1100FFFF are also keypad KeySyms.
17812
17813 Within a group, the choice of KeySym is determined by applying
17814 the first rule that is satisfied from the following list:
17815 * The numlock modifier is on and the second KeySym is a
17816 keypad KeySym. In this case, if the Shift modifier is on,
17817 or if the Lock modifier is on and is interpreted as
17818 ShiftLock, then the first KeySym is used, otherwise the
17819 second KeySym is used.
17820 * The Shift and Lock modifiers are both off. In this case,
17821 the first KeySym is used.
17822 * The Shift modifier is off, and the Lock modifier is on and
17823 is interpreted as CapsLock. In this case, the first KeySym
17824 is used, but if that KeySym is lowercase alphabetic, then
17825 the corresponding uppercase KeySym is used instead.
17826 * The Shift modifier is on, and the Lock modifier is on and
17827 is interpreted as CapsLock. In this case, the second KeySym
17828 is used, but if that KeySym is lowercase alphabetic, then
17829 the corresponding uppercase KeySym is used instead.
17830 * The Shift modifier is on, or the Lock modifier is on and is
17831 interpreted as ShiftLock, or both. In this case, the second
17832 KeySym is used.
17833
17834 No spatial geometry of the symbols on the key is defined by
17835 their order in the KeySym list, although a geometry might be
17836 defined on a server-specific basis. The X server does not use
17837 the mapping between KeyCodes and KeySyms. Rather, it merely
17838 stores it for reading and writing by clients.
17839
17840 To obtain the legal KeyCodes for a display, use
17841 XDisplayKeycodes.
17842
17843 XDisplayKeycodes(Display *display, int *min_keycodes_return,
17844 int *max_keycodes_return);
17845
17846 display
17847
17848 Specifies the connection to the X server.
17849
17850 min_keycodes_return
17851
17852 Returns the minimum number of KeyCodes.
17853
17854 max_keycodes_return
17855
17856 Returns the maximum number of KeyCodes.
17857
17858 The XDisplayKeycodes function returns the min-keycodes and
17859 max-keycodes supported by the specified display. The minimum
17860 number of KeyCodes returned is never less than 8, and the
17861 maximum number of KeyCodes returned is never greater than 255.
17862 Not all KeyCodes in this range are required to have
17863 corresponding keys.
17864
17865 To obtain the symbols for the specified KeyCodes, use
17866 XGetKeyboardMapping.
17867
17868 KeySym *XGetKeyboardMapping(Display *display, KeyCode
17869 first_keycode, int keycode_count, int
17870 *keysyms_per_keycode_return);
17871
17872 display
17873
17874 Specifies the connection to the X server.
17875
17876 first_keycode
17877
17878 Specifies the first KeyCode that is to be returned.
17879
17880 keycode_count
17881
17882 Specifies the number of KeyCodes that are to be returned.
17883
17884 keysyms_per_keycode_return
17885
17886 Returns the number of KeySyms per KeyCode.
17887
17888 The XGetKeyboardMapping function returns the symbols for the
17889 specified number of KeyCodes starting with first_keycode. The
17890 value specified in first_keycode must be greater than or equal
17891 to min_keycode as returned by XDisplayKeycodes, or a BadValue
17892 error results. In addition, the following expression must be
17893 less than or equal to max_keycode as returned by
17894 XDisplayKeycodes:
17895
17896first_keycode + keycode_count - 1
17897
17898 If this is not the case, a BadValue error results. The number
17899 of elements in the KeySyms list is:
17900
17901keycode_count * keysyms_per_keycode_return
17902
17903 KeySym number N, counting from zero, for KeyCode K has the
17904 following index in the list, counting from zero:
17905(K - first_code) * keysyms_per_code_return + N
17906
17907 The X server arbitrarily chooses the keysyms_per_keycode_return
17908 value to be large enough to report all requested symbols. A
17909 special KeySym value of NoSymbol is used to fill in unused
17910 elements for individual KeyCodes. To free the storage returned
17911 by XGetKeyboardMapping, use XFree.
17912
17913 XGetKeyboardMapping can generate a BadValue error.
17914
17915 To change the keyboard mapping, use XChangeKeyboardMapping.
17916
17917 XChangeKeyboardMapping(Display *display, int first_keycode, int
17918 keysyms_per_keycode, KeySym *keysyms, int num_codes);
17919
17920 display
17921
17922 Specifies the connection to the X server.
17923
17924 first_keycode
17925
17926 Specifies the first KeyCode that is to be changed.
17927
17928 keysyms_per_keycode
17929
17930 Specifies the number of KeySyms per KeyCode.
17931
17932 keysyms
17933
17934 Specifies an array of KeySyms.
17935
17936 num_codes
17937
17938 Specifies the number of KeyCodes that are to be changed.
17939
17940 The XChangeKeyboardMapping function defines the symbols for the
17941 specified number of KeyCodes starting with first_keycode. The
17942 symbols for KeyCodes outside this range remain unchanged. The
17943 number of elements in keysyms must be:
17944
17945num_codes * keysyms_per_keycode
17946
17947 The specified first_keycode must be greater than or equal to
17948 min_keycode returned by XDisplayKeycodes, or a BadValue error
17949 results. In addition, the following expression must be less
17950 than or equal to max_keycode as returned by XDisplayKeycodes,
17951 or a BadValue error results:
17952
17953first_keycode + num_codes - 1
17954
17955 KeySym number N, counting from zero, for KeyCode K has the
17956 following index in keysyms, counting from zero:
17957
17958(K - first_keycode) * keysyms_per_keycode + N
17959
17960 The specified keysyms_per_keycode can be chosen arbitrarily by
17961 the client to be large enough to hold all desired symbols. A
17962 special KeySym value of NoSymbol should be used to fill in
17963 unused elements for individual KeyCodes. It is legal for
17964 NoSymbol to appear in nontrailing positions of the effective
17965 list for a KeyCode. XChangeKeyboardMapping generates a
17966 MappingNotify event.
17967
17968 There is no requirement that the X server interpret this
17969 mapping. It is merely stored for reading and writing by
17970 clients.
17971
17972 XChangeKeyboardMapping can generate BadAlloc and BadValue
17973 errors.
17974
17975 The next six functions make use of the XModifierKeymap data
17976 structure, which contains:
17977
17978
17979
17980typedef struct {
17981 int max_keypermod; /* This server's max number of keys per
17982modifier */
17983 KeyCode *modifiermap; /* An 8 by max_keypermod array of the mo
17984difiers */
17985} XModifierKeymap;
17986
17987 To create an XModifierKeymap structure, use XNewModifiermap.
17988
17989 XModifierKeymap *XNewModifiermap(int max_keys_per_mod);
17990
17991 max_keys_per_mod
17992
17993 Specifies the number of KeyCode entries preallocated to the
17994 modifiers in the map.
17995
17996 The XNewModifiermap function returns a pointer to
17997 XModifierKeymap structure for later use.
17998
17999 To add a new entry to an XModifierKeymap structure, use
18000 XInsertModifiermapEntry.
18001
18002 XModifierKeymap *XInsertModifiermapEntry(XModifierKeymap
18003 *modmap, KeyCode keycode_entry, int modifier);
18004
18005 modmap
18006
18007 Specifies the XModifierKeymap structure.
18008
18009 keycode_entry
18010
18011 Specifies the KeyCode.
18012
18013 modifier
18014
18015 Specifies the modifier.
18016
18017 The XInsertModifiermapEntry function adds the specified KeyCode
18018 to the set that controls the specified modifier and returns the
18019 resulting XModifierKeymap structure (expanded as needed).
18020
18021 To delete an entry from an XModifierKeymap structure, use
18022 XDeleteModifiermapEntry.
18023
18024 XModifierKeymap *XDeleteModifiermapEntry(XModifierKeymap
18025 *modmap, KeyCode keycode_entry, int modifier);
18026
18027 modmap
18028
18029 Specifies the XModifierKeymap structure.
18030
18031 keycode_entry
18032
18033 Specifies the KeyCode.
18034
18035 modifier
18036
18037 Specifies the modifier.
18038
18039 The XDeleteModifiermapEntry function deletes the specified
18040 KeyCode from the set that controls the specified modifier and
18041 returns a pointer to the resulting XModifierKeymap structure.
18042
18043 To destroy an XModifierKeymap structure, use XFreeModifiermap.
18044
18045 XFreeModifiermap(XModifierKeymap *modmap);
18046
18047 modmap
18048
18049 Specifies the XModifierKeymap structure.
18050
18051 The XFreeModifiermap function frees the specified
18052 XModifierKeymap structure.
18053
18054 To set the KeyCodes to be used as modifiers, use
18055 XSetModifierMapping.
18056
18057 int XSetModifierMapping(Display *display, XModifierKeymap
18058 *modmap);
18059
18060 display
18061
18062 Specifies the connection to the X server.
18063
18064 modmap
18065
18066 Specifies the XModifierKeymap structure.
18067
18068 The XSetModifierMapping function specifies the KeyCodes of the
18069 keys (if any) that are to be used as modifiers. If it succeeds,
18070 the X server generates a MappingNotify event, and
18071 XSetModifierMapping returns MappingSuccess. X permits at most 8
18072 modifier keys. If more than 8 are specified in the
18073 XModifierKeymap structure, a BadLength error results.
18074
18075 The modifiermap member of the XModifierKeymap structure
18076 contains 8 sets of max_keypermod KeyCodes, one for each
18077 modifier in the order Shift, Lock, Control, Mod1, Mod2, Mod3,
18078 Mod4, and Mod5. Only nonzero KeyCodes have meaning in each set,
18079 and zero KeyCodes are ignored. In addition, all of the nonzero
18080 KeyCodes must be in the range specified by min_keycode and
18081 max_keycode in the Display structure, or a BadValue error
18082 results.
18083
18084 An X server can impose restrictions on how modifiers can be
18085 changed, for example, if certain keys do not generate up
18086 transitions in hardware, if auto-repeat cannot be disabled on
18087 certain keys, or if multiple modifier keys are not supported.
18088 If some such restriction is violated, the status reply is
18089 MappingFailed, and none of the modifiers are changed. If the
18090 new KeyCodes specified for a modifier differ from those
18091 currently defined and any (current or new) keys for that
18092 modifier are in the logically down state, XSetModifierMapping
18093 returns MappingBusy, and none of the modifiers is changed.
18094
18095 XSetModifierMapping can generate BadAlloc and BadValue errors.
18096
18097 To obtain the KeyCodes used as modifiers, use
18098 XGetModifierMapping.
18099
18100 XModifierKeymap *XGetModifierMapping(Display *display);
18101
18102 display
18103
18104 Specifies the connection to the X server.
18105
18106 The XGetModifierMapping function returns a pointer to a newly
18107 created XModifierKeymap structure that contains the keys being
18108 used as modifiers. The structure should be freed after use by
18109 calling XFreeModifiermap. If only zero values appear in the set
18110 for any modifier, that modifier is disabled.
18111
18112Chapter 13. Locales and Internationalized Text Functions
18113
18114 Table of Contents
18115
18116 X Locale Management
18117 Locale and Modifier Dependencies
18118 Variable Argument Lists
18119 Output Methods
18120
18121 Output Method Overview
18122 Output Method Functions
18123 X Output Method Values
18124 Output Context Functions
18125 Output Context Values
18126 Creating and Freeing a Font Set
18127 Obtaining Font Set Metrics
18128 Drawing Text Using Font Sets
18129
18130 Input Methods
18131
18132 Input Method Overview
18133 Input Method Management
18134 Input Method Functions
18135 Input Method Values
18136 Input Context Functions
18137 Input Context Values
18138 Input Method Callback Semantics
18139 Event Filtering
18140 Getting Keyboard Input
18141 Input Method Conventions
18142
18143 String Constants
18144
18145 An internationalized application is one that is adaptable to
18146 the requirements of different native languages, local customs,
18147 and character string encodings. The process of adapting the
18148 operation to a particular native language, local custom, or
18149 string encoding is called localization. A goal of
18150 internationalization is to permit localization without program
18151 source modifications or recompilation.
18152
18153 As one of the localization mechanisms, Xlib provides an X Input
18154 Method (XIM) functional interface for internationalized text
18155 input and an X Output Method (XOM) functional interface for
18156 internationalized text output.
18157
18158 Internationalization in X is based on the concept of a locale.
18159 A locale defines the localized behavior of a program at run
18160 time. Locales affect Xlib in its:
18161 * Encoding and processing of input method text
18162 * Encoding of resource files and values
18163 * Encoding and imaging of text strings
18164 * Encoding and decoding for inter-client text communication
18165
18166 o Encoding and decoding for inter-client text communication
18167 Characters from various languages are represented in a computer
18168 using an encoding. Different languages have different
18169 encodings, and there are even different encodings for the same
18170 characters in the same language.
18171
18172 This chapter defines support for localized text imaging and
18173 text input and describes the locale mechanism that controls all
18174 locale-dependent Xlib functions. Sets of functions are provided
18175 for multibyte (char *) text as well as wide character (wchar_t)
18176 text in the form supported by the host C language environment.
18177 The multibyte and wide character functions are equivalent
18178 except for the form of the text argument.
18179
18180 The Xlib internationalization functions are not meant to
18181 provide support for multilingual applications (mixing multiple
18182 languages within a single piece of text), but they make it
18183 possible to implement applications that work in limited fashion
18184 with more than one language in independent contexts.
18185
18186 The remainder of this chapter discusses:
18187 * X locale management
18188 * Locale and modifier dependencies
18189 * Variable argument lists
18190 * Output methods
18191 * Input methods
18192 * String constants
18193
18194X Locale Management
18195
18196 X supports one or more of the locales defined by the host
18197 environment. On implementations that conform to the ANSI C
18198 library, the locale announcement method is setlocale. This
18199 function configures the locale operation of both the host C
18200 library and Xlib. The operation of Xlib is governed by the
18201 LC_CTYPE category; this is called the current locale. An
18202 implementation is permitted to provide implementation-dependent
18203 mechanisms for announcing the locale in addition to setlocale.
18204
18205 On implementations that do not conform to the ANSI C library,
18206 the locale announcement method is Xlib
18207 implementation-dependent.
18208
18209 The mechanism by which the semantic operation of Xlib is
18210 defined for a specific locale is implementation-dependent.
18211
18212 X is not required to support all the locales supported by the
18213 host. To determine if the current locale is supported by X, use
18214 XSupportsLocale.
18215
18216 Bool XSupportsLocale(void);
18217
18218 The XSupportsLocale function returns True if Xlib functions are
18219 capable of operating under the current locale. If it returns
18220 False, Xlib locale-dependent functions for which the
18221 XLocaleNotSupported return status is defined will return
18222 XLocaleNotSupported. Other Xlib locale-dependent routines will
18223 operate in the ``C'' locale.
18224
18225 The client is responsible for selecting its locale and X
18226 modifiers. Clients should provide a means for the user to
18227 override the clients' locale selection at client invocation.
18228 Most single-display X clients operate in a single locale for
18229 both X and the host processing environment. They will configure
18230 the locale by calling three functions: the host locale
18231 configuration function, XSupportsLocale, and
18232 XSetLocaleModifiers.
18233
18234 The semantics of certain categories of X internationalization
18235 capabilities can be configured by setting modifiers. Modifiers
18236 are named by implementation-dependent and locale-specific
18237 strings. The only standard use for this capability at present
18238 is selecting one of several styles of keyboard input method.
18239
18240 To configure Xlib locale modifiers for the current locale, use
18241 XSetLocaleModifiers.
18242
18243 char *XSetLocaleModifiers(char *modifier_list);
18244
18245 modifier_list
18246
18247 Specifies the modifiers.
18248
18249 The XSetLocaleModifiers function sets the X modifiers for the
18250 current locale setting. The modifier_list argument is a
18251 null-terminated string of the form ``{@category=value}'', that
18252 is, having zero or more concatenated ``@category=value''
18253 entries, where category is a category name and value is the
18254 (possibly empty) setting for that category. The values are
18255 encoded in the current locale. Category names are restricted to
18256 the POSIX Portable Filename Character Set.
18257
18258 The local host X locale modifiers announcer (on POSIX-compliant
18259 systems, the XMODIFIERS environment variable) is appended to
18260 the modifier_list to provide default values on the local host.
18261 If a given category appears more than once in the list, the
18262 first setting in the list is used. If a given category is not
18263 included in the full modifier list, the category is set to an
18264 implementation-dependent default for the current locale. An
18265 empty value for a category explicitly specifies the
18266 implementation-dependent default.
18267
18268 If the function is successful, it returns a pointer to a
18269 string. The contents of the string are such that a subsequent
18270 call with that string (in the same locale) will restore the
18271 modifiers to the same settings. If modifier_list is a NULL
18272 pointer, XSetLocaleModifiers also returns a pointer to such a
18273 string, and the current locale modifiers are not changed.
18274
18275 If invalid values are given for one or more modifier categories
18276 supported by the locale, a NULL pointer is returned, and none
18277 of the current modifiers are changed.
18278
18279 At program startup, the modifiers that are in effect are
18280 unspecified until the first successful call to set them.
18281 Whenever the locale is changed, the modifiers that are in
18282 effect become unspecified until the next successful call to set
18283 them. Clients should always call XSetLocaleModifiers with a
18284 non-NULL modifier_list after setting the locale before they
18285 call any locale-dependent Xlib routine.
18286
18287 The only standard modifier category currently defined is
18288 ``im'', which identifies the desired input method. The values
18289 for input method are not standardized. A single locale may use
18290 multiple input methods, switching input method under user
18291 control. The modifier may specify the initial input method in
18292 effect or an ordered list of input methods. Multiple input
18293 methods may be specified in a single im value string in an
18294 implementation-dependent manner.
18295
18296 The returned modifiers string is owned by Xlib and should not
18297 be modified or freed by the client. It may be freed by Xlib
18298 after the current locale or modifiers are changed. Until freed,
18299 it will not be modified by Xlib.
18300
18301 The recommended procedure for clients initializing their locale
18302 and modifiers is to obtain locale and modifier announcers
18303 separately from one of the following prioritized sources:
18304 * A command line option
18305 * A resource
18306 * The empty string ("")
18307
18308 The first of these that is defined should be used. Note that
18309 when a locale command line option or locale resource is
18310 defined, the effect should be to set all categories to the
18311 specified locale, overriding any category-specific settings in
18312 the local host environment.
18313
18314Locale and Modifier Dependencies
18315
18316 The internationalized Xlib functions operate in the current
18317 locale configured by the host environment and X locale
18318 modifiers set by XSetLocaleModifiers or in the locale and
18319 modifiers configured at the time some object supplied to the
18320 function was created. For each locale-dependent function, the
18321 following table describes the locale (and modifiers)
18322 dependency:
18323 Locale from Affects the Function In
18324 Locale Query/Configuration:
18325 setlocale XSupportsLocale Locale queried
18326 XSetLocaleModifiers Locale modified
18327 Resources:
18328 setlocale
18329
18330 XrmGetFileDatabase
18331
18332 XrmGetStringDatabase
18333 Locale of XrmDatabase
18334 XrmDatabase
18335
18336 XrmPutFileDatabase
18337
18338 XrmLocaleOfDatabase
18339 Locale of XrmDatabase
18340 Setting Standard Properties:
18341 setlocale XmbSetWMProperties Encoding of supplied/returned text
18342 (some WM_ property text in environment locale)
18343 setlocale
18344
18345 XmbTextPropertyToTextList
18346
18347 XwcTextPropertyToTextList
18348
18349 XmbTextListToTextProperty
18350
18351 XwcTextListToTextProperty
18352 Encoding of supplied/returned text
18353 Text Input:
18354 setlocale XOpenIM XIM input method selection
18355 XRegisterIMInstantiateCallback XIM selection
18356 XUnregisterIMInstantiateCallback XIM selection
18357 XIM XCreateIC XIC input method configuration
18358 XLocaleOfIM, and so on Queried locale
18359 XIC XmbLookupString Keyboard layout
18360 XwcLookupString Encoding of returned text
18361 Text Drawing:
18362 setlocale XOpenOM XOM output method selection
18363 XCreateFontSet Charsets of fonts in XFontSet
18364 XOM XCreateOC XOC output method configuration
18365 XLocaleOfOM, and so on Queried locale
18366 XFontSet XmbDrawText, Locale of supplied text
18367 XwcDrawText, and so on Locale of supplied text
18368
18369 XExtentsOfFontSet, and so on
18370
18371 XmbTextExtents,
18372
18373 XwcTextExtents, and so on
18374 Locale-dependent metrics
18375 Xlib Errors:
18376 setlocale
18377
18378 XGetErrorDatabaseText,
18379
18380 XGetErrorText, and so on
18381 Locale of error message
18382
18383 Clients may assume that a locale-encoded text string returned
18384 by an X function can be passed to a C library routine, or vice
18385 versa, if the locale is the same at the two calls.
18386
18387 All text strings processed by internationalized Xlib functions
18388 are assumed to begin in the initial state of the encoding of
18389 the locale, if the encoding is state-dependent.
18390
18391 All Xlib functions behave as if they do not change the current
18392 locale or X modifier setting. (This means that if they do
18393 change locale or call XSetLocaleModifiers with a non-NULL
18394 argument, they must save and restore the current state on entry
18395 and exit.) Also, Xlib functions on implementations that conform
18396 to the ANSI C library do not alter the global state associated
18397 with the ANSI C functions mblen, mbtowc, wctomb, and strtok.
18398
18399Variable Argument Lists
18400
18401 Various functions in this chapter have arguments that conform
18402 to the ANSI C variable argument list calling convention. Each
18403 function denoted with an argument of the form ``...'' takes a
18404 variable-length list of name and value pairs, where each name
18405 is a string and each value is of type XPointer. A name argument
18406 that is NULL identifies the end of the list.
18407
18408 A variable-length argument list may contain a nested list. If
18409 the name XNVaNestedList is specified in place of an argument
18410 name, then the following value is interpreted as an
18411 XVaNestedList value that specifies a list of values logically
18412 inserted into the original list at the point of declaration. A
18413 NULL identifies the end of a nested list.
18414
18415 To allocate a nested variable argument list dynamically, use
18416 XVaCreateNestedList.
18417
18418 XVaNestedList XVaCreateNestedList(int dummy);
18419
18420 dummy
18421
18422 Specifies an unused argument (required by ANSI C).
18423
18424 ...
18425
18426 Specifies the variable length argument list(Al.
18427
18428 The XVaCreateNestedList function allocates memory and copies
18429 its arguments into a single list pointer, which may be used as
18430 a value for arguments requiring a list value. Any entries are
18431 copied as specified. Data passed by reference is not copied;
18432 the caller must ensure data remains valid for the lifetime of
18433 the nested list. The list should be freed using XFree when it
18434 is no longer needed.
18435
18436Output Methods
18437
18438 This section provides discussions of the following X Output
18439 Method (XOM) topics:
18440 * Output method overview
18441 * Output method functions
18442 * Output method values
18443 * Output context functions
18444 * Output context values
18445 * Creating and freeing a font set
18446 * Obtaining font set metrics
18447 * Drawing text using font sets
18448
18449Output Method Overview
18450
18451 Locale-dependent text may include one or more text components,
18452 each of which may require different fonts and character set
18453 encodings. In some languages, each component might have a
18454 different drawing direction, and some components might contain
18455 context-dependent characters that change shape based on
18456 relationships with neighboring characters.
18457
18458 When drawing such locale-dependent text, some locale-specific
18459 knowledge is required; for example, what fonts are required to
18460 draw the text, how the text can be separated into components,
18461 and which fonts are selected to draw each component. Further,
18462 when bidirectional text must be drawn, the internal
18463 representation order of the text must be changed into the
18464 visual representation order to be drawn.
18465
18466 An X Output Method provides a functional interface so that
18467 clients do not have to deal directly with such locale-dependent
18468 details. Output methods provide the following capabilities:
18469 * Creating a set of fonts required to draw locale-dependent
18470 text.
18471 * Drawing locale-dependent text with a font set without the
18472 caller needing to be aware of locale dependencies.
18473 * Obtaining the escapement and extents in pixels of
18474 locale-dependent text.
18475 * Determining if bidirectional or context-dependent drawing
18476 is required in a specific locale with a specific font set.
18477
18478 Two different abstractions are used in the representation of
18479 the output method for clients.
18480
18481 The abstraction used to communicate with an output method is an
18482 opaque data structure represented by the XOM data type. The
18483 abstraction for representing the state of a particular output
18484 thread is called an output context. The Xlib representation of
18485 an output context is an XOC, which is compatible with XFontSet
18486 in terms of its functional interface, but is a broader, more
18487 generalized abstraction.
18488
18489Output Method Functions
18490
18491 To open an output method, use XOpenOM.
18492
18493 XOM XOpenOM(Display *display, XrmDatabase db, char *res_name,
18494 char *res_class);
18495
18496 display
18497
18498 Specifies the connection to the X server.
18499
18500 db
18501
18502 Specifies a pointer to the resource database.
18503
18504 res_name
18505
18506 Specifies the full resource name of the application.
18507
18508 res_class
18509
18510 Specifies the full class name of the application.
18511
18512 The XOpenOM function opens an output method matching the
18513 current locale and modifiers specification. The current locale
18514 and modifiers are bound to the output method when XOpenOM is
18515 called. The locale associated with an output method cannot be
18516 changed.
18517
18518 The specific output method to which this call will be routed is
18519 identified on the basis of the current locale and modifiers.
18520 XOpenOM will identify a default output method corresponding to
18521 the current locale. That default can be modified using
18522 XSetLocaleModifiers to set the output method modifier.
18523
18524 The db argument is the resource database to be used by the
18525 output method for looking up resources that are private to the
18526 output method. It is not intended that this database be used to
18527 look up values that can be set as OC values in an output
18528 context. If db is NULL, no database is passed to the output
18529 method.
18530
18531 The res_name and res_class arguments specify the resource name
18532 and class of the application. They are intended to be used as
18533 prefixes by the output method when looking up resources that
18534 are common to all output contexts that may be created for this
18535 output method. The characters used for resource names and
18536 classes must be in the X Portable Character Set. The resources
18537 looked up are not fully specified if res_name or res_class is
18538 NULL.
18539
18540 The res_name and res_class arguments are not assumed to exist
18541 beyond the call to XOpenOM. The specified resource database is
18542 assumed to exist for the lifetime of the output method.
18543
18544 XOpenOM returns NULL if no output method could be opened.
18545
18546 To close an output method, use XCloseOM.
18547
18548 Status XCloseOM(XOM om);
18549
18550 om
18551
18552 Specifies the output method.
18553
18554 The XCloseOM function closes the specified output method.
18555
18556 To set output method attributes, use XSetOMValues.
18557
18558 char *XSetOMValues(XOM om);
18559
18560 om
18561
18562 Specifies the output method.
18563
18564 ...
18565
18566 Specifies the variable-length argument list to set XOM values.
18567
18568 The XSetOMValues function presents a variable argument list
18569 programming interface for setting properties or features of the
18570 specified output method. This function returns NULL if it
18571 succeeds; otherwise, it returns the name of the first argument
18572 that could not be obtained.
18573
18574 No standard arguments are currently defined by Xlib.
18575
18576 To query an output method, use XGetOMValues.
18577
18578 char *XGetOMValues(XOM om);
18579
18580 om
18581
18582 Specifies the output method.
18583
18584 ...
18585
18586 Specifies the variable-length argument list to get XOM values.
18587
18588 The XGetOMValues function presents a variable argument list
18589 programming interface for querying properties or features of
18590 the specified output method. This function returns NULL if it
18591 succeeds; otherwise, it returns the name of the first argument
18592 that could not be obtained.
18593
18594 To obtain the display associated with an output method, use
18595 XDisplayOfOM.
18596
18597 Display *XDisplayOfOM(XOM om);
18598
18599 om
18600
18601 Specifies the output method.
18602
18603 The XDisplayOfOM function returns the display associated with
18604 the specified output method.
18605
18606 To get the locale associated with an output method, use
18607 XLocaleOfOM.
18608
18609 char *XLocaleOfOM(XOM om);
18610
18611 om
18612
18613 Specifies the output method.
18614
18615 The XLocaleOfOM returns the locale associated with the
18616 specified output method.
18617
18618X Output Method Values
18619
18620 The following table describes how XOM values are interpreted by
18621 an output method. The first column lists the XOM values. The
18622 second column indicates how each of the XOM values are treated
18623 by a particular output style.
18624
18625 The following key applies to this table.
18626 Key Explanation
18627 G This value may be read using XGetOMValues.
18628
18629 XOM Value Key
18630 XNRequiredCharSet G
18631 XNQueryOrientation G
18632 XNDirectionalDependentDrawing G
18633 XNContextualDrawing G
18634
18635Required Char Set
18636
18637 The XNRequiredCharSet argument returns the list of charsets
18638 that are required for loading the fonts needed for the locale.
18639 The value of the argument is a pointer to a structure of type
18640 XOMCharSetList.
18641
18642 The XOMCharSetList structure is defined as follows:
18643
18644
18645typedef struct {
18646 int charset_count;
18647 char **charset_list;
18648} XOMCharSetList;
18649
18650 The charset_list member is a list of one or more
18651 null-terminated charset names, and the charset_count member is
18652 the number of charset names.
18653
18654 The required charset list is owned by Xlib and should not be
18655 modified or freed by the client. It will be freed by a call to
18656 XCloseOM with the associated XOM. Until freed, its contents
18657 will not be modified by Xlib.
18658
18659Query Orientation
18660
18661 The XNQueryOrientation argument returns the global orientation
18662 of text when drawn. Other than XOMOrientation_LTR_TTB, the set
18663 of orientations supported is locale-dependent. The value of the
18664 argument is a pointer to a structure of type XOMOrientation.
18665 Clients are responsible for freeing the XOMOrientation
18666 structure by using XFree; this also frees the contents of the
18667 structure.
18668
18669
18670typedef struct {
18671 int num_orientation;
18672 XOrientation *orientation; /* Input Text description */
18673} XOMOrientation;
18674
18675typedef enum {
18676 XOMOrientation_LTR_TTB,
18677 XOMOrientation_RTL_TTB,
18678 XOMOrientation_TTB_LTR,
18679 XOMOrientation_TTB_RTL,
18680 XOMOrientation_Context
18681} XOrientation;
18682
18683 The possible value for XOrientation may be:
18684 * XOMOrientation_LTR_TTB left-to-right, top-to-bottom global
18685 orientation
18686 * XOMOrientation_RTL_TTB right-to-left, top-to-bottom global
18687 orientation
18688 * XOMOrientation_TTB_LTR top-to-bottom, left-to-right global
18689 orientation
18690 * XOMOrientation_TTB_RTL top-to-bottom, right-to-left global
18691 orientation
18692 * XOMOrientation_Context contextual global orientation
18693
18694Directional Dependent Drawing
18695
18696 The XNDirectionalDependentDrawing argument indicates whether
18697 the text rendering functions implement implicit handling of
18698 directional text. If this value is True, the output method has
18699 knowledge of directional dependencies and reorders text as
18700 necessary when rendering text. If this value is False, the
18701 output method does not implement any directional text handling,
18702 and all character directions are assumed to be left-to-right.
18703
18704 Regardless of the rendering order of characters, the origins of
18705 all characters are on the primary draw direction side of the
18706 drawing origin.
18707
18708 This OM value presents functionality identical to the
18709 XDirectionalDependentDrawing function.
18710
18711Context Dependent Drawing
18712
18713 The XNContextualDrawing argument indicates whether the text
18714 rendering functions implement implicit context-dependent
18715 drawing. If this value is True, the output method has knowledge
18716 of context dependencies and performs character shape editing,
18717 combining glyphs to present a single character as necessary.
18718 The actual shape editing is dependent on the locale
18719 implementation and the font set used.
18720
18721 This OM value presents functionality identical to the
18722 XContextualDrawing function.
18723
18724Output Context Functions
18725
18726 An output context is an abstraction that contains both the data
18727 required by an output method and the information required to
18728 display that data. There can be multiple output contexts for
18729 one output method. The programming interfaces for creating,
18730 reading, or modifying an output context use a variable argument
18731 list. The name elements of the argument lists are referred to
18732 as XOC values. It is intended that output methods be controlled
18733 by these XOC values. As new XOC values are created, they should
18734 be registered with the X Consortium. An XOC can be used
18735 anywhere an XFontSet can be used, and vice versa; XFontSet is
18736 retained for compatibility with previous releases. The concepts
18737 of output methods and output contexts include broader, more
18738 generalized abstraction than font set, supporting complex and
18739 more intelligent text display, and dealing not only with
18740 multiple fonts but also with context dependencies. However,
18741 XFontSet is widely used in several interfaces, so XOC is
18742 defined as an upward compatible type of XFontSet.
18743
18744 To create an output context, use XCreateOC.
18745
18746 XOC XCreateOC(XOM om);
18747
18748 om
18749
18750 Specifies the output method.
18751
18752 ...
18753
18754 Specifies the variable-length argument list to set XOC values.
18755
18756 The XCreateOC function creates an output context within the
18757 specified output method.
18758
18759 The base font names argument is mandatory at creation time, and
18760 the output context will not be created unless it is provided.
18761 All other output context values can be set later.
18762
18763 XCreateOC returns NULL if no output context could be created.
18764 NULL can be returned for any of the following reasons:
18765 * A required argument was not set.
18766 * A read-only argument was set.
18767 * An argument name is not recognized.
18768 * The output method encountered an output method
18769 implementation-dependent error.
18770
18771 XCreateOC can generate a BadAtom error.
18772
18773 To destroy an output context, use XDestroyOC.
18774
18775 void XDestroyOC(XOC oc);
18776
18777 oc
18778
18779 Specifies the output context.
18780
18781 The XDestroyOC function destroys the specified output context.
18782
18783 To get the output method associated with an output context, use
18784 XOMOfOC.
18785
18786 XOM XOMOfOC(XOC oc);
18787
18788 oc
18789
18790 Specifies the output context.
18791
18792 The XOMOfOC function returns the output method associated with
18793 the specified output context.
18794
18795 Xlib provides two functions for setting and reading output
18796 context values, respectively, XSetOCValues and XGetOCValues.
18797 Both functions have a variable-length argument list. In that
18798 argument list, any XOC value's name must be denoted with a
18799 character string using the X Portable Character Set.
18800
18801 To set XOC values, use XSetOCValues.
18802
18803 char *XSetOCValues(XOC oc);
18804
18805 oc
18806
18807 Specifies the output context.
18808
18809 ...
18810
18811 Specifies the variable-length argument list to set XOC values.
18812
18813 The XSetOCValues function returns NULL if no error occurred;
18814 otherwise, it returns the name of the first argument that could
18815 not be set. An argument might not be set for any of the
18816 following reasons:
18817 * The argument is read-only.
18818 * The argument name is not recognized.
18819 * An implementation-dependent error occurs.
18820
18821 Each value to be set must be an appropriate datum, matching the
18822 data type imposed by the semantics of the argument.
18823
18824 XSetOCValues can generate a BadAtom error.
18825
18826 To obtain XOC values, use XGetOCValues.
18827
18828 char *XGetOCValues(XOC oc);
18829
18830 oc
18831
18832 Specifies the output context.
18833
18834 ...
18835
18836 Specifies the variable-length argument list to get XOC values.
18837
18838 The XGetOCValues function returns NULL if no error occurred;
18839 otherwise, it returns the name of the first argument that could
18840 not be obtained. An argument might not be obtained for any of
18841 the following reasons:
18842 * The argument name is not recognized.
18843 * An implementation-dependent error occurs.
18844
18845 Each argument value following a name must point to a location
18846 where the value is to be stored.
18847
18848Output Context Values
18849
18850 The following table describes how XOC values are interpreted by
18851 an output method. The first column lists the XOC values. The
18852 second column indicates the alternative interfaces that
18853 function identically and are provided for compatibility with
18854 previous releases. The third column indicates how each of the
18855 XOC values is treated.
18856
18857 The following keys apply to this table.
18858 Key Explanation
18859 C This value must be set with XCreateOC.
18860 D This value may be set using XCreateOC. If it is not set,a
18861 default is provided.
18862 G This value may be read using XGetOCValues.
18863 S This value must be set using XSetOCValues.
18864
18865 XOC Value Alternative Interface Key
18866 BaseFontName XCreateFontSet C-G
18867 MissingCharSet XCreateFontSet G
18868 DefaultString XCreateFontSet G
18869 Orientation - D-S-G
18870 ResourceName - S-G
18871 ResourceClass - S-G
18872 FontInfo XFontsOfFontSet G
18873 OMAutomatic - G
18874
18875Base Font Name
18876
18877 The XNBaseFontName argument is a list of base font names that
18878 Xlib uses to load the fonts needed for the locale. The base
18879 font names are a comma-separated list. The string is
18880 null-terminated and is assumed to be in the Host Portable
18881 Character Encoding; otherwise, the result is
18882 implementation-dependent. White space immediately on either
18883 side of a separating comma is ignored.
18884
18885 Use of XLFD font names permits Xlib to obtain the fonts needed
18886 for a variety of locales from a single locale-independent base
18887 font name. The single base font name should name a family of
18888 fonts whose members are encoded in the various charsets needed
18889 by the locales of interest.
18890
18891 An XLFD base font name can explicitly name a charset needed for
18892 the locale. This allows the user to specify an exact font for
18893 use with a charset required by a locale, fully controlling the
18894 font selection.
18895
18896 If a base font name is not an XLFD name, Xlib will attempt to
18897 obtain an XLFD name from the font properties for the font. If
18898 Xlib is successful, the XGetOCValues function will return this
18899 XLFD name instead of the client-supplied name.
18900
18901 This argument must be set at creation time and cannot be
18902 changed. If no fonts exist for any of the required charsets, or
18903 if the locale definition in Xlib requires that a font exist for
18904 a particular charset and a font is not found for that charset,
18905 XCreateOC returns NULL.
18906
18907 When querying for the XNBaseFontName XOC value, XGetOCValues
18908 returns a null-terminated string identifying the base font
18909 names that Xlib used to load the fonts needed for the locale.
18910 This string is owned by Xlib and should not be modified or
18911 freed by the client. The string will be freed by a call to
18912 XDestroyOC with the associated XOC. Until freed, the string
18913 contents will not be modified by Xlib.
18914
18915Missing CharSet
18916
18917 The XNMissingCharSet argument returns the list of required
18918 charsets that are missing from the font set. The value of the
18919 argument is a pointer to a structure of type XOMCharSetList.
18920
18921 If fonts exist for all of the charsets required by the current
18922 locale, charset_list is set to NULL and charset_count is set to
18923 zero. If no fonts exist for one or more of the required
18924 charsets, charset_list is set to a list of one or more
18925 null-terminated charset names for which no fonts exist, and
18926 charset_count is set to the number of missing charsets. The
18927 charsets are from the list of the required charsets for the
18928 encoding of the locale and do not include any charsets to which
18929 Xlib may be able to remap a required charset.
18930
18931 The missing charset list is owned by Xlib and should not be
18932 modified or freed by the client. It will be freed by a call to
18933 XDestroyOC with the associated XOC. Until freed, its contents
18934 will not be modified by Xlib.
18935
18936Default String
18937
18938 When a drawing or measuring function is called with an XOC that
18939 has missing charsets, some characters in the locale will not be
18940 drawable. The XNDefaultString argument returns a pointer to a
18941 string that represents the glyphs that are drawn with this XOC
18942 when the charsets of the available fonts do not include all
18943 glyphs required to draw a character. The string does not
18944 necessarily consist of valid characters in the current locale
18945 and is not necessarily drawn with the fonts loaded for the font
18946 set, but the client can draw or measure the default glyphs by
18947 including this string in a string being drawn or measured with
18948 the XOC.
18949
18950 If the XNDefaultString argument returned the empty string (""),
18951 no glyphs are drawn and the escapement is zero. The returned
18952 string is null-terminated. It is owned by Xlib and should not
18953 be modified or freed by the client. It will be freed by a call
18954 to XDestroyOC with the associated XOC. Until freed, its
18955 contents will not be modified by Xlib.
18956
18957Orientation
18958
18959 The XNOrientation argument specifies the current orientation of
18960 text when drawn. The value of this argument is one of the
18961 values returned by the XGetOMValues function with the
18962 XNQueryOrientation argument specified in the XOrientation list.
18963 The value of the argument is of type XOrientation. When
18964 XNOrientation is queried, the value specifies the current
18965 orientation. When XNOrientation is set, a value is used to set
18966 the current orientation.
18967
18968 When XOMOrientation_Context is set, the text orientation of the
18969 text is determined according to an implementation-defined
18970 method (for example, ISO 6429 control sequences), and the
18971 initial text orientation for locale-dependent Xlib functions is
18972 assumed to be XOMOrientation_LTR_TTB.
18973
18974 The XNOrientation value does not change the prime drawing
18975 direction for Xlib drawing functions.
18976
18977Resource Name and Class
18978
18979 The XNResourceName and XNResourceClass arguments are strings
18980 that specify the full name and class used by the client to
18981 obtain resources for the display of the output context. These
18982 values should be used as prefixes for name and class when
18983 looking up resources that may vary according to the output
18984 context. If these values are not set, the resources will not be
18985 fully specified.
18986
18987 It is not intended that values that can be set as XOM values be
18988 set as resources.
18989
18990 When querying for the XNResourceName or XNResourceClass XOC
18991 value, XGetOCValues returns a null-terminated string. This
18992 string is owned by Xlib and should not be modified or freed by
18993 the client. The string will be freed by a call to XDestroyOC
18994 with the associated XOC or when the associated value is changed
18995 via XSetOCValues. Until freed, the string contents will not be
18996 modified by Xlib.
18997
18998Font Info
18999
19000 The XNFontInfo argument specifies a list of one or more
19001 XFontStruct structures and font names for the fonts used for
19002 drawing by the given output context. The value of the argument
19003 is a pointer to a structure of type XOMFontInfo.
19004
19005
19006
19007typedef struct {
19008 int num_font;
19009 XFontStruct **font_struct_list;
19010 char **font_name_list;
19011} XOMFontInfo;
19012
19013 A list of pointers to the XFontStruct structures is returned to
19014 font_struct_list. A list of pointers to null-terminated,
19015 fully-specified font name strings in the locale of the output
19016 context is returned to font_name_list. The font_name_list order
19017 corresponds to the font_struct_list order. The number of
19018 XFontStruct structures and font names is returned to num_font.
19019
19020 Because it is not guaranteed that a given character will be
19021 imaged using a single font glyph, there is no provision for
19022 mapping a character or default string to the font properties,
19023 font ID, or direction hint for the font for the character. The
19024 client may access the XFontStruct list to obtain these values
19025 for all the fonts currently in use.
19026
19027 Xlib does not guarantee that fonts are loaded from the server
19028 at the creation of an XOC. Xlib may choose to cache font data,
19029 loading it only as needed to draw text or compute text
19030 dimensions. Therefore, existence of the per_char metrics in the
19031 XFontStruct structures in the XFontStructSet is undefined.
19032 Also, note that all properties in the XFontStruct structures
19033 are in the STRING encoding.
19034
19035 The client must not free the XOMFontInfo struct itself; it will
19036 be freed when the XOC is closed.
19037
19038OM Automatic
19039
19040 The XNOMAutomatic argument returns whether the associated
19041 output context was created by XCreateFontSet or not. Because
19042 the XFreeFontSet function not only destroys the output context
19043 but also closes the implicit output method associated with it,
19044 XFreeFontSet should be used with any output context created by
19045 XCreateFontSet. However, it is possible that a client does not
19046 know how the output context was created. Before a client
19047 destroys the output context, it can query whether XNOMAutomatic
19048 is set to determine whether XFreeFontSet or XDestroyOC should
19049 be used to destroy the output context.
19050
19051Creating and Freeing a Font Set
19052
19053 Xlib international text drawing is done using a set of one or
19054 more fonts, as needed for the locale of the text. Fonts are
19055 loaded according to a list of base font names supplied by the
19056 client and the charsets required by the locale. The XFontSet is
19057 an opaque type representing the state of a particular output
19058 thread and is equivalent to the type XOC.
19059
19060 The XCreateFontSet function is a convenience function for
19061 creating an output context using only default values. The
19062 returned XFontSet has an implicitly created XOM. This XOM has
19063 an OM value XNOMAutomatic automatically set to True so that the
19064 output context self indicates whether it was created by
19065 XCreateOC or XCreateFontSet.
19066
19067 XFontSet XCreateFontSet(Display *display, char
19068 *base_font_name_list, char ***missing_charset_list_return, int
19069 *missing_charset_count_return, char **def_string_return);
19070
19071 display
19072
19073 Specifies the connection to the X server.
19074
19075 base_font_name_list
19076
19077 Specifies the base font names.
19078
19079 missing_charset_list_return
19080
19081 Returns the missing charsets.
19082
19083 missing_charset_count_return
19084
19085 Returns the number of missing charsets.
19086
19087 def_string_return
19088
19089 Returns the string drawn for missing charsets.
19090
19091 The XCreateFontSet function creates a font set for the
19092 specified display. The font set is bound to the current locale
19093 when XCreateFontSet is called. The font set may be used in
19094 subsequent calls to obtain font and character information and
19095 to image text in the locale of the font set.
19096
19097 The base_font_name_list argument is a list of base font names
19098 that Xlib uses to load the fonts needed for the locale. The
19099 base font names are a comma-separated list. The string is
19100 null-terminated and is assumed to be in the Host Portable
19101 Character Encoding; otherwise, the result is
19102 implementation-dependent. White space immediately on either
19103 side of a separating comma is ignored.
19104
19105 Use of XLFD font names permits Xlib to obtain the fonts needed
19106 for a variety of locales from a single locale-independent base
19107 font name. The single base font name should name a family of
19108 fonts whose members are encoded in the various charsets needed
19109 by the locales of interest.
19110
19111 An XLFD base font name can explicitly name a charset needed for
19112 the locale. This allows the user to specify an exact font for
19113 use with a charset required by a locale, fully controlling the
19114 font selection.
19115
19116 If a base font name is not an XLFD name, Xlib will attempt to
19117 obtain an XLFD name from the font properties for the font. If
19118 this action is successful in obtaining an XLFD name, the
19119 XBaseFontNameListOfFontSet function will return this XLFD name
19120 instead of the client-supplied name.
19121
19122 Xlib uses the following algorithm to select the fonts that will
19123 be used to display text with the XFontSet.
19124
19125 For each font charset required by the locale, the base font
19126 name list is searched for the first appearance of one of the
19127 following cases that names a set of fonts that exist at the
19128 server:
19129 * The first XLFD-conforming base font name that specifies the
19130 required charset or a superset of the required charset in
19131 its CharSetRegistry and CharSetEncoding fields. The
19132 implementation may use a base font name whose specified
19133 charset is a superset of the required charset, for example,
19134 an ISO8859-1 font for an ASCII charset.
19135 * The first set of one or more XLFD-conforming base font
19136 names that specify one or more charsets that can be
19137 remapped to support the required charset. The Xlib
19138 implementation may recognize various mappings from a
19139 required charset to one or more other charsets and use the
19140 fonts for those charsets. For example, JIS Roman is ASCII
19141 with tilde and backslash replaced by yen and overbar; Xlib
19142 may load an ISO8859-1 font to support this character set if
19143 a JIS Roman font is not available.
19144 * The first XLFD-conforming font name or the first non-XLFD
19145 font name for which an XLFD font name can be obtained,
19146 combined with the required charset (replacing the
19147 CharSetRegistry and CharSetEncoding fields in the XLFD font
19148 name). As in case 1, the implementation may use a charset
19149 that is a superset of the required charset.
19150 * The first font name that can be mapped in some
19151 implementation-dependent manner to one or more fonts that
19152 support imaging text in the charset.
19153
19154 For example, assume that a locale required the charsets:
19155
19156ISO8859-1
19157JISX0208.1983
19158JISX0201.1976
19159GB2312-1980.0
19160
19161 The user could supply a base_font_name_list that explicitly
19162 specifies the charsets, ensuring that specific fonts are used
19163 if they exist. For example:
19164
19165"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
19166-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
19167-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
19168-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
19169
19170 Alternatively, the user could supply a base_font_name_list that
19171 omits the charsets, letting Xlib select font charsets required
19172 for the locale. For example:
19173
19174"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
19175-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
19176-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
19177-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
19178
19179 Alternatively, the user could simply supply a single base font
19180 name that allows Xlib to select from all available fonts that
19181 meet certain minimum XLFD property requirements. For example:
19182
19183"-*-*-*-R-Normal--*-180-100-100-*-*"
19184
19185 If XCreateFontSet is unable to create the font set, either
19186 because there is insufficient memory or because the current
19187 locale is not supported, XCreateFontSet returns NULL,
19188 missing_charset_list_return is set to NULL, and
19189 missing_charset_count_return is set to zero. If fonts exist for
19190 all of the charsets required by the current locale,
19191 XCreateFontSet returns a valid XFontSet,
19192 missing_charset_list_return is set to NULL, and
19193 missing_charset_count_return is set to zero.
19194
19195 If no font exists for one or more of the required charsets,
19196 XCreateFontSet sets missing_charset_list_return to a list of
19197 one or more null-terminated charset names for which no font
19198 exists and sets missing_charset_count_return to the number of
19199 missing fonts. The charsets are from the list of the required
19200 charsets for the encoding of the locale and do not include any
19201 charsets to which Xlib may be able to remap a required charset.
19202
19203 If no font exists for any of the required charsets or if the
19204 locale definition in Xlib requires that a font exist for a
19205 particular charset and a font is not found for that charset,
19206 XCreateFontSet returns NULL. Otherwise, XCreateFontSet returns
19207 a valid XFontSet to font_set.
19208
19209 When an Xmb/wc drawing or measuring function is called with an
19210 XFontSet that has missing charsets, some characters in the
19211 locale will not be drawable. If def_string_return is non-NULL,
19212 XCreateFontSet returns a pointer to a string that represents
19213 the glyphs that are drawn with this XFontSet when the charsets
19214 of the available fonts do not include all font glyphs required
19215 to draw a codepoint. The string does not necessarily consist of
19216 valid characters in the current locale and is not necessarily
19217 drawn with the fonts loaded for the font set, but the client
19218 can draw and measure the default glyphs by including this
19219 string in a string being drawn or measured with the XFontSet.
19220
19221 If the string returned to def_string_return is the empty string
19222 (""), no glyphs are drawn, and the escapement is zero. The
19223 returned string is null-terminated. It is owned by Xlib and
19224 should not be modified or freed by the client. It will be freed
19225 by a call to XFreeFontSet with the associated XFontSet. Until
19226 freed, its contents will not be modified by Xlib.
19227
19228 The client is responsible for constructing an error message
19229 from the missing charset and default string information and may
19230 choose to continue operation in the case that some fonts did
19231 not exist.
19232
19233 The returned XFontSet and missing charset list should be freed
19234 with XFreeFontSet and XFreeStringList, respectively. The
19235 client-supplied base_font_name_list may be freed by the client
19236 after calling XCreateFontSet.
19237
19238 To obtain a list of XFontStruct structures and full font names
19239 given an XFontSet, use XFontsOfFontSet.
19240
19241 int XFontsOfFontSet(XFontSet font_set, XFontStruct
19242 ***font_struct_list_return, char ***font_name_list_return);
19243
19244 font_set
19245
19246 Specifies the font set.
19247
19248 font_struct_list_return
19249
19250 Returns the list of font structs.
19251
19252 font_name_list_return
19253
19254 Returns the list of font names.
19255
19256 The XFontsOfFontSet function returns a list of one or more
19257 XFontStructs and font names for the fonts used by the Xmb and
19258 Xwc layers for the given font set. A list of pointers to the
19259 XFontStruct structures is returned to font_struct_list_return.
19260 A list of pointers to null-terminated, fully specified font
19261 name strings in the locale of the font set is returned to
19262 font_name_list_return. The font_name_list order corresponds to
19263 the font_struct_list order. The number of XFontStruct
19264 structures and font names is returned as the value of the
19265 function.
19266
19267 Because it is not guaranteed that a given character will be
19268 imaged using a single font glyph, there is no provision for
19269 mapping a character or default string to the font properties,
19270 font ID, or direction hint for the font for the character. The
19271 client may access the XFontStruct list to obtain these values
19272 for all the fonts currently in use.
19273
19274 Xlib does not guarantee that fonts are loaded from the server
19275 at the creation of an XFontSet. Xlib may choose to cache font
19276 data, loading it only as needed to draw text or compute text
19277 dimensions. Therefore, existence of the per_char metrics in the
19278 XFontStruct structures in the XFontStructSet is undefined.
19279 Also, note that all properties in the XFontStruct structures
19280 are in the STRING encoding.
19281
19282 The XFontStruct and font name lists are owned by Xlib and
19283 should not be modified or freed by the client. They will be
19284 freed by a call to XFreeFontSet with the associated XFontSet.
19285 Until freed, their contents will not be modified by Xlib.
19286
19287 To obtain the base font name list and the selected font name
19288 list given an XFontSet, use XBaseFontNameListOfFontSet.
19289
19290 char *XBaseFontNameListOfFontSet(XFontSet font_set);
19291
19292 font_set
19293
19294 Specifies the font set.
19295
19296 The XBaseFontNameListOfFontSet function returns the original
19297 base font name list supplied by the client when the XFontSet
19298 was created. A null-terminated string containing a list of
19299 comma-separated font names is returned as the value of the
19300 function. White space may appear immediately on either side of
19301 separating commas.
19302
19303 If XCreateFontSet obtained an XLFD name from the font
19304 properties for the font specified by a non-XLFD base name, the
19305 XBaseFontNameListOfFontSet function will return the XLFD name
19306 instead of the non-XLFD base name.
19307
19308 The base font name list is owned by Xlib and should not be
19309 modified or freed by the client. It will be freed by a call to
19310 XFreeFontSet with the associated XFontSet. Until freed, its
19311 contents will not be modified by Xlib.
19312
19313 To obtain the locale name given an XFontSet, use
19314 XLocaleOfFontSet.
19315
19316 char *XLocaleOfFontSet(XFontSet font_set);
19317
19318 font_set
19319
19320 Specifies the font set.
19321
19322 The XLocaleOfFontSet function returns the name of the locale
19323 bound to the specified XFontSet, as a null-terminated string.
19324
19325 The returned locale name string is owned by Xlib and should not
19326 be modified or freed by the client. It may be freed by a call
19327 to XFreeFontSet with the associated XFontSet. Until freed, it
19328 will not be modified by Xlib.
19329
19330 The XFreeFontSet function is a convenience function for freeing
19331 an output context. XFreeFontSet also frees its associated XOM
19332 if the output context was created by XCreateFontSet.
19333
19334 void XFreeFontSet(Display *display, XFontSet font_set);
19335
19336 display
19337
19338 Specifies the connection to the X server.
19339
19340 font_set
19341
19342 Specifies the font set.
19343
19344 The XFreeFontSet function frees the specified font set. The
19345 associated base font name list, font name list, XFontStruct
19346 list, and XFontSetExtents, if any, are freed.
19347
19348Obtaining Font Set Metrics
19349
19350 Metrics for the internationalized text drawing functions are
19351 defined in terms of a primary draw direction, which is the
19352 default direction in which the character origin advances for
19353 each succeeding character in the string. The Xlib interface is
19354 currently defined to support only a left-to-right primary draw
19355 direction. The drawing origin is the position passed to the
19356 drawing function when the text is drawn. The baseline is a line
19357 drawn through the drawing origin parallel to the primary draw
19358 direction. Character ink is the pixels painted in the
19359 foreground color and does not include interline or
19360 intercharacter spacing or image text background pixels.
19361
19362 The drawing functions are allowed to implement implicit text
19363 directionality control, reversing the order in which characters
19364 are rendered along the primary draw direction in response to
19365 locale-specific lexical analysis of the string.
19366
19367 Regardless of the character rendering order, the origins of all
19368 characters are on the primary draw direction side of the
19369 drawing origin. The screen location of a particular character
19370 image may be determined with XmbTextPerCharExtents or
19371 XwcTextPerCharExtents.
19372
19373 The drawing functions are allowed to implement
19374 context-dependent rendering, where the glyphs drawn for a
19375 string are not simply a concatenation of the glyphs that
19376 represent each individual character. A string of two characters
19377 drawn with XmbDrawString may render differently than if the two
19378 characters were drawn with separate calls to XmbDrawString. If
19379 the client appends or inserts a character in a previously drawn
19380 string, the client may need to redraw some adjacent characters
19381 to obtain proper rendering.
19382
19383 To find out about direction-dependent rendering, use
19384 XDirectionalDependentDrawing.
19385
19386 Bool XDirectionalDependentDrawing(XFontSet font_set);
19387
19388 font_set
19389
19390 Specifies the font set.
19391
19392 The XDirectionalDependentDrawing function returns True if the
19393 drawing functions implement implicit text directionality;
19394 otherwise, it returns False.
19395
19396 To find out about context-dependent rendering, use
19397 XContextualDrawing.
19398
19399 Bool XContextualDrawing(XFontSet font_set);
19400
19401 font_set
19402
19403 Specifies the font set.
19404
19405 The XContextualDrawing function returns True if text drawn with
19406 the font set might include context-dependent drawing;
19407 otherwise, it returns False.
19408
19409 To find out about context-dependent or direction-dependent
19410 rendering, use XContextDependentDrawing.
19411
19412 Bool XContextDependentDrawing(XFontSet font_set);
19413
19414 font_set
19415
19416 Specifies the font set.
19417
19418 The XContextDependentDrawing function returns True if the
19419 drawing functions implement implicit text directionality or if
19420 text drawn with the font_set might include context-dependent
19421 drawing; otherwise, it returns False.
19422
19423 The drawing functions do not interpret newline, tab, or other
19424 control characters. The behavior when nonprinting characters
19425 other than space are drawn is implementation-dependent. It is
19426 the client's responsibility to interpret control characters in
19427 a text stream.
19428
19429 The maximum character extents for the fonts that are used by
19430 the text drawing layers can be accessed by the XFontSetExtents
19431 structure:
19432
19433
19434
19435typedef struct {
19436 XRectangle max_ink_extent; /* over all drawable characters */
19437 XRectangle max_logical_extent; /* over all drawable characters */
19438} XFontSetExtents;
19439
19440 The XRectangle structures used to return font set metrics are
19441 the usual Xlib screen-oriented rectangles with x, y giving the
19442 upper left corner, and width and height always positive.
19443
19444 The max_ink_extent member gives the maximum extent, over all
19445 drawable characters, of the rectangles that bound the character
19446 glyph image drawn in the foreground color, relative to a
19447 constant origin. See XmbTextExtents and XwcTextExtents for
19448 detailed semantics.
19449
19450 The max_logical_extent member gives the maximum extent, over
19451 all drawable characters, of the rectangles that specify minimum
19452 spacing to other graphical features, relative to a constant
19453 origin. Other graphical features drawn by the client, for
19454 example, a border surrounding the text, should not intersect
19455 this rectangle. The max_logical_extent member should be used to
19456 compute minimum interline spacing and the minimum area that
19457 must be allowed in a text field to draw a given number of
19458 arbitrary characters.
19459
19460 Due to context-dependent rendering, appending a given character
19461 to a string may change the string's extent by an amount other
19462 than that character's individual extent.
19463
19464 The rectangles for a given character in a string can be
19465 obtained from XmbTextPerCharExtents or XwcTextPerCharExtents.
19466
19467 To obtain the maximum extents structure given an XFontSet, use
19468 XExtentsOfFontSet.
19469
19470 XFontSetExtents *XExtentsOfFontSet(XFontSet font_set);
19471
19472 font_set
19473
19474 Specifies the font set.
19475
19476 The XExtentsOfFontSet function returns an XFontSetExtents
19477 structure for the fonts used by the Xmb and Xwc layers for the
19478 given font set.
19479
19480 The XFontSetExtents structure is owned by Xlib and should not
19481 be modified or freed by the client. It will be freed by a call
19482 to XFreeFontSet with the associated XFontSet. Until freed, its
19483 contents will not be modified by Xlib.
19484
19485 To obtain the escapement in pixels of the specified text as a
19486 value, use XmbTextEscapement or XwcTextEscapement.
19487
19488 int XmbTextEscapement(XFontSet font_set, char *string, int
19489 num_bytes);
19490
19491 int XwcTextEscapement(XFontSet font_set, wchar_t *string, int
19492 num_wchars);
19493
19494 font_set
19495
19496 Specifies the font set.
19497
19498 string
19499
19500 Specifies the character string.
19501
19502 num_bytes
19503
19504 Specifies the number of bytes in the string argument.
19505
19506 num_wchars
19507
19508 Specifies the number of characters in the string argument.
19509
19510 The XmbTextEscapement and XwcTextEscapement functions return
19511 the escapement in pixels of the specified string as a value,
19512 using the fonts loaded for the specified font set. The
19513 escapement is the distance in pixels in the primary draw
19514 direction from the drawing origin to the origin of the next
19515 character to be drawn, assuming that the rendering of the next
19516 character is not dependent on the supplied string.
19517
19518 Regardless of the character rendering order, the escapement is
19519 always positive.
19520
19521 To obtain the overall_ink_return and overall_logical_return
19522 arguments, the overall bounding box of the string's image, and
19523 a logical bounding box, use XmbTextExtents or XwcTextExtents.
19524
19525 int XmbTextExtents(XFontSet font_set, char *string, int
19526 num_bytes, XRectangle *overall_ink_return, XRectangle
19527 *overall_logical_return);
19528
19529 int XwcTextExtents(XFontSet font_set, wchar_t *string, int
19530 num_wchars, XRectangle *overall_ink_return, XRectangle
19531 *overall_logical_return);
19532
19533 font_set
19534
19535 Specifies the font set.
19536
19537 string
19538
19539 Specifies the character string.
19540
19541 num_bytes
19542
19543 Specifies the number of bytes in the string argument.
19544
19545 num_wchars
19546
19547 Specifies the number of characters in the string argument.
19548
19549 overall_ink_return
19550
19551 Returns the overall ink dimensions.
19552
19553 overall_logical_return
19554
19555 Returns the overall logical dimensions.
19556
19557 The XmbTextExtents and XwcTextExtents functions set the
19558 components of the specified overall_ink_return and
19559 overall_logical_return arguments to the overall bounding box of
19560 the string's image and a logical bounding box for spacing
19561 purposes, respectively. They return the value returned by
19562 XmbTextEscapement or XwcTextEscapement. These metrics are
19563 relative to the drawing origin of the string, using the fonts
19564 loaded for the specified font set.
19565
19566 If the overall_ink_return argument is non-NULL, it is set to
19567 the bounding box of the string's character ink. The
19568 overall_ink_return for a nondescending, horizontally drawn
19569 Latin character is conventionally entirely above the baseline;
19570 that is, overall_ink_return.height <= -overall_ink_return.y.
19571 The overall_ink_return for a nonkerned character is entirely
19572 at, and to the right of, the origin; that is,
19573 overall_ink_return.x >= 0. A character consisting of a single
19574 pixel at the origin would set overall_ink_return fields y = 0,
19575 x = 0, width = 1, and height = 1.
19576
19577 If the overall_logical_return argument is non-NULL, it is set
19578 to the bounding box that provides minimum spacing to other
19579 graphical features for the string. Other graphical features,
19580 for example, a border surrounding the text, should not
19581 intersect this rectangle.
19582
19583 When the XFontSet has missing charsets, metrics for each
19584 unavailable character are taken from the default string
19585 returned by XCreateFontSet so that the metrics represent the
19586 text as it will actually be drawn. The behavior for an invalid
19587 codepoint is undefined.
19588
19589 To determine the effective drawing origin for a character in a
19590 drawn string, the client should call XmbTextPerCharExtents on
19591 the entire string, then on the character, and subtract the x
19592 values of the returned rectangles for the character. This is
19593 useful to redraw portions of a line of text or to justify
19594 words, but for context-dependent rendering, the client should
19595 not assume that it can redraw the character by itself and get
19596 the same rendering.
19597
19598 To obtain per-character information for a text string, use
19599 XmbTextPerCharExtents or XwcTextPerCharExtents.
19600
19601 Status XmbTextPerCharExtents(XFontSet font_set, char *string,
19602 int num_bytes, XRectangle *ink_array_return, XRectangle
19603 *logical_array_return, int array_size, int *num_chars_return,
19604 XRectangle *overall_ink_return, XRectangle
19605 *overall_logical_return);
19606
19607 Status XwcTextPerCharExtents(XFontSet font_set, wchar_t
19608 *string, int num_wchars, XRectangle *ink_array_return,
19609 XRectangle *logical_array_return, int array_size, int
19610 *num_chars_return, XRectangle *overall_ink_return, XRectangle
19611 *overall_logical_return);
19612
19613 font_set
19614
19615 Specifies the font set.
19616
19617 string
19618
19619 Specifies the character string.
19620
19621 num_bytes
19622
19623 Specifies the number of bytes in the string argument.
19624
19625 num_wchars
19626
19627 Specifies the number of characters in the string argument.
19628
19629 ink_array_return
19630
19631 Returns the ink dimensions for each character.
19632
19633 logical_array_return
19634
19635 Returns the logical dimensions for each character.
19636
19637 array_size
19638
19639 Specifies the size of ink_array_return and
19640 logical_array_return. The caller must pass in arrays of this
19641 size.
19642
19643 num_chars_return
19644
19645 Returns the number of characters in the string argument.
19646
19647 overall_ink_return
19648
19649 Returns the overall ink dimensions.
19650
19651 overall_logical_return
19652
19653 Returns the overall logical dimensions.
19654
19655 The XmbTextPerCharExtents and XwcTextPerCharExtents functions
19656 return the text dimensions of each character of the specified
19657 text, using the fonts loaded for the specified font set. Each
19658 successive element of ink_array_return and logical_array_return
19659 is set to the successive character's drawn metrics, relative to
19660 the drawing origin of the string and one rectangle for each
19661 character in the supplied text string. The number of elements
19662 of ink_array_return and logical_array_return that have been set
19663 is returned to num_chars_return.
19664
19665 Each element of ink_array_return is set to the bounding box of
19666 the corresponding character's drawn foreground color. Each
19667 element of logical_array_return is set to the bounding box that
19668 provides minimum spacing to other graphical features for the
19669 corresponding character. Other graphical features should not
19670 intersect any of the logical_array_return rectangles.
19671
19672 Note that an XRectangle represents the effective drawing
19673 dimensions of the character, regardless of the number of font
19674 glyphs that are used to draw the character or the direction in
19675 which the character is drawn. If multiple characters map to a
19676 single character glyph, the dimensions of all the XRectangles
19677 of those characters are the same.
19678
19679 When the XFontSet has missing charsets, metrics for each
19680 unavailable character are taken from the default string
19681 returned by XCreateFontSet so that the metrics represent the
19682 text as it will actually be drawn. The behavior for an invalid
19683 codepoint is undefined.
19684
19685 If the array_size is too small for the number of characters in
19686 the supplied text, the functions return zero and
19687 num_chars_return is set to the number of rectangles required.
19688 Otherwise, the functions return a nonzero value.
19689
19690 If the overall_ink_return or overall_logical_return argument is
19691 non-NULL, XmbTextPerCharExtents and XwcTextPerCharExtents
19692 return the maximum extent of the string's metrics to
19693 overall_ink_return or overall_logical_return, as returned by
19694 XmbTextExtents or XwcTextExtents.
19695
19696Drawing Text Using Font Sets
19697
19698 The functions defined in this section draw text at a specified
19699 location in a drawable. They are similar to the functions
19700 XDrawText, XDrawString, and XDrawImageString except that they
19701 work with font sets instead of single fonts and interpret the
19702 text based on the locale of the font set instead of treating
19703 the bytes of the string as direct font indexes. See section 8.6
19704 for details of the use of Graphics Contexts (GCs) and possible
19705 protocol errors. If a BadFont error is generated, characters
19706 prior to the offending character may have been drawn.
19707
19708 The text is drawn using the fonts loaded for the specified font
19709 set; the font in the GC is ignored and may be modified by the
19710 functions. No validation that all fonts conform to some width
19711 rule is performed.
19712
19713 The text functions XmbDrawText and XwcDrawText use the
19714 following structures:
19715
19716
19717
19718typedef struct {
19719 char *chars; /* pointer to string */
19720 int nchars; /* number of bytes */
19721 int delta; /* pixel delta between strings */
19722 XFontSet font_set; /* fonts, None means don't change */
19723} XmbTextItem;
19724
19725
19726
19727typedef struct {
19728 wchar_t *chars; /* pointer to wide char string */
19729 int nchars; /* number of wide characters */
19730 int delta; /* pixel delta between strings */
19731 XFontSet font_set; /* fonts, None means don't change */
19732} XwcTextItem;
19733
19734 To draw text using multiple font sets in a given drawable, use
19735 XmbDrawText or XwcDrawText.
19736
19737 void XmbDrawText(Display *display, Drawable d, GC gc, int x,
19738 int y, XmbTextItem *items, int nitems);
19739
19740 void XwcDrawText(Display *display, Drawable d, GC gc, int x,
19741 int y, XwcTextItem *items, int nitems);
19742
19743 display
19744
19745 Specifies the connection to the X server.
19746
19747 d
19748
19749 Specifies the drawable.
19750
19751 gc
19752
19753 Specifies the GC.
19754
19755 x
19756
19757 y
19758
19759 Specify the x and y coordinates of the position in the new
19760 parent window.
19761
19762 items
19763
19764 Specifies an array of text items.
19765
19766 nitems
19767
19768 Specifies the number of text items in the array.
19769
19770 The XmbDrawText and XwcDrawText functions allow complex spacing
19771 and font set shifts between text strings. Each text item is
19772 processed in turn, with the origin of a text element advanced
19773 in the primary draw direction by the escapement of the previous
19774 text item. A text item delta specifies an additional escapement
19775 of the text item drawing origin in the primary draw direction.
19776 A font_set member other than None in an item causes the font
19777 set to be used for this and subsequent text items in the
19778 text_items list. Leading text items with a font_set member set
19779 to None will not be drawn.
19780
19781 XmbDrawText and XwcDrawText do not perform any
19782 context-dependent rendering between text segments. Clients may
19783 compute the drawing metrics by passing each text segment to
19784 XmbTextExtents and XwcTextExtents or XmbTextPerCharExtents and
19785 XwcTextPerCharExtents. When the XFontSet has missing charsets,
19786 each unavailable character is drawn with the default string
19787 returned by XCreateFontSet. The behavior for an invalid
19788 codepoint is undefined.
19789
19790 To draw text using a single font set in a given drawable, use
19791 XmbDrawString or XwcDrawString.
19792
19793 void XmbDrawString(Display *display, Drawable d, XFontSet
19794 font_set, GC gc, int x, int y, char *string, int num_bytes);
19795
19796 void XwcDrawString(Display *display, Drawable d, XFontSet
19797 font_set, GC gc, int x, int y, wchar_t *string, int
19798 num_wchars);
19799
19800 display
19801
19802 Specifies the connection to the X server.
19803
19804 d
19805
19806 Specifies the drawable.
19807
19808 font_set
19809
19810 Specifies the font set.
19811
19812 gc
19813
19814 Specifies the GC.
19815
19816 x
19817
19818 y
19819
19820 Specify the x and y coordinates of the position in the new
19821 parent window.
19822
19823 string
19824
19825 Specifies the character string.
19826
19827 num_bytes
19828
19829 Specifies the number of bytes in the string argument.
19830
19831 num_wchars
19832
19833 Specifies the number of characters in the string argument.
19834
19835 The XmbDrawString and XwcDrawString functions draw the
19836 specified text with the foreground pixel. When the XFontSet has
19837 missing charsets, each unavailable character is drawn with the
19838 default string returned by XCreateFontSet. The behavior for an
19839 invalid codepoint is undefined.
19840
19841 To draw image text using a single font set in a given drawable,
19842 use XmbDrawImageString or XwcDrawImageString.
19843
19844 void XmbDrawImageString(Display *display, Drawable d, XFontSet
19845 font_set, GC gc, int x, int y, char *string, int num_bytes);
19846
19847 void XwcDrawImageString(Display *display, Drawable d, XFontSet
19848 font_set, GC gc, int x, int y, wchar_t *string, int
19849 num_wchars);
19850
19851 display
19852
19853 Specifies the connection to the X server.
19854
19855 d
19856
19857 Specifies the drawable.
19858
19859 font_set
19860
19861 Specifies the font set.
19862
19863 gc
19864
19865 Specifies the GC.
19866
19867 x
19868
19869 y
19870
19871 Specify the x and y coordinates of the position in the new
19872 parent window.
19873
19874 string
19875
19876 Specifies the character string.
19877
19878 num_bytes
19879
19880 Specifies the number of bytes in the string argument.
19881
19882 num_wchars
19883
19884 Specifies the number of characters in the string argument.
19885
19886 The XmbDrawImageString and XwcDrawImageString functions fill a
19887 destination rectangle with the background pixel defined in the
19888 GC and then paint the text with the foreground pixel. The
19889 filled rectangle is the rectangle returned to
19890 overall_logical_return by XmbTextExtents or XwcTextExtents for
19891 the same text and XFontSet.
19892
19893 When the XFontSet has missing charsets, each unavailable
19894 character is drawn with the default string returned by
19895 XCreateFontSet. The behavior for an invalid codepoint is
19896 undefined.
19897
19898Input Methods
19899
19900 This section provides discussions of the following X Input
19901 Method (XIM) topics:
19902 * Input method overview
19903 * Input method management
19904 * Input method functions
19905 * Input method values
19906 * Input context functions
19907 * Input context values
19908 * Input method callback semantics
19909 * Event filtering
19910 * Getting keyboard input
19911 * Input method conventions
19912
19913Input Method Overview
19914
19915 This section provides definitions for terms and concepts used
19916 for internationalized text input and a brief overview of the
19917 intended use of the mechanisms provided by Xlib.
19918
19919 A large number of languages in the world use alphabets
19920 consisting of a small set of symbols (letters) to form words.
19921 To enter text into a computer in an alphabetic language, a user
19922 usually has a keyboard on which there exist key symbols
19923 corresponding to the alphabet. Sometimes, a few characters of
19924 an alphabetic language are missing on the keyboard. Many
19925 computer users who speak a Latin-alphabet-based language only
19926 have an English-based keyboard. They need to hit a combination
19927 of keystrokes to enter a character that does not exist directly
19928 on the keyboard. A number of algorithms have been developed for
19929 entering such characters. These are known as European input
19930 methods, compose input methods, or dead-key input methods.
19931
19932 Japanese is an example of a language with a phonetic symbol
19933 set, where each symbol represents a specific sound. There are
19934 two phonetic symbol sets in Japanese: Katakana and Hiragana. In
19935 general, Katakana is used for words that are of foreign origin,
19936 and Hiragana is used for writing native Japanese words.
19937 Collectively, the two systems are called Kana. Each set
19938 consists of 48 characters.
19939
19940 Korean also has a phonetic symbol set, called Hangul. Each of
19941 the 24 basic phonetic symbols (14 consonants and 10 vowels)
19942 represents a specific sound. A syllable is composed of two or
19943 three parts: the initial consonants, the vowels, and the
19944 optional last consonants. With Hangul, syllables can be treated
19945 as the basic units on which text processing is done. For
19946 example, a delete operation may work on a phonetic symbol or a
19947 syllable. Korean code sets include several thousands of these
19948 syllables. A user types the phonetic symbols that make up the
19949 syllables of the words to be entered. The display may change as
19950 each phonetic symbol is entered. For example, when the second
19951 phonetic symbol of a syllable is entered, the first phonetic
19952 symbol may change its shape and size. Likewise, when the third
19953 phonetic symbol is entered, the first two phonetic symbols may
19954 change their shape and size.
19955
19956 Not all languages rely solely on alphabetic or phonetic
19957 systems. Some languages, including Japanese and Korean, employ
19958 an ideographic writing system. In an ideographic system, rather
19959 than taking a small set of symbols and combining them in
19960 different ways to create words, each word consists of one
19961 unique symbol (or, occasionally, several symbols). The number
19962 of symbols can be very large: approximately 50,000 have been
19963 identified in Hanzi, the Chinese ideographic system.
19964
19965 Two major aspects of ideographic systems impact their use with
19966 computers. First, the standard computer character sets in
19967 Japan, China, and Korea include roughly 8,000 characters, while
19968 sets in Taiwan have between 15,000 and 30,000 characters. This
19969 makes it necessary to use more than one byte to represent a
19970 character. Second, it obviously is impractical to have a
19971 keyboard that includes all of a given language's ideographic
19972 symbols. Therefore, a mechanism is required for entering
19973 characters so that a keyboard with a reasonable number of keys
19974 can be used. Those input methods are usually based on
19975 phonetics, but there also exist methods based on the graphical
19976 properties of characters.
19977
19978 In Japan, both Kana and the ideographic system Kanji are used.
19979 In Korea, Hangul and sometimes the ideographic system Hanja are
19980 used. Now consider entering ideographs in Japan, Korea, China,
19981 and Taiwan.
19982
19983 In Japan, either Kana or English characters are typed and then
19984 a region is selected (sometimes automatically) for conversion
19985 to Kanji. Several Kanji characters may have the same phonetic
19986 representation. If that is the case with the string entered, a
19987 menu of characters is presented and the user must choose the
19988 appropriate one. If no choice is necessary or a preference has
19989 been established, the input method does the substitution
19990 directly. When Latin characters are converted to Kana or Kanji,
19991 it is called a romaji conversion.
19992
19993 In Korea, it is usually acceptable to keep Korean text in
19994 Hangul form, but some people may choose to write
19995 Hanja-originated words in Hanja rather than in Hangul. To
19996 change Hangul to Hanja, the user selects a region for
19997 conversion and then follows the same basic method as that
19998 described for Japanese.
19999
20000 Probably because there are well-accepted phonetic writing
20001 systems for Japanese and Korean, computer input methods in
20002 these countries for entering ideographs are fairly standard.
20003 Keyboard keys have both English characters and phonetic symbols
20004 engraved on them, and the user can switch between the two sets.
20005
20006 The situation is different for Chinese. While there is a
20007 phonetic system called Pinyin promoted by authorities, there is
20008 no consensus for entering Chinese text. Some vendors use a
20009 phonetic decomposition (Pinyin or another), others use
20010 ideographic decomposition of Chinese words, with various
20011 implementations and keyboard layouts. There are about 16 known
20012 methods, none of which is a clear standard.
20013
20014 Also, there are actually two ideographic sets used: Traditional
20015 Chinese (the original written Chinese) and Simplified Chinese.
20016 Several years ago, the People's Republic of China launched a
20017 campaign to simplify some ideographic characters and eliminate
20018 redundancies altogether. Under the plan, characters would be
20019 streamlined every five years. Characters have been revised
20020 several times now, resulting in the smaller, simpler set that
20021 makes up Simplified Chinese.
20022
20023Input Method Architecture
20024
20025 As shown in the previous section, there are many different
20026 input methods in use today, each varying with language,
20027 culture, and history. A common feature of many input methods is
20028 that the user may type multiple keystrokes to compose a single
20029 character (or set of characters). The process of composing
20030 characters from keystrokes is called preediting. It may require
20031 complex algorithms and large dictionaries involving substantial
20032 computer resources.
20033
20034 Input methods may require one or more areas in which to show
20035 the feedback of the actual keystrokes, to propose
20036 disambiguation to the user, to list dictionaries, and so on.
20037 The input method areas of concern are as follows:
20038 * The status area is a logical extension of the LEDs that
20039 exist on the physical keyboard. It is a window that is
20040 intended to present the internal state of the input method
20041 that is critical to the user. The status area may consist
20042 of text data and bitmaps or some combination.
20043 * The preedit area displays the intermediate text for those
20044 languages that are composing prior to the client handling
20045 the data.
20046 * The auxiliary area is used for pop-up menus and customizing
20047 dialogs that may be required for an input method. There may
20048 be multiple auxiliary areas for an input method. Auxiliary
20049 areas are managed by the input method independent of the
20050 client. Auxiliary areas are assumed to be separate dialogs,
20051 which are maintained by the input method.
20052
20053 There are various user interaction styles used for preediting.
20054 The ones supported by Xlib are as follows:
20055 * For on-the-spot input methods, preediting data will be
20056 displayed directly in the application window. Application
20057 data is moved to allow preedit data to appear at the point
20058 of insertion.
20059 * Over-the-spot preediting means that the data is displayed
20060 in a preedit window that is placed over the point of
20061 insertion.
20062 * Off-the-spot preediting means that the preedit window is
20063 inside the application window but not at the point of
20064 insertion. Often, this type of window is placed at the
20065 bottom of the application window.
20066 * Root-window preediting refers to input methods that use a
20067 preedit window that is the child of RootWindow.
20068
20069 It would require a lot of computing resources if portable
20070 applications had to include input methods for all the languages
20071 in the world. To avoid this, a goal of the Xlib design is to
20072 allow an application to communicate with an input method placed
20073 in a separate process. Such a process is called an input
20074 server. The server to which the application should connect is
20075 dependent on the environment when the application is started
20076 up, that is, the user language and the actual encoding to be
20077 used for it. The input method connection is said to be
20078 locale-dependent. It is also user-dependent. For a given
20079 language, the user can choose, to some extent, the user
20080 interface style of input method (if choice is possible among
20081 several).
20082
20083 Using an input server implies communication overhead, but
20084 applications can be migrated without relinking. Input methods
20085 can be implemented either as a stub communicating to an input
20086 server or as a local library.
20087
20088 An input method may be based on a front-end or a back-end
20089 architecture. In a front-end architecture, there are two
20090 separate connections to the X server: keystrokes go directly
20091 from the X server to the input method on one connection and
20092 other events to the regular client connection. The input method
20093 is then acting as a filter and sends composed strings to the
20094 client. A front-end architecture requires synchronization
20095 between the two connections to avoid lost key events or locking
20096 issues.
20097
20098 In a back-end architecture, a single X server connection is
20099 used. A dispatching mechanism must decide on this channel to
20100 delegate appropriate keystrokes to the input method. For
20101 instance, it may retain a Help keystroke for its own purpose.
20102 In the case where the input method is a separate process (that
20103 is, a server), there must be a special communication protocol
20104 between the back-end client and the input server.
20105
20106 A front-end architecture introduces synchronization issues and
20107 a filtering mechanism for noncharacter keystrokes (Function
20108 keys, Help, and so on). A back-end architecture sometimes
20109 implies more communication overhead and more process switching.
20110 If all three processes (X server, input server, client) are
20111 running on a single workstation, there are two process switches
20112 for each keystroke in a back-end architecture, but there is
20113 only one in a front-end architecture.
20114
20115 The abstraction used by a client to communicate with an input
20116 method is an opaque data structure represented by the XIM data
20117 type. This data structure is returned by the XOpenIM function,
20118 which opens an input method on a given display. Subsequent
20119 operations on this data structure encapsulate all communication
20120 between client and input method. There is no need for an X
20121 client to use any networking library or natural language
20122 package to use an input method.
20123
20124 A single input server may be used for one or more languages,
20125 supporting one or more encoding schemes. But the strings
20126 returned from an input method will always be encoded in the
20127 (single) locale associated with the XIM object.
20128
20129Input Contexts
20130
20131 Xlib provides the ability to manage a multi-threaded state for
20132 text input. A client may be using multiple windows, each window
20133 with multiple text entry areas, and the user possibly switching
20134 among them at any time. The abstraction for representing the
20135 state of a particular input thread is called an input context.
20136 The Xlib representation of an input context is an XIC.
20137
20138 An input context is the abstraction retaining the state,
20139 properties, and semantics of communication between a client and
20140 an input method. An input context is a combination of an input
20141 method, a locale specifying the encoding of the character
20142 strings to be returned, a client window, internal state
20143 information, and various layout or appearance characteristics.
20144 The input context concept somewhat matches for input the
20145 graphics context abstraction defined for graphics output.
20146
20147 One input context belongs to exactly one input method.
20148 Different input contexts may be associated with the same input
20149 method, possibly with the same client window. An XIC is created
20150 with the XCreateIC function, providing an XIM argument and
20151 affiliating the input context to the input method for its
20152 lifetime. When an input method is closed with XCloseIM, all of
20153 its affiliated input contexts should not be used any more (and
20154 should preferably be destroyed before closing the input
20155 method).
20156
20157 Considering the example of a client window with multiple text
20158 entry areas, the application programmer could, for example,
20159 choose to implement as follows:
20160 * As many input contexts are created as text entry areas, and
20161 the client will get the input accumulated on each context
20162 each time it looks up in that context.
20163 * A single context is created for a top-level window in the
20164 application. If such a window contains several text entry
20165 areas, each time the user moves to another text entry area,
20166 the client has to indicate changes in the context.
20167
20168 A range of choices can be made by application designers to use
20169 either a single or multiple input contexts, according to the
20170 needs of their application.
20171
20172Getting Keyboard Input
20173
20174 To obtain characters from an input method, a client must call
20175 the function XmbLookupString or XwcLookupString with an input
20176 context created from that input method. Both a locale and
20177 display are bound to an input method when it is opened, and an
20178 input context inherits this locale and display. Any strings
20179 returned by XmbLookupString or XwcLookupString will be encoded
20180 in that locale.
20181
20182Focus Management
20183
20184 For each text entry area in which the XmbLookupString or
20185 XwcLookupString functions are used, there will be an associated
20186 input context.
20187
20188 When the application focus moves to a text entry area, the
20189 application must set the input context focus to the input
20190 context associated with that area. The input context focus is
20191 set by calling XSetICFocus with the appropriate input context.
20192
20193 Also, when the application focus moves out of a text entry
20194 area, the application should unset the focus for the associated
20195 input context by calling XUnsetICFocus. As an optimization, if
20196 XSetICFocus is called successively on two different input
20197 contexts, setting the focus on the second will automatically
20198 unset the focus on the first.
20199
20200 To set and unset the input context focus correctly, it is
20201 necessary to track application-level focus changes. Such focus
20202 changes do not necessarily correspond to X server focus
20203 changes.
20204
20205 If a single input context is being used to do input for
20206 multiple text entry areas, it will also be necessary to set the
20207 focus window of the input context whenever the focus window
20208 changes (see section 13.5.6.3).
20209
20210Geometry Management
20211
20212 In most input method architectures (on-the-spot being the
20213 notable exception), the input method will perform the display
20214 of its own data. To provide better visual locality, it is often
20215 desirable to have the input method areas embedded within a
20216 client. To do this, the client may need to allocate space for
20217 an input method. Xlib provides support that allows the size and
20218 position of input method areas to be provided by a client. The
20219 input method areas that are supported for geometry management
20220 are the status area and the preedit area.
20221
20222 The fundamental concept on which geometry management for input
20223 method windows is based is the proper division of
20224 responsibilities between the client (or toolkit) and the input
20225 method. The division of responsibilities is as follows:
20226 * The client is responsible for the geometry of the input
20227 method window.
20228 * The input method is responsible for the contents of the
20229 input method window.
20230
20231 An input method is able to suggest a size to the client, but it
20232 cannot suggest a placement. Also the input method can only
20233 suggest a size. It does not determine the size, and it must
20234 accept the size it is given.
20235
20236 Before a client provides geometry management for an input
20237 method, it must determine if geometry management is needed. The
20238 input method indicates the need for geometry management by
20239 setting XIMPreeditArea or XIMStatusArea in its XIMStyles value
20240 returned by XGetIMValues. When a client has decided that it
20241 will provide geometry management for an input method, it
20242 indicates that decision by setting the XNInputStyle value in
20243 the XIC.
20244
20245 After a client has established with the input method that it
20246 will do geometry management, the client must negotiate the
20247 geometry with the input method. The geometry is negotiated by
20248 the following steps:
20249 * The client suggests an area to the input method by setting
20250 the XNAreaNeeded value for that area. If the client has no
20251 constraints for the input method, it either will not
20252 suggest an area or will set the width and height to zero.
20253 Otherwise, it will set one of the values.
20254 * The client will get the XIC value XNAreaNeeded. The input
20255 method will return its suggested size in this value. The
20256 input method should pay attention to any constraints
20257 suggested by the client.
20258 * The client sets the XIC value XNArea to inform the input
20259 method of the geometry of its window. The client should try
20260 to honor the geometry requested by the input method. The
20261 input method must accept this geometry.
20262
20263 Clients doing geometry management must be aware that setting
20264 other XIC values may affect the geometry desired by an input
20265 method. For example, XNFontSet and XNLineSpace may change the
20266 geometry desired by the input method.
20267
20268 The table of XIC values (see section 13.5.6) indicates the
20269 values that can cause the desired geometry to change when they
20270 are set. It is the responsibility of the client to renegotiate
20271 the geometry of the input method window when it is needed.
20272
20273 In addition, a geometry management callback is provided by
20274 which an input method can initiate a geometry change.
20275
20276Event Filtering
20277
20278 A filtering mechanism is provided to allow input methods to
20279 capture X events transparently to clients. It is expected that
20280 toolkits (or clients) using XmbLookupString or XwcLookupString
20281 will call this filter at some point in the event processing
20282 mechanism to make sure that events needed by an input method
20283 can be filtered by that input method.
20284
20285 If there were no filter, a client could receive and discard
20286 events that are necessary for the proper functioning of an
20287 input method. The following provides a few examples of such
20288 events:
20289 * Expose events on preedit window in local mode.
20290 * Events may be used by an input method to communicate with
20291 an input server. Such input server protocol-related events
20292 have to be intercepted if one does not want to disturb
20293 client code.
20294 * Key events can be sent to a filter before they are bound to
20295 translations such as those the X Toolkit Intrinsics library
20296 provides.
20297
20298 Clients are expected to get the XIC value XNFilterEvents and
20299 augment the event mask for the client window with that event
20300 mask. This mask may be zero.
20301
20302Callbacks
20303
20304 When an on-the-spot input method is implemented, only the
20305 client can insert or delete preedit data in place and possibly
20306 scroll existing text. This means that the echo of the
20307 keystrokes has to be achieved by the client itself, tightly
20308 coupled with the input method logic.
20309
20310 When the user enters a keystroke, the client calls
20311 XmbLookupString or XwcLookupString. At this point, in the
20312 on-the-spot case, the echo of the keystroke in the preedit has
20313 not yet been done. Before returning to the client logic that
20314 handles the input characters, the look-up function must call
20315 the echoing logic to insert the new keystroke. If the
20316 keystrokes entered so far make up a character, the keystrokes
20317 entered need to be deleted, and the composed character will be
20318 returned. Hence, what happens is that, while being called by
20319 client code, the input method logic has to call back to the
20320 client before it returns. The client code, that is, a callback
20321 procedure, is called from the input method logic.
20322
20323 There are a number of cases where the input method logic has to
20324 call back the client. Each of those cases is associated with a
20325 well-defined callback action. It is possible for the client to
20326 specify, for each input context, what callback is to be called
20327 for each action.
20328
20329 There are also callbacks provided for feedback of status
20330 information and a callback to initiate a geometry request for
20331 an input method.
20332
20333Visible Position Feedback Masks
20334
20335 In the on-the-spot input style, there is a problem when
20336 attempting to draw preedit strings that are longer than the
20337 available space. Once the display area is exceeded, it is not
20338 clear how best to display the preedit string. The visible
20339 position feedback masks of XIMText help resolve this problem by
20340 allowing the input method to specify hints that indicate the
20341 essential portions of the preedit string. For example, such
20342 hints can help developers implement scrolling of a long preedit
20343 string within a short preedit display area.
20344
20345Preedit String Management
20346
20347 As highlighted before, the input method architecture provides
20348 preediting, which supports a type of preprocessor input
20349 composition. In this case, composition consists of interpreting
20350 a sequence of key events and returning a committed string via
20351 XmbLookupString or XwcLookupString. This provides the basics
20352 for input methods.
20353
20354 In addition to preediting based on key events, a general
20355 framework is provided to give a client that desires it more
20356 advanced preediting based on the text within the client. This
20357 framework is called string conversion and is provided using XIC
20358 values. The fundamental concept of string conversion is to
20359 allow the input method to manipulate the client's text
20360 independent of any user preediting operation.
20361
20362 The need for string conversion is based on language needs and
20363 input method capabilities. The following are some examples of
20364 string conversion:
20365 * Transliteration conversion provides language-specific
20366 conversions within the input method. In the case of Korean
20367 input, users wish to convert a Hangul string into a Hanja
20368 string while in preediting, after preediting, or in other
20369 situations (for example, on a selected string). The
20370 conversion is triggered when the user presses a
20371 Hangul-to-Hanja key sequence (which may be input method
20372 specific). Sometimes the user may want to invoke the
20373 conversion after finishing preediting or on a user-selected
20374 string. Thus, the string to be converted is in an
20375 application buffer, not in the preedit area of the input
20376 method. The string conversion services allow the client to
20377 request this transliteration conversion from the input
20378 method. There are many other transliteration conversions
20379 defined for various languages, for example, Kana-to-Kanji
20380 conversion in Japanese. The key to remember is that
20381 transliteration conversions are triggered at the request of
20382 the user and returned to the client immediately without
20383 affecting the preedit area of the input method.
20384 * Reconversion of a previously committed string or a selected
20385 string is supported by many input methods as a convenience
20386 to the user. For example, a user tends to mistype the
20387 commit key while preediting. In that case, some input
20388 methods provide a special key sequence to request a
20389 ``reconvert'' operation on the committed string, similiar
20390 to the undo facility provided by most text editors. Another
20391 example is where the user is proofreading a document that
20392 has some misconversions from preediting and wants to
20393 correct the misconverted text. Such reconversion is again
20394 triggered by the user invoking some special action, but
20395 reconversions should not affect the state of the preedit
20396 area.
20397 * Context-sensitive conversion is required for some languages
20398 and input methods that need to retrieve text that surrounds
20399 the current spot location (cursor position) of the client's
20400 buffer. Such text is needed when the preediting operation
20401 depends on some surrounding characters (usually preceding
20402 the spot location). For example, in Thai language input,
20403 certain character sequences may be invalid and the input
20404 method may want to check whether characters constitute a
20405 valid word. Input methods that do such context-dependent
20406 checking need to retrieve the characters surrounding the
20407 current cursor position to obtain complete words. Unlike
20408 other conversions, this conversion is not explicitly
20409 requested by the user. Input methods that provide such
20410 context-sensitive conversion continuously need to request
20411 context from the client, and any change in the context of
20412 the spot location may affect such conversions. The client's
20413 context would be needed if the user moves the cursor and
20414 starts editing again. For this reason, an input method
20415 supporting this type of conversion should take notice of
20416 when the client calls XmbResetIC or XwcResetIC, which is
20417 usually an indication of a context change.
20418
20419 Context-sensitive conversions just need a copy of the client's
20420 text, while other conversions replace the client's text with
20421 new text to achieve the reconversion or transliteration. Yet in
20422 all cases the result of a conversion, either immediately or via
20423 preediting, is returned by the XmbLookupString and
20424 XwcLookupString functions.
20425
20426 String conversion support is dependent on the availability of
20427 the XNStringConversion or XNStringConversionCallback XIC
20428 values. Because the input method may not support string
20429 conversions, clients have to query the availability of string
20430 conversion operations by checking the supported XIC values list
20431 by calling XGetIMValues with the XNQueryICValuesList IM value.
20432
20433 The difference between these two values is whether the
20434 conversion is invoked by the client or the input method. The
20435 XNStringConversion XIC value is used by clients to request a
20436 string conversion from the input method. The client is
20437 responsible for determining which events are used to trigger
20438 the string conversion and whether the string to be converted
20439 should be copied or deleted. The type of conversion is
20440 determined by the input method; the client can only pass the
20441 string to be converted. The client is guaranteed that no
20442 XNStringConversionCallback will be issued when this value is
20443 set; thus, the client need only set one of these values.
20444
20445 The XNStringConversionCallback XIC value is used by the client
20446 to notify the input method that it will accept requests from
20447 the input method for string conversion. If this value is set,
20448 it is the input method's responsibility to determine which
20449 events are used to trigger the string conversion. When such
20450 events occur, the input method issues a call to the
20451 client-supplied procedure to retrieve the string to be
20452 converted. The client's callback procedure is notified whether
20453 to copy or delete the string and is provided with hints as to
20454 the amount of text needed. The
20455 XIMStringConversionCallbackStruct specifies which text should
20456 be passed back to the input method.
20457
20458 Finally, the input method may call the client's
20459 XNStringConversionCallback procedure multiple times if the
20460 string returned from the callback is not sufficient to perform
20461 a successful conversion. The arguments to the client's
20462 procedure allow the input method to define a position (in
20463 character units) relative to the client's cursor position and
20464 the size of the text needed. By varying the position and size
20465 of the desired text in subsequent callbacks, the input method
20466 can retrieve additional text.
20467
20468Input Method Management
20469
20470 The interface to input methods might appear to be simply
20471 creating an input method (XOpenIM) and freeing an input method
20472 (XCloseIM). However, input methods may require complex
20473 communication with input method servers (IM servers), for
20474 example:
20475 * If the X server, IM server, and X clients are started
20476 asynchronously, some clients may attempt to connect to the
20477 IM server before it is fully operational, and fail.
20478 Therefore, some mechanism is needed to allow clients to
20479 detect when an IM server has started.
20480
20481 It is up to clients to decide what should be done when an IM
20482 server is not available (for example, wait, or use some other
20483 IM server).
20484
20485 * Some input methods may allow the underlying IM server to be
20486 switched. Such customization may be desired without
20487 restarting the entire client.
20488
20489 To support management of input methods in these cases, the
20490 following functions are provided:
20491 XRegisterIMInstantiateCallback This function allows clients to
20492 register a callback procedure to be called when Xlib detects
20493 that an IM server is up and available.
20494 XOpenIM A client calls this function as a result of the
20495 callback procedure being called.
20496 XSetIMValues, XSetICValues These functions use the XIM and XIC
20497 values, XNDestroyCallback, to allow a client to register a
20498 callback procedure to be called when Xlib detects that an IM
20499 server that was associated with an opened input method is no
20500 longer available. In addition, this function can be used to
20501 switch IM servers for those input methods that support such
20502 functionality. The IM value for switching IM servers is
20503 implementation-dependent; see the description below about
20504 switching IM servers.
20505 XUnregisterIMInstantiateCallback This function removes a
20506 callback procedure registered by the client.
20507
20508 Input methods that support switching of IM servers may exhibit
20509 some side-effects:
20510 * The input method will ensure that any new IM server
20511 supports any of the input styles being used by input
20512 contexts already associated with the input method. However,
20513 the list of supported input styles may be different.
20514
20515 * Geometry management requests on previously created input
20516 contexts may be initiated by the new IM server.
20517
20518Hot Keys
20519
20520 Some clients need to guarantee which keys can be used to escape
20521 from the input method, regardless of the input method state;
20522 for example, the client-specific Help key or the keys to move
20523 the input focus. The HotKey mechanism allows clients to specify
20524 a set of keys for this purpose. However, the input method might
20525 not allow clients to specify hot keys. Therefore, clients have
20526 to query support of hot keys by checking the supported XIC
20527 values list by calling XGetIMValues with the
20528 XNQueryICValuesList IM value. When the hot keys specified
20529 conflict with the key bindings of the input method, hot keys
20530 take precedence over the key bindings of the input method.
20531
20532Preedit State Operation
20533
20534 An input method may have several internal states, depending on
20535 its implementation and the locale. However, one state that is
20536 independent of locale and implementation is whether the input
20537 method is currently performing a preediting operation. Xlib
20538 provides the ability for an application to manage the preedit
20539 state programmatically. Two methods are provided for retrieving
20540 the preedit state of an input context. One method is to query
20541 the state by calling XGetICValues with the XNPreeditState XIC
20542 value. Another method is to receive notification whenever the
20543 preedit state is changed. To receive such notification, an
20544 application needs to register a callback by calling
20545 XSetICValues with the XNPreeditStateNotifyCallback XIC value.
20546 In order to change the preedit state programmatically, an
20547 application needs to call XSetICValues with XNPreeditState.
20548
20549 Availability of the preedit state is input method dependent.
20550 The input method may not provide the ability to set the state
20551 or to retrieve the state programmatically. Therefore, clients
20552 have to query availability of preedit state operations by
20553 checking the supported XIC values list by calling XGetIMValues
20554 with the XNQueryICValuesList IM value.
20555
20556Input Method Functions
20557
20558 To open a connection, use XOpenIM.
20559
20560 XIM XOpenIM(Display *display, XrmDatabase db, char *res_name,
20561 char *res_class);
20562
20563 display
20564
20565 Specifies the connection to the X server.
20566
20567 db
20568
20569 Specifies a pointer to the resource database.
20570
20571 res_name
20572
20573 Specifies the full resource name of the application.
20574
20575 res_class
20576
20577 Specifies the full class name of the application.
20578
20579 The XOpenIM function opens an input method, matching the
20580 current locale and modifiers specification. Current locale and
20581 modifiers are bound to the input method at opening time. The
20582 locale associated with an input method cannot be changed
20583 dynamically. This implies that the strings returned by
20584 XmbLookupString or XwcLookupString, for any input context
20585 affiliated with a given input method, will be encoded in the
20586 locale current at the time the input method is opened.
20587
20588 The specific input method to which this call will be routed is
20589 identified on the basis of the current locale. XOpenIM will
20590 identify a default input method corresponding to the current
20591 locale. That default can be modified using XSetLocaleModifiers
20592 for the input method modifier.
20593
20594 The db argument is the resource database to be used by the
20595 input method for looking up resources that are private to the
20596 input method. It is not intended that this database be used to
20597 look up values that can be set as IC values in an input
20598 context. If db is NULL, no database is passed to the input
20599 method.
20600
20601 The res_name and res_class arguments specify the resource name
20602 and class of the application. They are intended to be used as
20603 prefixes by the input method when looking up resources that are
20604 common to all input contexts that may be created for this input
20605 method. The characters used for resource names and classes must
20606 be in the X Portable Character Set. The resources looked up are
20607 not fully specified if res_name or res_class is NULL.
20608
20609 The res_name and res_class arguments are not assumed to exist
20610 beyond the call to XOpenIM. The specified resource database is
20611 assumed to exist for the lifetime of the input method.
20612
20613 XOpenIM returns NULL if no input method could be opened.
20614
20615 To close a connection, use XCloseIM.
20616
20617 Status XCloseIM(XIM im);
20618
20619 im
20620
20621 Specifies the input method.
20622
20623 The XCloseIM function closes the specified input method.
20624
20625 To set input method attributes, use XSetIMValues.
20626
20627 char *XSetIMValues(XIM im);
20628
20629 im
20630
20631 Specifies the input method.
20632
20633 ...
20634
20635 Specifies the variable-length argument list to set XIM values.
20636
20637 The XSetIMValues function presents a variable argument list
20638 programming interface for setting attributes of the specified
20639 input method. It returns NULL if it succeeds; otherwise, it
20640 returns the name of the first argument that could not be set.
20641 Xlib does not attempt to set arguments from the supplied list
20642 that follow the failed argument; all arguments in the list
20643 preceding the failed argument have been set correctly.
20644
20645 To query an input method, use XGetIMValues.
20646
20647 char *XGetIMValues(XIM im);
20648
20649 im
20650
20651 Specifies the input method.
20652
20653 ...
20654
20655 Specifies the variable length argument list to get XIM values.
20656
20657 The XGetIMValues function presents a variable argument list
20658 programming interface for querying properties or features of
20659 the specified input method. This function returns NULL if it
20660 succeeds; otherwise, it returns the name of the first argument
20661 that could not be obtained.
20662
20663 Each XIM value argument (following a name) must point to a
20664 location where the XIM value is to be stored. That is, if the
20665 XIM value is of type T, the argument must be of type T*. If T
20666 itself is a pointer type, then XGetIMValues allocates memory to
20667 store the actual data, and the client is responsible for
20668 freeing this data by calling XFree with the returned pointer.
20669
20670 To obtain the display associated with an input method, use
20671 XDisplayOfIM.
20672
20673 Display *XDisplayOfIM(XIM im);
20674
20675 im
20676
20677 Specifies the input method.
20678
20679 The XDisplayOfIM function returns the display associated with
20680 the specified input method.
20681
20682 To get the locale associated with an input method, use
20683 XLocaleOfIM.
20684
20685 char *XLocaleOfIM(XIM im);
20686
20687 im
20688
20689 Specifies the input method.
20690
20691 The XLocaleOfIM function returns the locale associated with the
20692 specified input method.
20693
20694 To register an input method instantiate callback, use
20695 XRegisterIMInstantiateCallback.
20696
20697 Bool XRegisterIMInstantiateCallback(Display *display,
20698 XrmDatabase db, char *res_name, char *res_class, XIMProc
20699 callback, XPointer *client_data);
20700
20701 display
20702
20703 Specifies the connection to the X server.
20704
20705 db
20706
20707 Specifies a pointer to the resource database.
20708
20709 res_name
20710
20711 Specifies the full resource name of the application.
20712
20713 res_class
20714
20715 Specifies the full class name of the application.
20716
20717 callback
20718
20719 Specifies a pointer to the input method instantiate callback.
20720
20721 client_data
20722
20723 Specifies the additional client data.
20724
20725 The XRegisterIMInstantiateCallback function registers a
20726 callback to be invoked whenever a new input method becomes
20727 available for the specified display that matches the current
20728 locale and modifiers.
20729
20730 The function returns True if it succeeds; otherwise, it returns
20731 False.
20732
20733 The generic prototype is as follows:
20734
20735 void IMInstantiateCallback(Display *display, XPointer
20736 client_data, XPointer call_data);
20737
20738 display
20739
20740 Specifies the connection to the X server.
20741
20742 client_data
20743
20744 Specifies the additional client data.
20745
20746 call_data
20747
20748 Not used for this callback and always passed as NULL.
20749
20750 To unregister an input method instantiation callback, use
20751 XUnregisterIMInstantiateCallback.
20752
20753 Bool XUnregisterIMInstantiateCallback(Display *display,
20754 XrmDatabase db, char *res_name, char *res_class, XIMProc
20755 callback, XPointer *client_data);
20756
20757 display
20758
20759 Specifies the connection to the X server.
20760
20761 db
20762
20763 Specifies a pointer to the resource database.
20764
20765 res_name
20766
20767 Specifies the full resource name of the application.
20768
20769 res_class
20770
20771 Specifies the full class name of the application.
20772
20773 callback
20774
20775 Specifies a pointer to the input method instantiate callback.
20776
20777 client_data
20778
20779 Specifies the additional client data.
20780
20781 The XUnregisterIMInstantiateCallback function removes an input
20782 method instantiation callback previously registered. The
20783 function returns True if it succeeds; otherwise, it returns
20784 False.
20785
20786Input Method Values
20787
20788 The following table describes how XIM values are interpreted by
20789 an input method. The first column lists the XIM values. The
20790 second column indicates how each of the XIM values are treated
20791 by that input style.
20792
20793 The following keys apply to this table.
20794 Key Explanation
20795 D This value may be set using XSetIMValues. If it is not set, a
20796 default is provided.
20797 S This value may be set using XSetIMValues.
20798 G This value may be read using XGetIMValues.
20799
20800 XIM Value Key
20801 XNQueryInputStyle G
20802 XNResourceName D-S-G
20803 XNResourceClass D-S-G
20804 XNDestroyCallback D-S-G
20805 XNQueryIMValuesList G
20806 XNQueryICValuesList G
20807 XNVisiblePosition G
20808 XNR6PreeditCallback D-S-G
20809
20810 XNR6PreeditCallback is obsolete and its use is not recommended
20811 (see section 13.5.4.6).
20812
20813Query Input Style
20814
20815 A client should always query the input method to determine
20816 which input styles are supported. The client should then find
20817 an input style it is capable of supporting.
20818
20819 If the client cannot find an input style that it can support,
20820 it should negotiate with the user the continuation of the
20821 program (exit, choose another input method, and so on).
20822
20823 The argument value must be a pointer to a location where the
20824 returned value will be stored. The returned value is a pointer
20825 to a structure of type XIMStyles. Clients are responsible for
20826 freeing the XIMStyles structure. To do so, use XFree.
20827
20828 The XIMStyles structure is defined as follows:
20829typedef unsigned long XIMStyle;
20830
20831
20832#define XIMPreeditArea 0x0001L
20833#define XIMPreeditCallbacks 0x0002L
20834#define XIMPreeditPosition 0x0004L
20835#define XIMPreeditNothing 0x0008L
20836#define XIMPreeditNone 0x0010L
20837
20838#define XIMStatusArea 0x0100L
20839#define XIMStatusCallbacks 0x0200L
20840#define XIMStatusNothing 0x0400L
20841#define XIMStatusNone 0x0800L
20842
20843typedef struct {
20844 unsigned short count_styles;
20845 XIMStyle * supported_styles;
20846} XIMStyles;
20847
20848
20849 An XIMStyles structure contains the number of input styles
20850 supported in its count_styles field. This is also the size of
20851 the supported_styles array.
20852
20853 The supported styles is a list of bitmask combinations, which
20854 indicate the combination of styles for each of the areas
20855 supported. These areas are described later. Each element in the
20856 list should select one of the bitmask values for each area. The
20857 list describes the complete set of combinations supported. Only
20858 these combinations are supported by the input method.
20859
20860 The preedit category defines what type of support is provided
20861 by the input method for preedit information.
20862 XIMPreeditArea If chosen, the input method would require the
20863 client to provide some area values for it to do its preediting.
20864 Refer to XIC values XNArea and XNAreaNeeded.
20865 XIMPreeditPosition If chosen, the input method would require
20866 the client to provide positional values. Refer to XIC values
20867 XNSpotLocation and XNFocusWindow.
20868 XIMPreeditCallbacks If chosen, the input method would require
20869 the client to define the set of preedit callbacks. Refer to XIC
20870 values XNPreeditStartCallback, XNPreeditDoneCallback,
20871 XNPreeditDrawCallback, and XNPreeditCaretCallback.
20872 XIMPreeditNothing If chosen, the input method can function
20873 without any preedit values.
20874 XIMPreeditNone The input method does not provide any preedit
20875 feedback. Any preedit value is ignored. This style is mutually
20876 exclusive with the other preedit styles.
20877
20878 The status category defines what type of support is provided by
20879 the input method for status information.
20880 XIMStatusArea The input method requires the client to provide
20881 some area values for it to do its status feedback. See XNArea
20882 and XNAreaNeeded.
20883 XIMStatusCallbacks The input method requires the client to
20884 define the set of status callbacks, XNStatusStartCallback,
20885 XNStatusDoneCallback, and XNStatusDrawCallback.
20886 XIMStatusNothing The input method can function without any
20887 status values.
20888 XIMStatusNone The input method does not provide any status
20889 feedback. If chosen, any status value is ignored. This style is
20890 mutually exclusive with the other status styles.
20891
20892Resource Name and Class
20893
20894 The XNResourceName and XNResourceClass arguments are strings
20895 that specify the full name and class used by the input method.
20896 These values should be used as prefixes for the name and class
20897 when looking up resources that may vary according to the input
20898 method. If these values are not set, the resources will not be
20899 fully specified.
20900
20901 It is not intended that values that can be set as XIM values be
20902 set as resources.
20903
20904Destroy Callback
20905
20906 The XNDestroyCallback argument is a pointer to a structure of
20907 type XIMCallback. XNDestroyCallback is triggered when an input
20908 method stops its service for any reason. After the callback is
20909 invoked, the input method is closed and the associated input
20910 context(s) are destroyed by Xlib. Therefore, the client should
20911 not call XCloseIM or XDestroyIC.
20912
20913 The generic prototype of this callback function is as follows:
20914
20915 void DestroyCallback(XIM im, XPointer client_data, XPointer
20916 call_data);
20917
20918 im
20919
20920 Specifies the input method.
20921
20922 client_data
20923
20924 Specifies the additional client data.
20925
20926 call_data
20927
20928 Not used for this callback and always passed as NULL.
20929
20930 A DestroyCallback is always called with a NULL call_data
20931 argument.
20932
20933Query IM/IC Values List
20934
20935 XNQueryIMValuesList and XNQueryICValuesList are used to query
20936 about XIM and XIC values supported by the input method.
20937
20938 The argument value must be a pointer to a location where the
20939 returned value will be stored. The returned value is a pointer
20940 to a structure of type XIMValuesList. Clients are responsible
20941 for freeing the XIMValuesList structure. To do so, use XFree.
20942
20943 The XIMValuesList structure is defined as follows:
20944
20945
20946typedef struct {
20947 unsigned short count_values;
20948 char **supported_values;
20949} XIMValuesList;
20950
20951Visible Position
20952
20953 The XNVisiblePosition argument indicates whether the visible
20954 position masks of XIMFeedback in XIMText are available.
20955
20956 The argument value must be a pointer to a location where the
20957 returned value will be stored. The returned value is of type
20958 Bool. If the returned value is True, the input method uses the
20959 visible position masks of XIMFeedback in XIMText; otherwise,
20960 the input method does not use the masks.
20961
20962 Because this XIM value is optional, a client should call
20963 XGetIMValues with argument XNQueryIMValuesList before using
20964 this argument. If the XNVisiblePosition does not exist in the
20965 IM values list returned from XNQueryIMValuesList, the visible
20966 position masks of XIMFeedback in XIMText are not used to
20967 indicate the visible position.
20968
20969Preedit Callback Behavior
20970
20971 The XNR6PreeditCallback argument originally included in the
20972 X11R6 specification has been deprecated.\(dg During formulation
20973 of the X11R6 specification, the behavior of the R6
20974 PreeditDrawCallbacks was going to differ significantly from
20975 that of the R5 callbacks. Late changes to the specification
20976 converged the R5 and R6 behaviors, eliminating the need for
20977 XNR6PreeditCallback. Unfortunately, this argument was not
20978 removed from the R6 specification before it was published.
20979
20980 The XNR6PreeditCallback argument indicates whether the behavior
20981 of preedit callbacks regarding XIMPreeditDrawCallbackStruct
20982 values follows Release 5 or Release 6 semantics.
20983
20984 The value is of type Bool. When querying for
20985 XNR6PreeditCallback, if the returned value is True, the input
20986 method uses the Release 6 behavior; otherwise, it uses the
20987 Release 5 behavior. The default value is False. In order to use
20988 Release 6 semantics, the value of XNR6PreeditCallback must be
20989 set to True.
20990
20991 Because this XIM value is optional, a client should call
20992 XGetIMValues with argument XNQueryIMValuesList before using
20993 this argument. If the XNR6PreeditCallback does not exist in the
20994 IM values list returned from XNQueryIMValuesList, the
20995 PreeditCallback behavior is Release 5 semantics.
20996
20997Input Context Functions
20998
20999 An input context is an abstraction that is used to contain both
21000 the data required (if any) by an input method and the
21001 information required to display that data. There may be
21002 multiple input contexts for one input method. The programming
21003 interfaces for creating, reading, or modifying an input context
21004 use a variable argument list. The name elements of the argument
21005 lists are referred to as XIC values. It is intended that input
21006 methods be controlled by these XIC values. As new XIC values
21007 are created, they should be registered with the X Consortium.
21008
21009 To create an input context, use XCreateIC.
21010
21011 XIC XCreateIC(XIM im);
21012
21013 im
21014
21015 Specifies the input method.
21016
21017 ...
21018
21019 Specifies the variable length argument list to set XIC values.
21020
21021 The XCreateIC function creates a context within the specified
21022 input method.
21023
21024 Some of the arguments are mandatory at creation time, and the
21025 input context will not be created if those arguments are not
21026 provided. The mandatory arguments are the input style and the
21027 set of text callbacks (if the input style selected requires
21028 callbacks). All other input context values can be set later.
21029
21030 XCreateIC returns a NULL value if no input context could be
21031 created. A NULL value could be returned for any of the
21032 following reasons:
21033 * A required argument was not set.
21034 * A read-only argument was set (for example, XNFilterEvents).
21035 * The argument name is not recognized.
21036 * The input method encountered an input method
21037 implementation-dependent error.
21038
21039 XCreateIC can generate BadAtom, BadColor, BadPixmap, and
21040 BadWindow errors.
21041
21042 To destroy an input context, use XDestroyIC.
21043
21044 void XDestroyIC(XIC ic);
21045
21046 ic
21047
21048 Specifies the input context.
21049
21050 XDestroyIC destroys the specified input context.
21051
21052 To communicate to and synchronize with input method for any
21053 changes in keyboard focus from the client side, use XSetICFocus
21054 and XUnsetICFocus.
21055
21056 void XSetICFocus(XIC ic);
21057
21058 ic
21059
21060 Specifies the input context.
21061
21062 The XSetICFocus function allows a client to notify an input
21063 method that the focus window attached to the specified input
21064 context has received keyboard focus. The input method should
21065 take action to provide appropriate feedback. Complete feedback
21066 specification is a matter of user interface policy.
21067
21068 Calling XSetICFocus does not affect the focus window value.
21069
21070 void XUnsetICFocus(XIC ic);
21071
21072 ic
21073
21074 Specifies the input context.
21075
21076 The XUnsetICFocus function allows a client to notify an input
21077 method that the specified input context has lost the keyboard
21078 focus and that no more input is expected on the focus window
21079 attached to that input context. The input method should take
21080 action to provide appropriate feedback. Complete feedback
21081 specification is a matter of user interface policy.
21082
21083 Calling XUnsetICFocus does not affect the focus window value;
21084 the client may still receive events from the input method that
21085 are directed to the focus window.
21086
21087 To reset the state of an input context to its initial state,
21088 use XmbResetIC or XwcResetIC.
21089
21090 char *XmbResetIC(XIC ic);
21091
21092 wchar_t *XwcResetIC(XIC ic);
21093
21094 ic
21095
21096 Specifies the input context.
21097
21098 When XNResetState is set to XIMInitialState, XmbResetIC and
21099 XwcResetIC reset an input context to its initial state; when
21100 XNResetState is set to XIMPreserveState, the current input
21101 context state is preserved. In both cases, any input pending on
21102 that context is deleted. The input method is required to clear
21103 the preedit area, if any, and update the status accordingly.
21104 Calling XmbResetIC or XwcResetIC does not change the focus.
21105
21106 The return value of XmbResetIC is its current preedit string as
21107 a multibyte string. If there is any preedit text drawn or
21108 visible to the user, then these procedures must return a
21109 non-NULL string. If there is no visible preedit text, then it
21110 is input method implementation-dependent whether these
21111 procedures return a non-NULL string or NULL.
21112
21113 The client should free the returned string by calling XFree.
21114
21115 To get the input method associated with an input context, use
21116 XIMOfIC.
21117
21118 XIM XIMOfIC(XIC ic);
21119
21120 ic
21121
21122 Specifies the input context.
21123
21124 The XIMOfIC function returns the input method associated with
21125 the specified input context.
21126
21127 Xlib provides two functions for setting and reading XIC values,
21128 respectively, XSetICValues and XGetICValues. Both functions
21129 have a variable-length argument list. In that argument list,
21130 any XIC value's name must be denoted with a character string
21131 using the X Portable Character Set.
21132
21133 To set XIC values, use XSetICValues.
21134
21135 char *XSetICValues(XIC ic);
21136
21137 ic
21138
21139 Specifies the input context.
21140
21141 ...
21142
21143 Specifies the variable length argument list to set XIC values.
21144
21145 The XSetICValues function returns NULL if no error occurred;
21146 otherwise, it returns the name of the first argument that could
21147 not be set. An argument might not be set for any of the
21148 following reasons:
21149 * The argument is read-only (for example, XNFilterEvents).
21150 * The argument name is not recognized.
21151 * An implementation-dependent error occurs.
21152
21153 Each value to be set must be an appropriate datum, matching the
21154 data type imposed by the semantics of the argument.
21155
21156 XSetICValues can generate BadAtom, BadColor, BadCursor,
21157 BadPixmap, and BadWindow errors.
21158
21159 To obtain XIC values, use XGetICValues.
21160
21161 char *XGetICValues(XIC ic);
21162
21163 ic
21164
21165 Specifies the input context.
21166
21167 ...
21168
21169 Specifies the variable length argument list to get XIC values.
21170
21171 The XGetICValues function returns NULL if no error occurred;
21172 otherwise, it returns the name of the first argument that could
21173 not be obtained. An argument could not be obtained for any of
21174 the following reasons:
21175 * The argument name is not recognized.
21176 * The input method encountered an implementation-dependent
21177 error.
21178
21179 Each IC attribute value argument (following a name) must point
21180 to a location where the IC value is to be stored. That is, if
21181 the IC value is of type T, the argument must be of type T*. If
21182 T itself is a pointer type, then XGetICValues allocates memory
21183 to store the actual data, and the client is responsible for
21184 freeing this data by calling XFree with the returned pointer.
21185 The exception to this rule is for an IC value of type
21186 XVaNestedList (for preedit and status attributes). In this
21187 case, the argument must also be of type XVaNestedList. Then,
21188 the rule of changing type T to T* and freeing the allocated
21189 data applies to each element of the nested list.
21190
21191Input Context Values
21192
21193 The following tables describe how XIC values are interpreted by
21194 an input method depending on the input style chosen by the
21195 user.
21196
21197 The first column lists the XIC values. The second column
21198 indicates which values are involved in affecting, negotiating,
21199 and setting the geometry of the input method windows. The
21200 subentries under the third column indicate the different input
21201 styles that are supported. Each of these columns indicates how
21202 each of the XIC values are treated by that input style.
21203
21204 The following keys apply to these tables.
21205 Key Explanation
21206 C This value must be set with XCreateIC.
21207 D This value may be set using XCreateIC.> If it is not set,> a
21208 default is provided.
21209 G This value may be read using XGetICValues.
21210 GN This value may cause geometry negotiation when its value is
21211 set by means of XCreateIC or XSetICValues.
21212 GR This value will be the response of the input method when any
21213 GN value is changed.
21214 GS This value will cause the geometry of the input method
21215 window to be set.
21216 O This value must be set once and only once. It need not be set
21217 at create time.
21218 S This value may be set with XSetICValues.
21219 Ignored This value is ignored by the input method for the given
21220 input style.
21221
21222 XIC Value Geometry Mangement Preedit Callback Preedit Position
21223 Input Style Preedit Area Preedit Nothing Preedit None
21224 Input Style C-G C-G C-G C-G C-G
21225 Client Window O-G O-G O-G O-G Ignored
21226 Focus Window GN D-S-G D-S-G D-S-G D-S-G Ignored
21227 Resource Name Ignored D-S-G D-S-G D-S-G Ignored
21228 Resource Class Ignored D-S-G D-S-G D-S-G Ignored
21229 Geometry Callback Ignored Ignored D-S-G Ignored Ignored
21230 Filter Events G G G G Ignored
21231 Destroy Callback D-S-G D-S-G D-S-G D-S-G D-S-G
21232 String Conversion Callback S-G S-G S-G S-G S-G
21233 String Conversion D-S-G D-S-G D-S-G D-S-G D-S-G
21234 Reset State D-S-G D-S-G D-S-G D-S-G Ignored
21235 HotKey S-G S-G S-G S-G Ignored
21236 HotKeyState D-S-G D-S-G D-S-G D-S-G Ignored
21237 Preedit
21238 Area GS Ignored D-S-G D-S-G Ignored Ignored
21239 Area Needed GN-GR Ignored Ignored S-G Ignored Ignored
21240 Spot Location Ignored D-S-G Ignored Ignored Ignored
21241 Colormap Ignored D-S-G D-S-G D-S-G Ignored
21242 Foreground Ignored D-S-G D-S-G D-S-G Ignored
21243 Background Ignored D-S-G D-S-G D-S-G Ignored
21244 Background Pixmap Ignored D-S-G D-S-G D-S-G Ignored
21245 Font Set GN Ignored D-S-G D-S-G D-S-G Ignored
21246 Line Spacing GN Ignored D-S-G D-S-G D-S-G Ignored
21247 Cursor Ignored D-S-G D-S-G D-S-G Ignored
21248 Preedit State D-S-G D-S-G D-S-G D-S-G Ignored
21249 Preedit State Notify Callback S-G S-G S-G S-G Ignored
21250 Preedit Callbacks C-S-G Ignored Ignored Ignored Ignored
21251
21252 XIC Value Geomentry Management Status Callback Status Area
21253 Status Nothing Status None
21254 Input Style C-G C-G C-G C-G
21255 Client Window O-G O-G O-G Ignored
21256 Focus Window GN D-S-G D-S-G D-S-G Ignored
21257 Resource Name Ignored D-S-G D-S-G Ignored
21258 Resource Class Ignored D-S-G D-S-G Ignored
21259 Geometry Callback Ignored D-S-G Ignored Ignored
21260 Filter Events G G G G
21261 Status
21262 Area GS Ignored D-S-G Ignored Ignored
21263 Area Needed GN-GR Ignored S-G Ignored Ignored
21264 Colormap Ignored D-S-G D-S-G Ignored
21265 Foreground Ignored D-S-G D-S-G Ignored
21266 Background Ignored D-S-G D-S-G Ignored
21267 Background Pixmap Ignored D-S-G D-S-G Ignored
21268 Font Set GN Ignored D-S-G D-S-G Ignored
21269 Line Spacing GN Ignored D-S-G D-S-G Ignored
21270 Cursor Ignored D-S-G D-S-G Ignored
21271 Status Callbacks C-S-G Ignored Ignored Ignored
21272
21273Input Style
21274
21275 The XNInputStyle argument specifies the input style to be used.
21276 The value of this argument must be one of the values returned
21277 by the XGetIMValues function with the XNQueryInputStyle
21278 argument specified in the supported_styles list.
21279
21280 Note that this argument must be set at creation time and cannot
21281 be changed.
21282
21283Client Window
21284
21285 The XNClientWindow argument specifies to the input method the
21286 client window in which the input method can display data or
21287 create subwindows. Geometry values for input method areas are
21288 given with respect to the client window. Dynamic change of
21289 client window is not supported. This argument may be set only
21290 once and should be set before any input is done using this
21291 input context. If it is not set, the input method may not
21292 operate correctly.
21293
21294 If an attempt is made to set this value a second time with
21295 XSetICValues, the string XNClientWindow will be returned by
21296 XSetICValues, and the client window will not be changed.
21297
21298 If the client window is not a valid window ID on the display
21299 attached to the input method, a BadWindow error can be
21300 generated when this value is used by the input method.
21301
21302Focus Window
21303
21304 The XNFocusWindow argument specifies the focus window. The
21305 primary purpose of the XNFocusWindow is to identify the window
21306 that will receive the key event when input is composed. In
21307 addition, the input method may possibly affect the focus window
21308 as follows:
21309 * Select events on it
21310 * Send events to it
21311 * Modify its properties
21312 * Grab the keyboard within that window
21313
21314 The associated value must be of type Window. If the focus
21315 window is not a valid window ID on the display attached to the
21316 input method, a BadWindow error can be generated when this
21317 value is used by the input method.
21318
21319 When this XIC value is left unspecified, the input method will
21320 use the client window as the default focus window.
21321
21322Resource Name and Class
21323
21324 The XNResourceName and XNResourceClass arguments are strings
21325 that specify the full name and class used by the client to
21326 obtain resources for the client window. These values should be
21327 used as prefixes for name and class when looking up resources
21328 that may vary according to the input context. If these values
21329 are not set, the resources will not be fully specified.
21330
21331 It is not intended that values that can be set as XIC values be
21332 set as resources.
21333
21334Geometry Callback
21335
21336 The XNGeometryCallback argument is a structure of type
21337 XIMCallback (see section 13.5.6.13.12).
21338
21339 The XNGeometryCallback argument specifies the geometry callback
21340 that a client can set. This callback is not required for
21341 correct operation of either an input method or a client. It can
21342 be set for a client whose user interface policy permits an
21343 input method to request the dynamic change of that input
21344 method's window. An input method that does dynamic change will
21345 need to filter any events that it uses to initiate the change.
21346
21347Filter Events
21348
21349 The XNFilterEvents argument returns the event mask that an
21350 input method needs to have selected for. The client is expected
21351 to augment its own event mask for the client window with this
21352 one.
21353
21354 This argument is read-only, is set by the input method at
21355 create time, and is never changed.
21356
21357 The type of this argument is unsigned long. Setting this value
21358 will cause an error.
21359
21360Destroy Callback
21361
21362 The XNDestroyCallback argument is a pointer to a structure of
21363 type XIMCallback (see section 13.5.6.13.12). This callback is
21364 triggered when the input method stops its service for any
21365 reason; for example, when a connection to an IM server is
21366 broken. After the destroy callback is called, the input context
21367 is destroyed and the input method is closed. Therefore, the
21368 client should not call XDestroyIC and XCloseIM.
21369
21370String Conversion Callback
21371
21372 The XNStringConversionCallback argument is a structure of type
21373 XIMCallback (see section 13.5.6.13.12).
21374
21375 The XNStringConversionCallback argument specifies a string
21376 conversion callback. This callback is not required for correct
21377 operation of either the input method or the client. It can be
21378 set by a client to support string conversions that may be
21379 requested by the input method. An input method that does string
21380 conversions will filter any events that it uses to initiate the
21381 conversion.
21382
21383 Because this XIC value is optional, a client should call
21384 XGetIMValues with argument XNQueryICValuesList before using
21385 this argument.
21386
21387String Conversion
21388
21389 The XNStringConversion argument is a structure of type
21390 XIMStringConversionText.
21391
21392 The XNStringConversion argument specifies the string to be
21393 converted by an input method. This argument is not required for
21394 correct operation of either the input method or the client.
21395
21396 String conversion facilitates the manipulation of text
21397 independent of preediting. It is essential for some input
21398 methods and clients to manipulate text by performing
21399 context-sensitive conversion, reconversion, or transliteration
21400 conversion on it.
21401
21402 Because this XIC value is optional, a client should call
21403 XGetIMValues with argument XNQueryICValuesList before using
21404 this argument.
21405
21406 The XIMStringConversionText structure is defined as follows:
21407
21408
21409typedef struct _XIMStringConversionText {
21410 unsigned short length;
21411 XIMStringConversionFeedback *feedback;
21412 Bool encoding_is_wchar;
21413 union {
21414 char *mbs;
21415 wchar_t *wcs;
21416 } string;
21417} XIMStringConversionText;
21418
21419typedef unsigned long XIMStringConversionFeedback;
21420
21421 The feedback member is reserved for future use. The text to be
21422 converted is defined by the string and length members. The
21423 length is indicated in characters. To prevent the library from
21424 freeing memory pointed to by an uninitialized pointer, the
21425 client should set the feedback element to NULL.
21426
21427Reset State
21428
21429 The XNResetState argument specifies the state the input context
21430 will return to after calling XmbResetIC or XwcResetIC.
21431
21432 The XIC state may be set to its initial state, as specified by
21433 the XNPreeditState value when XCreateIC was called, or it may
21434 be set to preserve the current state.
21435
21436 The valid masks for XIMResetState are as follows:
21437
21438typedef unsigned long XIMResetState;
21439
21440#define XIMInitialState (1L)
21441#define XIMPreserveState (1L<<1)
21442
21443
21444 If XIMInitialState is set, then XmbResetIC and XwcResetIC will
21445 return to the initial XNPreeditState state of the XIC.
21446
21447 If XIMPreserveState is set, then XmbResetIC and XwcResetIC will
21448 preserve the current state of the XIC.
21449
21450 If XNResetState is left unspecified, the default is
21451 XIMInitialState.
21452
21453 XIMResetState values other than those specified above will
21454 default to XIMInitialState.
21455
21456 Because this XIC value is optional, a client should call
21457 XGetIMValues with argument XNQueryICValuesList before using
21458 this argument.
21459
21460Hot Keys
21461
21462 The XNHotKey argument specifies the hot key list to the XIC.
21463 The hot key list is a pointer to the structure of type
21464 XIMHotKeyTriggers, which specifies the key events that must be
21465 received without any interruption of the input method. For the
21466 hot key list set with this argument to be utilized, the client
21467 must also set XNHotKeyState to XIMHotKeyStateON.
21468
21469 Because this XIC value is optional, a client should call
21470 XGetIMValues with argument XNQueryICValuesList before using
21471 this functionality.
21472
21473 The value of the argument is a pointer to a structure of type
21474 XIMHotKeyTriggers.
21475
21476 If an event for a key in the hot key list is found, then the
21477 process will receive the event and it will be processed inside
21478 the client.
21479
21480
21481
21482typedef struct {
21483 KeySym keysym;
21484 unsigned int modifier;
21485 unsigned int modifier_mask;
21486} XIMHotKeyTrigger;
21487
21488typedef struct {
21489 int num_hot_key;
21490 XIMHotKeyTrigger *key;
21491} XIMHotKeyTriggers;
21492
21493 The combination of modifier and modifier_mask are used to
21494 represent one of three states for each modifier: either the
21495 modifier must be on, or the modifier must be off, or the
21496 modifier is a ``don't care'' - it may be on or off. When a
21497 modifier_mask bit is set to 0, the state of the associated
21498 modifier is ignored when evaluating whether the key is hot or
21499 not.
21500 Modifier Bit Mask Bit Meaning
21501 0 1 The modifier must be off.
21502 1 1 The modifier must be on.
21503 n/a 0 Do not care if the modifier is on or off.
21504
21505Hot Key State
21506
21507 The XNHotKeyState argument specifies the hot key state of the
21508 input method. This is usually used to switch the input method
21509 between hot key operation and normal input processing.
21510
21511 The value of the argument is a pointer to a structure of type
21512 XIMHotKeyState .
21513typedef unsigned long XIMHotKeyState;
21514
21515#define XIMHotKeyStateON (0x0001L)
21516#define XIMHotKeyStateOFF (0x0002L)
21517
21518
21519 If not specified, the default is XIMHotKeyStateOFF.
21520
21521Preedit and Status Attributes
21522
21523 The XNPreeditAttributes and XNStatusAttributes arguments
21524 specify to an input method the attributes to be used for the
21525 preedit and status areas, if any. Those attributes are passed
21526 to XSetICValues or XGetICValues as a nested variable-length
21527 list. The names to be used in these lists are described in the
21528 following sections.
21529
21530Area
21531
21532 The value of the XNArea argument must be a pointer to a
21533 structure of type XRectangle. The interpretation of the XNArea
21534 argument is dependent on the input method style that has been
21535 set.
21536
21537 If the input method style is XIMPreeditPosition, XNArea
21538 specifies the clipping region within which preediting will take
21539 place. If the focus window has been set, the coordinates are
21540 assumed to be relative to the focus window. Otherwise, the
21541 coordinates are assumed to be relative to the client window. If
21542 neither has been set, the results are undefined.
21543
21544 If XNArea is not specified, is set to NULL, or is invalid, the
21545 input method will default the clipping region to the geometry
21546 of the XNFocusWindow. If the area specified is NULL or invalid,
21547 the results are undefined.
21548
21549 If the input style is XIMPreeditArea or XIMStatusArea, XNArea
21550 specifies the geometry provided by the client to the input
21551 method. The input method may use this area to display its data,
21552 either preedit or status depending on the area designated. The
21553 input method may create a window as a child of the client
21554 window with dimensions that fit the XNArea. The coordinates are
21555 relative to the client window. If the client window has not
21556 been set yet, the input method should save these values and
21557 apply them when the client window is set. If XNArea is not
21558 specified, is set to NULL, or is invalid, the results are
21559 undefined.
21560
21561Area Needed
21562
21563 When set, the XNAreaNeeded argument specifies the geometry
21564 suggested by the client for this area (preedit or status). The
21565 value associated with the argument must be a pointer to a
21566 structure of type XRectangle. Note that the x, y values are not
21567 used and that nonzero values for width or height are the
21568 constraints that the client wishes the input method to respect.
21569
21570 When read, the XNAreaNeeded argument specifies the preferred
21571 geometry desired by the input method for the area.
21572
21573 This argument is only valid if the input style is
21574 XIMPreeditArea or XIMStatusArea. It is used for geometry
21575 negotiation between the client and the input method and has no
21576 other effect on the input method (see section 13.5.1.5).
21577
21578Spot Location
21579
21580 The XNSpotLocation argument specifies to the input method the
21581 coordinates of the spot to be used by an input method executing
21582 with XNInputStyle set to XIMPreeditPosition. When specified to
21583 any input method other than XIMPreeditPosition, this XIC value
21584 is ignored.
21585
21586 The x coordinate specifies the position where the next
21587 character would be inserted. The y coordinate is the position
21588 of the baseline used by the current text line in the focus
21589 window. The x and y coordinates are relative to the focus
21590 window, if it has been set; otherwise, they are relative to the
21591 client window. If neither the focus window nor the client
21592 window has been set, the results are undefined.
21593
21594 The value of the argument is a pointer to a structure of type
21595 XPoint.
21596
21597Colormap
21598
21599 Two different arguments can be used to indicate what colormap
21600 the input method should use to allocate colors, a colormap ID,
21601 or a standard colormap name.
21602
21603 The XNColormap argument is used to specify a colormap ID. The
21604 argument value is of type Colormap. An invalid argument may
21605 generate a BadColor error when it is used by the input method.
21606
21607 The XNStdColormap argument is used to indicate the name of the
21608 standard colormap in which the input method should allocate
21609 colors. The argument value is an Atom that should be a valid
21610 atom for calling XGetRGBColormaps. An invalid argument may
21611 generate a BadAtom error when it is used by the input method.
21612
21613 If the colormap is left unspecified, the client window colormap
21614 becomes the default.
21615
21616Foreground and Background
21617
21618 The XNForeground and XNBackground arguments specify the
21619 foreground and background pixel, respectively. The argument
21620 value is of type unsigned long. It must be a valid pixel in the
21621 input method colormap.
21622
21623 If these values are left unspecified, the default is determined
21624 by the input method.
21625
21626Background Pixmap
21627
21628 The XNBackgroundPixmap argument specifies a background pixmap
21629 to be used as the background of the window. The value must be
21630 of type Pixmap. An invalid argument may generate a BadPixmap
21631 error when it is used by the input method.
21632
21633 If this value is left unspecified, the default is determined by
21634 the input method.
21635
21636Font Set
21637
21638 The XNFontSet argument specifies to the input method what font
21639 set is to be used. The argument value is of type XFontSet.
21640
21641 If this value is left unspecified, the default is determined by
21642 the input method.
21643
21644Line Spacing
21645
21646 The XNLineSpace argument specifies to the input method what
21647 line spacing is to be used in the preedit window if more than
21648 one line is to be used. This argument is of type int.
21649
21650 If this value is left unspecified, the default is determined by
21651 the input method.
21652
21653Cursor
21654
21655 The XNCursor argument specifies to the input method what cursor
21656 is to be used in the specified window. This argument is of type
21657 Cursor.
21658
21659 An invalid argument may generate a BadCursor error when it is
21660 used by the input method. If this value is left unspecified,
21661 the default is determined by the input method.
21662
21663Preedit State
21664
21665 The XNPreeditState argument specifies the state of input
21666 preediting for the input method. Input preediting can be on or
21667 off.
21668
21669 The valid mask names for XNPreeditState are as follows:
21670
21671typedef unsigned long XIMPreeditState;
21672
21673#define XIMPreeditUnknown 0L
21674#define XIMPreeditEnable 1L
21675#define XIMPreeditDisable (1L<<1)
21676
21677
21678 If a value of XIMPreeditEnable is set, then input preediting is
21679 turned on by the input method.
21680
21681 If a value of XIMPreeditDisable is set, then input preediting
21682 is turned off by the input method.
21683
21684 If XNPreeditState is left unspecified, then the state will be
21685 implementation-dependent.
21686
21687 When XNResetState is set to XIMInitialState, the XNPreeditState
21688 value specified at the creation time will be reflected as the
21689 initial state for XmbResetIC and XwcResetIC.
21690
21691 Because this XIC value is optional, a client should call
21692 XGetIMValues with argument XNQueryICValuesList before using
21693 this argument.
21694
21695Preedit State Notify Callback
21696
21697 The preedit state notify callback is triggered by the input
21698 method when the preediting state has changed. The value of the
21699 XNPreeditStateNotifyCallback argument is a pointer to a
21700 structure of type XIMCallback. The generic prototype is as
21701 follows:
21702
21703 void PreeditStateNotifyCallback(XIC ic, XPointer client_data,
21704 XIMPreeditStateNotifyCallbackStruct *call_data);
21705
21706 ic
21707
21708 Specifies the input context.
21709
21710 client_data
21711
21712 Specifies the additional client data.
21713
21714 call_data
21715
21716 Specifies the current preedit state.
21717
21718 The XIMPreeditStateNotifyCallbackStruct structure is defined as
21719 follows:
21720
21721
21722
21723typedef struct _XIMPreeditStateNotifyCallbackStruct {
21724 XIMPreeditState state;
21725} XIMPreeditStateNotifyCallbackStruct;
21726
21727 Because this XIC value is optional, a client should call
21728 XGetIMValues with argument XNQueryICValuesList before using
21729 this argument.
21730
21731Preedit and Status Callbacks
21732
21733 A client that wants to support the input style
21734 XIMPreeditCallbacks must provide a set of preedit callbacks to
21735 the input method. The set of preedit callbacks is as follows:
21736 XNPreeditStartCallback This is called when the input method
21737 starts preedit.
21738 XNPreeditDoneCallback This is called when the input method
21739 stops preedit.
21740 XNPreeditDrawCallback This is called when a number of preedit
21741 keystrokes should be echoed.
21742 XNPreeditCaretCallback This is called to move the text
21743 insertion point within the preedit string.
21744
21745 A client that wants to support the input style
21746 XIMStatusCallbacks must provide a set of status callbacks to
21747 the input method. The set of status callbacks is as follows:
21748 XNStatusStartCallback This is called when the input method
21749 initializes the status area.
21750 XNStatusDoneCallback This is called when the input method no
21751 longer needs the status area.
21752 XNStatusDrawCallback This is called when updating of the status
21753 area is required.
21754
21755 The value of any status or preedit argument is a pointer to a
21756 structure of type XIMCallback.
21757
21758
21759
21760typedef void (*XIMProc)();
21761
21762typedef struct {
21763 XPointer client_data;
21764 XIMProc callback;
21765} XIMCallback;
21766
21767 Each callback has some particular semantics and will carry the
21768 data that expresses the environment necessary to the client
21769 into a specific data structure. This paragraph only describes
21770 the arguments to be used to set the callback.
21771
21772 Setting any of these values while doing preedit may cause
21773 unexpected results.
21774
21775Input Method Callback Semantics
21776
21777 XIM callbacks are procedures defined by clients or text drawing
21778 packages that are to be called from the input method when
21779 selected events occur. Most clients will use a text editing
21780 package or a toolkit and, hence, will not need to define such
21781 callbacks. This section defines the callback semantics, when
21782 they are triggered, and what their arguments are. This
21783 information is mostly useful for X toolkit implementors.
21784
21785 Callbacks are mostly provided so that clients (or text editing
21786 packages) can implement on-the-spot preediting in their own
21787 window. In that case, the input method needs to communicate and
21788 synchronize with the client. The input method needs to
21789 communicate changes in the preedit window when it is under
21790 control of the client. Those callbacks allow the client to
21791 initialize the preedit area, display a new preedit string, move
21792 the text insertion point during preedit, terminate preedit, or
21793 update the status area.
21794
21795 All callback procedures follow the generic prototype:
21796
21797 void CallbackPrototype(XIC ic, XPointer client_data, SomeType
21798 call_data);
21799
21800 ic
21801
21802 Specifies the input context.
21803
21804 client_data
21805
21806 Specifies the additional client data.
21807
21808 call_data
21809
21810 Specifies data specific to the callback.
21811
21812 The call_data argument is a structure that expresses the
21813 arguments needed to achieve the semantics; that is, it is a
21814 specific data structure appropriate to the callback. In cases
21815 where no data is needed in the callback, this call_data
21816 argument is NULL. The client_data argument is a closure that
21817 has been initially specified by the client when specifying the
21818 callback and passed back. It may serve, for example, to inherit
21819 application context in the callback.
21820
21821 The following paragraphs describe the programming semantics and
21822 specific data structure associated with the different reasons.
21823
21824Geometry Callback
21825
21826 The geometry callback is triggered by the input method to
21827 indicate that it wants the client to negotiate geometry. The
21828 generic prototype is as follows:
21829
21830 void GeometryCallback(XIC ic, XPointer client_data, XPointer
21831 call_data);
21832
21833 ic
21834
21835 Specifies the input context.
21836
21837 client_data
21838
21839 Specifies the additional client data.
21840
21841 call_data
21842
21843 Not used for this callback and always passed as NULL.
21844
21845 The callback is called with a NULL call_data argument.
21846
21847Destroy Callback
21848
21849 The destroy callback is triggered by the input method when it
21850 stops service for any reason. After the callback is invoked,
21851 the input context will be freed by Xlib. The generic prototype
21852 is as follows:
21853
21854 void DestroyCallback(XIC ic, XPointer client_data, XPointer
21855 call_data);
21856
21857 ic
21858
21859 Specifies the input context.
21860
21861 client_data
21862
21863 Specifies the additional client data.
21864
21865 call_data
21866
21867 Not used for this callback and always passed as NULL.
21868
21869 The callback is called with a NULL call_data argument.
21870
21871String Conversion Callback
21872
21873 The string conversion callback is triggered by the input method
21874 to request the client to return the string to be converted. The
21875 returned string may be either a multibyte or wide character
21876 string, with an encoding matching the locale bound to the input
21877 context. The callback prototype is as follows:
21878
21879 void StringConversionCallback(XIC ic, XPointer client_data,
21880 XIMStringConversionCallbackStruct *call_data);
21881
21882 ic
21883
21884 Specifies the input method.
21885
21886 client_data
21887
21888 Specifies the additional client data.
21889
21890 call_data
21891
21892 Specifies the amount of the string to be converted.
21893
21894 The callback is passed an XIMStringConversionCallbackStruct
21895 structure in the call_data argument. The text member is an
21896 XIMStringConversionText structure (see section 13.5.6.9) to be
21897 filled in by the client and describes the text to be sent to
21898 the input method. The data pointed to by the string and
21899 feedback elements of the XIMStringConversionText structure will
21900 be freed using XFree by the input method after the callback
21901 returns. So the client should not point to internal buffers
21902 that are critical to the client. Similarly, because the
21903 feedback element is currently reserved for future use, the
21904 client should set feedback to NULL to prevent the library from
21905 freeing memory at some random location due to an uninitialized
21906 pointer.
21907
21908 The XIMStringConversionCallbackStruct structure is defined as
21909 follows:
21910
21911typedef struct _XIMStringConversionCallbackStruct {
21912 XIMStringConversionPosition position;
21913 XIMCaretDirection direction;
21914 short factor;
21915 XIMStringConversionOperation operation;
21916 XIMStringConversionText *text;
21917} XIMStringConversionCallbackStruct;
21918
21919typedef short XIMStringConversionPosition;
21920
21921typedef unsigned short XIMStringConversionOperation;
21922
21923#define XIMStringConversionSubstitution (0x0001)
21924#define XIMStringConversionRetrieval (0x0001)
21925
21926
21927 XIMStringConversionPosition specifies the starting position of
21928 the string to be returned in the XIMStringConversionText
21929 structure. The value identifies a position, in units of
21930 characters, relative to the client's cursor position in the
21931 client's buffer.
21932
21933 The ending position of the text buffer is determined by the
21934 direction and factor members. Specifically, it is the character
21935 position relative to the starting point as defined by the
21936 XIMCaretDirection. The factor member of
21937 XIMStringConversionCallbackStruct specifies the number of
21938 XIMCaretDirection positions to be applied. For example, if the
21939 direction specifies XIMLineEnd and factor is 1, then all
21940 characters from the starting position to the end of the current
21941 display line are returned. If the direction specifies
21942 XIMForwardChar or XIMBackwardChar, then the factor specifies a
21943 relative position, indicated in characters, from the starting
21944 position.
21945
21946 XIMStringConversionOperation specifies whether the string to be
21947 converted should be deleted (substitution) or copied
21948 (retrieval) from the client's buffer. When the
21949 XIMStringConversionOperation is
21950 XIMStringConversionSubstitution, the client must delete the
21951 string to be converted from its own buffer. When the
21952 XIMStringConversionOperation is XIMStringConversionRetrieval,
21953 the client must not delete the string to be converted from its
21954 buffer. The substitute operation is typically used for
21955 reconversion and transliteration conversion, while the
21956 retrieval operation is typically used for context-sensitive
21957 conversion.
21958
21959Preedit State Callbacks
21960
21961 When the input method turns preediting on or off, a
21962 PreeditStartCallback or PreeditDoneCallback callback is
21963 triggered to let the toolkit do the setup or the cleanup for
21964 the preedit region.
21965
21966 int PreeditStartCallback(XIC ic, XPointer client_data, XPointer
21967 call_data);
21968
21969 ic
21970
21971 Specifies the input context.
21972
21973 client_data
21974
21975 Specifies the additional client data.
21976
21977 call_data
21978
21979 Not used for this callback and always passed as NULL.
21980
21981 When preedit starts on the specified input context, the
21982 callback is called with a NULL call_data argument.
21983 PreeditStartCallback will return the maximum size of the
21984 preedit string. A positive number indicates the maximum number
21985 of bytes allowed in the preedit string, and a value of -1
21986 indicates there is no limit.
21987
21988 void PreeditDoneCallback(XIC ic, XPointer client_data, XPointer
21989 call_data);
21990
21991 ic
21992
21993 Specifies the input context.
21994
21995 client_data
21996
21997 Specifies the additional client data.
21998
21999 call_data
22000
22001 Not used for this callback and always passed as NULL.
22002
22003 When preedit stops on the specified input context, the callback
22004 is called with a NULL call_data argument. The client can
22005 release the data allocated by PreeditStartCallback.
22006
22007 PreeditStartCallback should initialize appropriate data needed
22008 for displaying preedit information and for handling further
22009 PreeditDrawCallback calls. Once PreeditStartCallback is called,
22010 it will not be called again before PreeditDoneCallback has been
22011 called.
22012
22013Preedit Draw Callback
22014
22015 This callback is triggered to draw and insert, delete or
22016 replace, preedit text in the preedit region. The preedit text
22017 may include unconverted input text such as Japanese Kana,
22018 converted text such as Japanese Kanji characters, or characters
22019 of both kinds. That string is either a multibyte or wide
22020 character string, whose encoding matches the locale bound to
22021 the input context. The callback prototype is as follows:
22022
22023 void PreeditDrawCallback(XIC ic, XPointer client_data,
22024 XIMPreeditDrawCallbackStruct *call_data);
22025
22026 ic
22027
22028 Specifies the input context.
22029
22030 client_data
22031
22032 Specifies the additional client data.
22033
22034 call_data
22035
22036 Specifies the preedit drawing information.
22037
22038 The callback is passed an XIMPreeditDrawCallbackStruct
22039 structure in the call_data argument. The text member of this
22040 structure contains the text to be drawn. After the string has
22041 been drawn, the caret should be moved to the specified
22042 location.
22043
22044 The XIMPreeditDrawCallbackStruct structure is defined as
22045 follows:
22046
22047
22048
22049typedef struct _XIMPreeditDrawCallbackStruct {
22050 int caret; /* Cursor offset within preedit string */
22051 int chg_first; /* Starting change position */
22052 int chg_length; /* Length of the change in character count */
22053 XIMText *text;
22054} XIMPreeditDrawCallbackStruct;
22055
22056 The client must keep updating a buffer of the preedit text and
22057 the callback arguments referring to indexes in that buffer. The
22058 call_data fields have specific meanings according to the
22059 operation, as follows:
22060 * To indicate text deletion, the call_data member specifies a
22061 NULL text field. The text to be deleted is then the current
22062 text in the buffer from position chg_first (starting at
22063 zero) on a character length of chg_length.
22064 * When text is non-NULL, it indicates insertion or
22065 replacement of text in the buffer.
22066 * The chg_length member identifies the number of characters
22067 in the current preedit buffer that are affected by this
22068 call. A positive chg_length indicates that chg_length
22069 number of characters, starting at chg_first, must be
22070 deleted or must be replaced by text, whose length is
22071 specified in the XIMText structure.
22072 * A chg_length value of zero indicates that text must be
22073 inserted right at the position specified by chg_first. A
22074 value of zero for chg_first specifies the first character
22075 in the buffer.
22076 * chg_length and chg_first combine to identify the
22077 modification required to the preedit buffer; beginning at
22078 chg_first, replace chg_length number of characters with the
22079 text in the supplied XIMText structure. For example,
22080 suppose the preedit buffer contains the string "ABCDE".
22081 *
22082
22083Text: A B C D E
22084 ^ ^ ^ ^ ^ ^
22085CharPos: 0 1 2 3 4 5
22086
22087
22088
22089 The CharPos in the diagram shows the location of the
22090 character position relative to the character.
22091 * If the value of chg_first is 1 and the value of chg_length
22092 is 3, this says to replace 3 characters beginning at
22093 character position 1 with the string in the XIMText
22094 structure. Hence, BCD would be replaced by the value in the
22095 structure.
22096 * Though chg_length and chg_first are both signed integers
22097 they will never have a negative value.
22098 * The caret member identifies the character position before
22099 which the cursor should be placed - after modification to
22100 the preedit buffer has been completed. For example, if
22101 caret is zero, the cursor is at the beginning of the
22102 buffer. If the caret is one, the cursor is between the
22103 first and second character.
22104
22105
22106typedef struct _XIMText {
22107 unsigned short length;
22108 XIMFeedback * feedback;
22109 Bool encoding_is_wchar;
22110 union {
22111 char * multi_byte;
22112 wchar_t * wide_char;
22113 } string;
22114} XIMText;
22115
22116 The text string passed is actually a structure specifying as
22117 follows:
22118 * The length member is the text length in characters.
22119 * The encoding_is_wchar member is a value that indicates if
22120 the text string is encoded in wide character or multibyte
22121 format. The text string may be passed either as multibyte
22122 or as wide character; the input method controls in which
22123 form data is passed. The client's callback routine must be
22124 able to handle data passed in either form.
22125 * The string member is the text string.
22126 * The feedback member indicates rendering type for each
22127 character in the string member. If string is NULL
22128 (indicating that only highlighting of the existing preedit
22129 buffer should be updated), feedback points to length
22130 highlight elements that should be applied to the existing
22131 preedit buffer, beginning at chg_first.
22132
22133 The feedback member expresses the types of rendering feedback
22134 the callback should apply when drawing text. Rendering of the
22135 text to be drawn is specified either in generic ways (for
22136 example, primary, secondary) or in specific ways (reverse,
22137 underline). When generic indications are given, the client is
22138 free to choose the rendering style. It is necessary, however,
22139 that primary and secondary be mapped to two distinct rendering
22140 styles.
22141
22142 If an input method wants to control display of the preedit
22143 string, an input method can indicate the visibility hints using
22144 feedbacks in a specific way. The XIMVisibleToForward,
22145 XIMVisibleToBackword, and XIMVisibleToCenter masks are
22146 exclusively used for these visibility hints. The
22147 XIMVisibleToForward mask indicates that the preedit text is
22148 preferably displayed in the primary draw direction from the
22149 caret position in the preedit area forward. The
22150 XIMVisibleToBackword mask indicates that the preedit text is
22151 preferably displayed from the caret position in the preedit
22152 area backward, relative to the primary draw direction. The
22153 XIMVisibleToCenter mask indicates that the preedit text is
22154 preferably displayed with the caret position in the preedit
22155 area centered.
22156
22157 The insertion point of the preedit string could exist outside
22158 of the visible area when visibility hints are used. Only one of
22159 the masks is valid for the entire preedit string, and only one
22160 character can hold one of these feedbacks for a given input
22161 context at one time. This feedback may be OR'ed together with
22162 another highlight (such as XIMReverse). Only the most recently
22163 set feedback is valid, and any previous feedback is
22164 automatically canceled. This is a hint to the client, and the
22165 client is free to choose how to display the preedit string.
22166
22167 The feedback member also specifies how rendering of the text
22168 argument should be performed. If the feedback is NULL, the
22169 callback should apply the same feedback as is used for the
22170 surrounding characters in the preedit buffer; if chg_first is
22171 at a highlight boundary, the client can choose which of the two
22172 highlights to use. If feedback is not NULL, feedback specifies
22173 an array defining the rendering for each character of the
22174 string, and the length of the array is thus length.
22175
22176 If an input method wants to indicate that it is only updating
22177 the feedback of the preedit text without changing the content
22178 of it, the XIMText structure will contain a NULL value for the
22179 string field, the number of characters affected (relative to
22180 chg_first) will be in the length field, and the feedback field
22181 will point to an array of XIMFeedback.
22182
22183 Each element in the feedback array is a bitmask represented by
22184 a value of type XIMFeedback. The valid mask names are as
22185 follows:
22186
22187typedef unsigned long XIMFeedback;
22188
22189#define XIMReverse 1L
22190#define XIMUnderline (1L<<1)
22191#define XIMHighlight (1L<<2)
22192#define XIMPrimary (1L<<5)*
22193#define XIMSecondary (1L<<6)*
22194#define XIMTertiary (1L<<7)*
22195#define XIMVisibleToForward (1L<<8)
22196#define XIMVisibleToBackward (1L<<9)
22197#define XIMVisibleToCenter (1L<<10)
22198
22199*/- The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorr
22200ectly defined in
22201the R5 specification. The X Consortium's X11R5 implementation correctly
22202implemented the values for these highlights. The value of these highligh
22203ts has
22204been corrected in this specification to agree with the values in the
22205Consortium's X11R5 and X11R6 implementations.
22206
22207
22208 Characters drawn with the XIMReverse highlight should be drawn
22209 by swapping the foreground and background colors used to draw
22210 normal, unhighlighted characters. Characters drawn with the
22211 XIMUnderline highlight should be underlined. Characters drawn
22212 with the XIMHighlight, XIMPrimary, XIMSecondary, and
22213 XIMTertiary highlights should be drawn in some unique manner
22214 that must be different from XIMReverse and XIMUnderline. The
22215 values for XIMPrimary, XIMSecondary, and XIMTertiary were
22216 incorrectly defined in the R5 specification. The X Consortium's
22217 X11R5 implementation correctly implemented the values for these
22218 highlights. The value of these highlights has been corrected in
22219 this specification to agree with the values in the Consortium's
22220 X11R5 and X11R6 implementations.
22221
22222Preedit Caret Callback
22223
22224 An input method may have its own navigation keys to allow the
22225 user to move the text insertion point in the preedit area (for
22226 example, to move backward or forward). Consequently, input
22227 method needs to indicate to the client that it should move the
22228 text insertion point. It then calls the PreeditCaretCallback.
22229
22230 void PreeditCaretCallback(XIC ic, XPointer client_data,
22231 XIMPreeditCaretCallbackStruct *call_data);
22232
22233 ic
22234
22235 Specifies the input context.
22236
22237 client_data
22238
22239 Specifies the additional client data.
22240
22241 call_data
22242
22243 Specifies the preedit caret information.
22244
22245 The input method will trigger PreeditCaretCallback to move the
22246 text insertion point during preedit. The call_data argument
22247 contains a pointer to an XIMPreeditCaretCallbackStruct
22248 structure, which indicates where the caret should be moved. The
22249 callback must move the insertion point to its new location and
22250 return, in field position, the new offset value from the
22251 initial position.
22252
22253 The XIMPreeditCaretCallbackStruct structure is defined as
22254 follows:
22255
22256
22257
22258typedef struct _XIMPreeditCaretCallbackStruct {
22259 int position; /* Caret offset within preedit string */
22260 XIMCaretDirection direction; /* Caret moves direction */
22261 XIMCaretStyle style; /* Feedback of the caret */
22262} XIMPreeditCaretCallbackStruct;
22263
22264 The XIMCaretStyle structure is defined as follows:
22265
22266
22267
22268typedef enum {
22269 XIMIsInvisible, /* Disable caret feedback */
22270 XIMIsPrimary, /* UI defined caret feedback */
22271 XIMIsSecondary, /* UI defined caret feedback */
22272} XIMCaretStyle;
22273
22274 The XIMCaretDirection structure is defined as follows:
22275
22276
22277
22278typedef enum {
22279 XIMForwardChar, XIMBackwardChar,
22280 XIMForwardWord, XIMBackwardWord,
22281 XIMCaretUp, XIMCaretDown,
22282 XIMNextLine, XIMPreviousLine,
22283 XIMLineStart, XIMLineEnd,
22284 XIMAbsolutePosition,
22285 XIMDontChange,
22286 } XIMCaretDirection;
22287
22288 These values are defined as follows:
22289 XIMForwardChar Move the caret forward one character position.
22290 XIMBackwardChar Move the caret backward one character position.
22291 XIMForwardWord Move the caret forward one word.
22292 XIMBackwardWord Move the caret backward one word.
22293 XIMCaretUp Move the caret up one line keeping the current
22294 horizontal offset.
22295 XIMCaretDown Move the caret down one line keeping the current
22296 horizontal offset.
22297 XIMPreviousLine Move the caret to the beginning of the previous
22298 line.
22299 XIMNextLine Move the caret to the beginning of the next line.
22300 XIMLineStart Move the caret to the beginning of the current
22301 display line that contains the caret.
22302 XIMLineEnd Move the caret to the end of the current display
22303 line that contains the caret.
22304 XIMAbsolutePosition The callback must move to the location
22305 specified by the position field of the callback data, indicated
22306 in characters, starting from the beginning of the preedit text.
22307 Hence, a value of zero means move back to the beginning of the
22308 preedit text.
22309 XIMDontChange The caret position does not change.
22310
22311Status Callbacks
22312
22313 An input method may communicate changes in the status of an
22314 input context (for example, created, destroyed, or focus
22315 changes) with three status callbacks: StatusStartCallback,
22316 StatusDoneCallback, and StatusDrawCallback.
22317
22318 When the input context is created or gains focus, the input
22319 method calls the StatusStartCallback callback.
22320
22321 void StatusStartCallback(XIC ic, XPointer client_data, XPointer
22322 call_data);
22323
22324 ic
22325
22326 Specifies the input context.
22327
22328 client_data
22329
22330 Specifies the additional client data.
22331
22332 call_data
22333
22334 Not used for this callback and always passed as NULL.
22335
22336 The callback should initialize appropriate data for displaying
22337 status and for responding to StatusDrawCallback calls. Once
22338 StatusStartCallback is called, it will not be called again
22339 before StatusDoneCallback has been called.
22340
22341 When an input context is destroyed or when it loses focus, the
22342 input method calls StatusDoneCallback.
22343
22344 void StatusDoneCallback(XIC ic, XPointer client_data, XPointer
22345 call_data);
22346
22347 ic
22348
22349 Specifies the input context.
22350
22351 client_data
22352
22353 Specifies the additional client data.
22354
22355 call_data
22356
22357 Not used for this callback and always passed as NULL.
22358
22359 The callback may release any data allocated on StatusStart.
22360
22361 When an input context status has to be updated, the input
22362 method calls StatusDrawCallback.
22363
22364 void StatusDrawCallback(XIC ic, XPointer client_data,
22365 XIMStatusDrawCallbackStruct *call_data);
22366
22367 ic
22368
22369 Specifies the input context.
22370
22371 client_data
22372
22373 Specifies the additional client data.
22374
22375 call_data
22376
22377 Specifies the status drawing information.
22378
22379 The callback should update the status area by either drawing a
22380 string or imaging a bitmap in the status area.
22381
22382 The XIMStatusDataType and XIMStatusDrawCallbackStruct
22383 structures are defined as follows:
22384
22385
22386
22387typedef enum {
22388 XIMTextType,
22389 XIMBitmapType,
22390} XIMStatusDataType;
22391
22392typedef struct _XIMStatusDrawCallbackStruct {
22393 XIMStatusDataType type;
22394 union {
22395 XIMText *text;
22396 Pixmap bitmap;
22397 } data;
22398} XIMStatusDrawCallbackStruct;
22399
22400 The feedback styles XIMVisibleToForward, XIMVisibleToBackword,
22401 and XIMVisibleToCenter are not relevant and will not appear in
22402 the XIMFeedback element of the XIMText structure.
22403
22404Event Filtering
22405
22406 Xlib provides the ability for an input method to register a
22407 filter internal to Xlib. This filter is called by a client (or
22408 toolkit) by calling XFilterEvent after calling XNextEvent. Any
22409 client that uses the XIM interface should call XFilterEvent to
22410 allow input methods to process their events without knowledge
22411 of the client's dispatching mechanism. A client's user
22412 interface policy may determine the priority of event filters
22413 with respect to other event-handling mechanisms (for example,
22414 modal grabs).
22415
22416 Clients may not know how many filters there are, if any, and
22417 what they do. They may only know if an event has been filtered
22418 on return of XFilterEvent. Clients should discard filtered
22419 events.
22420
22421 To filter an event, use XFilterEvent.
22422
22423 Bool XFilterEvent(XEvent *event, Window w);
22424
22425 event
22426
22427 Specifies the event to filter.
22428
22429 w
22430
22431 Specifies the window for which the filter is to be applied.
22432
22433 If the window argument is None, XFilterEvent applies the filter
22434 to the window specified in the XEvent structure. The window
22435 argument is provided so that layers above Xlib that do event
22436 redirection can indicate to which window an event has been
22437 redirected.
22438
22439 If XFilterEvent returns True, then some input method has
22440 filtered the event, and the client should discard the event. If
22441 XFilterEvent returns False, then the client should continue
22442 processing the event.
22443
22444 If a grab has occurred in the client and XFilterEvent returns
22445 True, the client should ungrab the keyboard.
22446
22447Getting Keyboard Input
22448
22449 To get composed input from an input method, use XmbLookupString
22450 or XwcLookupString.
22451
22452 int XmbLookupString(XIC ic, XKeyPressedEvent *event, char
22453 *buffer_return, int bytes_buffer, KeySym *keysym_return, Status
22454 *status_return);
22455
22456 int XwcLookupString(XIC ic, XKeyPressedEvent *event, wchar_t
22457 *buffer_return, int wchars_buffer, KeySym *keysym_return,
22458 Status *status_return);
22459
22460 ic
22461
22462 Specifies the input context.
22463
22464 event
22465
22466 Specifies the key event to be used.
22467
22468 buffer_return
22469
22470 Returns a multibyte string or wide character string (if any)
22471 from the input method.
22472
22473 bytes_buffer
22474
22475 wchars_buffer
22476
22477 Specifies space available in the return buffer.
22478
22479 keysym_return
22480
22481 Returns the KeySym computed from the event if this argument is
22482 not NULL.
22483
22484 status_return
22485
22486 Returns a value indicating what kind of data is returned.
22487
22488 The XmbLookupString and XwcLookupString functions return the
22489 string from the input method specified in the buffer_return
22490 argument. If no string is returned, the buffer_return argument
22491 is unchanged.
22492
22493 The KeySym into which the KeyCode from the event was mapped is
22494 returned in the keysym_return argument if it is non-NULL and
22495 the status_return argument indicates that a KeySym was
22496 returned. If both a string and a KeySym are returned, the
22497 KeySym value does not necessarily correspond to the string
22498 returned.
22499
22500 XmbLookupString returns the length of the string in bytes, and
22501 XwcLookupString returns the length of the string in characters.
22502 Both XmbLookupString and XwcLookupString return text in the
22503 encoding of the locale bound to the input method of the
22504 specified input context.
22505
22506 Each string returned by XmbLookupString and XwcLookupString
22507 begins in the initial state of the encoding of the locale (if
22508 the encoding of the locale is state-dependent).
22509
22510Note
22511
22512 To insure proper input processing, it is essential that the
22513 client pass only KeyPress events to XmbLookupString and
22514 XwcLookupString. Their behavior when a client passes a
22515 KeyRelease event is undefined.
22516
22517 Clients should check the status_return argument before using
22518 the other returned values. These two functions both return a
22519 value to status_return that indicates what has been returned in
22520 the other arguments. The possible values returned are:
22521 XBufferOverflow The input string to be returned is too large
22522 for the supplied buffer_return. The required size
22523 (XmbLookupString in bytes; XwcLookupString in characters) is
22524 returned as the value of the function, and the contents of
22525 buffer_return and keysym_return are not modified. The client
22526 should recall the function with the same event and a buffer of
22527 adequate size to obtain the string.
22528 XLookupNone No consistent input has been composed so far. The
22529 contents of buffer_return and keysym_return are not modified,
22530 and the function returns zero.
22531 XLookupChars Some input characters have been composed. They are
22532 placed in the buffer_return argument, and the string length is
22533 returned as the value of the function. The string is encoded in
22534 the locale bound to the input context. The content of the
22535 keysym_return argument is not modified.
22536 XLookupKeySym A KeySym has been returned instead of a string
22537 and is returned in keysym_return. The content of the
22538 buffer_return argument is not modified, and the function
22539 returns zero.
22540 XLookupBoth Both a KeySym and a string are returned;
22541 XLookupChars and XLookupKeySym occur simultaneously.
22542
22543 It does not make any difference if the input context passed as
22544 an argument to XmbLookupString and XwcLookupString is the one
22545 currently in possession of the focus or not. Input may have
22546 been composed within an input context before it lost the focus,
22547 and that input may be returned on subsequent calls to
22548 XmbLookupString or XwcLookupString even though it does not have
22549 any more keyboard focus.
22550
22551Input Method Conventions
22552
22553 The input method architecture is transparent to the client.
22554 However, clients should respect a number of conventions in
22555 order to work properly. Clients must also be aware of possible
22556 effects of synchronization between input method and library in
22557 the case of a remote input server.
22558
22559Client Conventions
22560
22561 A well-behaved client (or toolkit) should first query the input
22562 method style. If the client cannot satisfy the requirements of
22563 the supported styles (in terms of geometry management or
22564 callbacks), it should negotiate with the user continuation of
22565 the program or raise an exception or error of some sort.
22566
22567Synchronization Conventions
22568
22569 A KeyPress event with a KeyCode of zero is used exclusively as
22570 a signal that an input method has composed input that can be
22571 returned by XmbLookupString or XwcLookupString. No other use is
22572 made of a KeyPress event with KeyCode of zero.
22573
22574 Such an event may be generated by either a front-end or a
22575 back-end input method in an implementation-dependent manner.
22576 Some possible ways to generate this event include:
22577 * A synthetic event sent by an input method server
22578 * An artificial event created by a input method filter and
22579 pushed onto a client's event queue
22580 * A KeyPress event whose KeyCode value is modified by an
22581 input method filter
22582
22583 When callback support is specified by the client, input methods
22584 will not take action unless they explicitly called back the
22585 client and obtained no response (the callback is not specified
22586 or returned invalid data).
22587
22588String Constants
22589
22590 The following symbols for string constants are defined in
22591 <X11/Xlib.h>. Although they are shown here with particular
22592 macro definitions, they may be implemented as macros, as global
22593 symbols, or as a mixture of the two. The string pointer value
22594 itself is not significant; clients must not assume that
22595 inequality of two values implies inequality of the actual
22596 string data.
22597#define XNVaNestedList "XNVaNestedList"
22598#define XNSeparatorofNestedList "separatorofNestedList"
22599#define XNQueryInputStyle "queryInputStyle"
22600#define XNClientWindow "clientWindow"
22601#define XNInputStyle "inputStyle"
22602#define XNFocusWindow "focusWindow"
22603#define XNResourceName "resourceName"
22604#define XNResourceClass "resourceClass"
22605#define XNGeometryCallback "geometryCallback"
22606#define XNDestroyCallback "destroyCallback"
22607#define XNFilterEvents "filterEvents"
22608#define XNPreeditStartCallback "preeditStartCallback"
22609#define XNPreeditDoneCallback "preeditDoneCallback"
22610#define XNPreeditDrawCallback "preeditDrawCallback"
22611#define XNPreeditCaretCallback "preeditCaretCallback"
22612#define XNPreeditStateNotifyCallback "preeditStateNotifyCallback
22613"
22614#define XNPreeditAttributes "preeditAttributes"
22615#define XNStatusStartCallback "statusStartCallback"
22616#define XNStatusDoneCallback "statusDoneCallback"
22617#define XNStatusDrawCallback "statusDrawCallback"
22618#define XNStatusAttributes "statusAttributes"
22619#define XNArea "area"
22620#define XNAreaNeeded "areaNeeded"
22621#define XNSpotLocation "spotLocation"
22622#define XNColormap "colorMap"
22623#define XNStdColormap "stdColorMap"
22624#define XNForeground "foreground"
22625#define XNBackground "background"
22626#define XNBackgroundPixmap "backgroundPixmap"
22627#define XNFontSet "fontSet"
22628#define XNLineSpace "lineSpace"
22629#define XNCursor "cursor"
22630#define XNQueryIMValuesList "queryIMValuesList"
22631#define XNQueryICValuesList "queryICValuesList"
22632#define XNStringConversionCallback "stringConversionCallback"
22633#define XNStringConversion "stringConversion"
22634#define XNResetState "resetState"
22635#define XNHotKey "hotkey"
22636#define XNHotKeyState "hotkeyState"
22637#define XNPreeditState "preeditState"
22638#define XNVisiblePosition "visiblePosition"
22639#define XNR6PreeditCallbackBehavior "r6PreeditCallback"
22640#define XNRequiredCharSet "requiredCharSet"
22641#define XNQueryOrientation "queryOrientation"
22642#define XNDirectionalDependentDrawing "directionalDependentDrawin
22643g"
22644#define XNContextualDrawing "contextualDrawing"
22645#define XNBaseFontName "baseFontName"
22646#define XNMissingCharSet "missingCharSet"
22647#define XNDefaultString "defaultString"
22648#define XNOrientation "orientation"
22649#define XNFontInfo "fontInfo"
22650#define XNOMAutomatic "omAutomatic"
22651
22652
22653Chapter 14. Inter-Client Communication Functions
22654
22655 Table of Contents
22656
22657 Client to Window Manager Communication
22658
22659 Manipulating Top-Level Windows
22660 Converting String Lists
22661 Setting and Reading Text Properties
22662 Setting and Reading the WM_NAME Property
22663 Setting and Reading the WM_ICON_NAME Property
22664 Setting and Reading the WM_HINTS Property
22665 Setting and Reading the WM_NORMAL_HINTS Property
22666 Setting and Reading the WM_CLASS Property
22667 Setting and Reading the WM_TRANSIENT_FOR Property
22668 Setting and Reading the WM_PROTOCOLS Property
22669 Setting and Reading the WM_COLORMAP_WINDOWS Property
22670 Setting and Reading the WM_ICON_SIZE Property
22671 Using Window Manager Convenience Functions
22672
22673 Client to Session Manager Communication
22674
22675 Setting and Reading the WM_COMMAND Property
22676 Setting and Reading the WM_CLIENT_MACHINE Property
22677
22678 Standard Colormaps
22679
22680 Standard Colormap Properties and Atoms
22681 Setting and Obtaining Standard Colormaps
22682
22683 The Inter-Client Communication Conventions Manual, hereafter
22684 referred to as the ICCCM, details the X Consortium approved
22685 conventions that govern inter-client communications. These
22686 conventions ensure peer-to-peer client cooperation in the use
22687 of selections, cut buffers, and shared resources as well as
22688 client cooperation with window and session managers. For
22689 further information, see the Inter-Client Communication
22690 Conventions Manual.
22691
22692 Xlib provides a number of standard properties and programming
22693 interfaces that are ICCCM compliant. The predefined atoms for
22694 some of these properties are defined in the <X11/Xatom.h>
22695 header file, where to avoid name conflicts with user symbols
22696 their #define name has an XA_ prefix. For further information
22697 about atoms and properties, see section 4.3.
22698
22699 Xlib's selection and cut buffer mechanisms provide the primary
22700 programming interfaces by which peer client applications
22701 communicate with each other (see sections 4.5 and 16.6). The
22702 functions discussed in this chapter provide the primary
22703 programming interfaces by which client applications communicate
22704 with their window and session managers as well as share
22705 standard colormaps.
22706
22707 The standard properties that are of special interest for
22708 communicating with window and session managers are:
22709 Name Type Format Description
22710 WM_CLASS STRING 8 Set by application programs to allow window
22711 and session managers to obtain the application's resources from
22712 the resource database.
22713 WM_CLIENT_MACHINE TEXT The string name of the machine on
22714 which the client application is running.
22715 WM_COLORMAP_WINDOWS WINDOWS 32 The list of window IDs that may
22716 need a different colormap from that of their top-level window.
22717 WM_COMMAND TEXT The command and arguments, null separated,
22718 used to invoke the application.
22719 WM_HINTS WM_HINTS 32 Additional hints set by the client for use
22720 by the window manager. The C type of this property is XWMHints.
22721 WM_ICON_NAME TEXT The name to be used in an icon.
22722 WM_ICON_SIZE WM_ICON_SIZE 32 The window manager may set this
22723 property on the root window to specify the icon sizes it
22724 supports. The C type of this property is XIconSize.
22725 WM_NAME TEXT The name of the application.
22726 WM_NORMAL_HINTS WM_NORMAL_HINTS 32 Size hints for a window in
22727 its normal state. The C type of this property is XSizeHints.
22728 WM_PROTOCOLS ATOM 32 List of atoms that identify the
22729 communications protocols between the client and window manager
22730 in which the client is willing to participate.
22731 WM_STATE WM_STATE 32 Intended for communication between window
22732 and session managers only.
22733 WM_TRANSIENT_FOR WINDOW 32 Set by application programs to
22734 indicate to the window manager that a transient top-level
22735 window, such as a dialog box.
22736
22737 The remainder of this chapter discusses:
22738 * Client to window manager communication
22739 * Client to session manager communication
22740 * Standard colormaps
22741
22742Client to Window Manager Communication
22743
22744 This section discusses how to:
22745 * Manipulate top-level windows
22746 * Convert string lists
22747 * Set and read text properties
22748 * Set and read the WM_NAME property
22749 * Set and read the WM_ICON_NAME property
22750 * Set and read the WM_HINTS property
22751 * Set and read the WM_NORMAL_HINTS property
22752 * Set and read the WM_CLASS property
22753 * Set and read the WM_TRANSIENT_FOR property
22754 * Set and read the WM_PROTOCOLS property
22755 * Set and read the WM_COLORMAP_WINDOWS property
22756 * Set and read the WM_ICON_SIZE property
22757 * Use window manager convenience functions
22758
22759Manipulating Top-Level Windows
22760
22761 Xlib provides functions that you can use to change the
22762 visibility or size of top-level windows (that is, those that
22763 were created as children of the root window). Note that the
22764 subwindows that you create are ignored by window managers.
22765 Therefore, you should use the basic window functions described
22766 in chapter 3 to manipulate your application's subwindows.
22767
22768 To request that a top-level window be iconified, use
22769 XIconifyWindow.
22770
22771 Status XIconifyWindow(Display *display, Window w, int
22772 screen_number);
22773
22774 display
22775
22776 Specifies the connection to the X server.
22777
22778 w
22779
22780 Specifies the window.
22781
22782 screen_number
22783
22784 Specifies the appropriate screen number on the host server.
22785
22786 The XIconifyWindow function sends a WM_CHANGE_STATE
22787 ClientMessage event with a format of 32 and a first data
22788 element of IconicState (as described in section 4.1.4 of the
22789 Inter-Client Communication Conventions Manual) and a window of
22790 w to the root window of the specified screen with an event mask
22791 set to SubstructureNotifyMask | SubstructureRedirectMask.
22792 Window managers may elect to receive this message and if the
22793 window is in its normal state, may treat it as a request to
22794 change the window's state from normal to iconic. If the
22795 WM_CHANGE_STATE property cannot be interned, XIconifyWindow
22796 does not send a message and returns a zero status. It returns a
22797 nonzero status if the client message is sent successfully;
22798 otherwise, it returns a zero status.
22799
22800 To request that a top-level window be withdrawn, use
22801 XWithdrawWindow.
22802
22803 Status XWithdrawWindow(Display *display, Window w, int
22804 screen_number);
22805
22806 display
22807
22808 Specifies the connection to the X server.
22809
22810 w
22811
22812 Specifies the window.
22813
22814 screen_number
22815
22816 Specifies the appropriate screen number on the host server.
22817
22818 The XWithdrawWindow function unmaps the specified window and
22819 sends a synthetic UnmapNotify event to the root window of the
22820 specified screen. Window managers may elect to receive this
22821 message and may treat it as a request to change the window's
22822 state to withdrawn. When a window is in the withdrawn state,
22823 neither its normal nor its iconic representations is visible.
22824 It returns a nonzero status if the UnmapNotify event is
22825 successfully sent; otherwise, it returns a zero status.
22826
22827 XWithdrawWindow can generate a BadWindow error.
22828
22829 To request that a top-level window be reconfigured, use
22830 XReconfigureWMWindow.
22831
22832 Status XReconfigureWMWindow(Display *display, Window w, int
22833 screen_number, unsigned int value_mask, XWindowChanges
22834 *values);
22835
22836 display
22837
22838 Specifies the connection to the X server.
22839
22840 w
22841
22842 Specifies the window.
22843
22844 screen_number
22845
22846 Specifies the appropriate screen number on the host server.
22847
22848 value_mask
22849
22850 Specifies which values are to be set using information in the
22851 values structure. This mask is the bitwise inclusive OR of the
22852 valid configure window values bits.
22853
22854 values
22855
22856 Specifies the XWindowChanges structure.
22857
22858 The XReconfigureWMWindow function issues a ConfigureWindow
22859 request on the specified top-level window. If the stacking mode
22860 is changed and the request fails with a BadMatch error, the
22861 error is trapped by Xlib and a synthetic ConfigureRequestEvent
22862 containing the same configuration parameters is sent to the
22863 root of the specified window. Window managers may elect to
22864 receive this event and treat it as a request to reconfigure the
22865 indicated window. It returns a nonzero status if the request or
22866 event is successfully sent; otherwise, it returns a zero
22867 status.
22868
22869 XReconfigureWMWindow can generate BadValue and BadWindow
22870 errors.
22871
22872Converting String Lists
22873
22874 Many of the text properties allow a variety of types and
22875 formats. Because the data stored in these properties are not
22876 simple null-terminated strings, an XTextProperty structure is
22877 used to describe the encoding, type, and length of the text as
22878 well as its value. The XTextProperty structure contains:
22879
22880
22881typedef struct {
22882 unsigned char *value; /* property data */
22883 Atom encoding; /* type of property */
22884 int format; /* 8, 16, or 32 */
22885 unsigned long nitems; /* number of items in value */
22886} XTextProperty;
22887
22888 Xlib provides functions to convert localized text to or from
22889 encodings that support the inter-client communication
22890 conventions for text. In addition, functions are provided for
22891 converting between lists of pointers to character strings and
22892 text properties in the STRING encoding.
22893
22894 The functions for localized text return a signed integer error
22895 status that encodes Success as zero, specific error conditions
22896 as negative numbers, and partial conversion as a count of
22897 unconvertible characters.
22898
22899#define #XNoMemory -1
22900#define #XLocaleNotSupported -2
22901#define #XConverterNotFound -3
22902
22903typedef enum {
22904 XStringStyle, /* STRING */
22905 XCompoundTextStyle, /* COMPOUND_TEXT */
22906 XTextStyle, /* text in owner's encoding (current loc
22907ale) */
22908 XStdICCTextStyle /* STRING, else COMPOUND_TEXT */
22909} XICCEncodingStyle;
22910
22911 To convert a list of text strings to an XTextProperty
22912 structure, use XmbTextListToTextProperty or
22913 XwcTextListToTextProperty.
22914
22915 int XmbTextListToTextProperty(Display *display, char **list,
22916 int count, XICCEncodingStyle style, XTextProperty
22917 *text_prop_return);
22918
22919 int XwcTextListToTextProperty(Display *display, wchar_t **list,
22920 int count, XICCEncodingStyle style, XTextProperty
22921 *text_prop_return);
22922
22923 display
22924
22925 Specifies the connection to the X server.
22926
22927 list
22928
22929 Specifies a list of null-terminated character strings.
22930
22931 count
22932
22933 Specifies the number of strings specified.
22934
22935 style
22936
22937 Specifies the manner in which the property is encoded.
22938
22939 text_prop_return
22940
22941 Returns the XTextProperty structure.
22942
22943 The XmbTextListToTextProperty and XwcTextListToTextProperty
22944 functions set the specified XTextProperty value to a set of
22945 null-separated elements representing the concatenation of the
22946 specified list of null-terminated text strings. A final
22947 terminating null is stored at the end of the value field of
22948 text_prop_return but is not included in the nitems member.
22949
22950 The functions set the encoding field of text_prop_return to an
22951 Atom for the specified display naming the encoding determined
22952 by the specified style and convert the specified text list to
22953 this encoding for storage in the text_prop_return value field.
22954 If the style XStringStyle or XCompoundTextStyle is specified,
22955 this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
22956 If the style XTextStyle is specified, this encoding is the
22957 encoding of the current locale. If the style XStdICCTextStyle
22958 is specified, this encoding is ``STRING'' if the text is fully
22959 convertible to STRING, else ``COMPOUND_TEXT''.
22960
22961 If insufficient memory is available for the new value string,
22962 the functions return XNoMemory. If the current locale is not
22963 supported, the functions return XLocaleNotSupported. In both of
22964 these error cases, the functions do not set text_prop_return.
22965
22966 To determine if the functions are guaranteed not to return
22967 XLocaleNotSupported, use XSupportsLocale.
22968
22969 If the supplied text is not fully convertible to the specified
22970 encoding, the functions return the number of unconvertible
22971 characters. Each unconvertible character is converted to an
22972 implementation-defined and encoding-specific default string.
22973 Otherwise, the functions return Success. Note that full
22974 convertibility to all styles except XStringStyle is guaranteed.
22975
22976 To free the storage for the value field, use XFree.
22977
22978 To obtain a list of text strings from an XTextProperty
22979 structure, use XmbTextPropertyToTextList or
22980 XwcTextPropertyToTextList.
22981
22982 int XmbTextPropertyToTextList(Display *display, XTextProperty
22983 *text_prop, char ***list_return, int *count_return);
22984
22985 int XwcTextPropertyToTextList(Display *display, XTextProperty
22986 *text_prop, wchar_t ***list_return, int *count_return);
22987
22988 display
22989
22990 Specifies the connection to the X server.
22991
22992 text_prop
22993
22994 Specifies the XTextProperty structure to be used.
22995
22996 list_return
22997
22998 Returns a list of null-terminated character strings.
22999
23000 count_return
23001
23002 Returns the number of strings.
23003
23004 The XmbTextPropertyToTextList and XwcTextPropertyToTextList
23005 functions return a list of text strings in the current locale
23006 representing the null-separated elements of the specified
23007 XTextProperty structure. The data in text_prop must be format
23008 8.
23009
23010 Multiple elements of the property (for example, the strings in
23011 a disjoint text selection) are separated by a null byte. The
23012 contents of the property are not required to be
23013 null-terminated; any terminating null should not be included in
23014 text_prop.nitems.
23015
23016 If insufficient memory is available for the list and its
23017 elements, XmbTextPropertyToTextList and
23018 XwcTextPropertyToTextList return XNoMemory. If the current
23019 locale is not supported, the functions return
23020 XLocaleNotSupported. Otherwise, if the encoding field of
23021 text_prop is not convertible to the encoding of the current
23022 locale, the functions return XConverterNotFound. For supported
23023 locales, existence of a converter from COMPOUND_TEXT, STRING or
23024 the encoding of the current locale is guaranteed if
23025 XSupportsLocale returns True for the current locale (but the
23026 actual text may contain unconvertible characters). Conversion
23027 of other encodings is implementation-dependent. In all of these
23028 error cases, the functions do not set any return values.
23029
23030 Otherwise, XmbTextPropertyToTextList and
23031 XwcTextPropertyToTextList return the list of null-terminated
23032 text strings to list_return and the number of text strings to
23033 count_return.
23034
23035 If the value field of text_prop is not fully convertible to the
23036 encoding of the current locale, the functions return the number
23037 of unconvertible characters. Each unconvertible character is
23038 converted to a string in the current locale that is specific to
23039 the current locale. To obtain the value of this string, use
23040 XDefaultString. Otherwise, XmbTextPropertyToTextList and
23041 XwcTextPropertyToTextList return Success.
23042
23043 To free the storage for the list and its contents returned by
23044 XmbTextPropertyToTextList, use XFreeStringList. To free the
23045 storage for the list and its contents returned by
23046 XwcTextPropertyToTextList, use XwcFreeStringList.
23047
23048 To free the in-memory data associated with the specified wide
23049 character string list, use XwcFreeStringList.
23050
23051 void XwcFreeStringList(wchar_t **list);
23052
23053 list
23054
23055 Specifies the list of strings to be freed.
23056
23057 The XwcFreeStringList function frees memory allocated by
23058 XwcTextPropertyToTextList.
23059
23060 To obtain the default string for text conversion in the current
23061 locale, use
23062
23063 char *XDefaultString(void);
23064
23065 The XDefaultString function returns the default string used by
23066 Xlib for text conversion (for example, in
23067 XmbTextPropertyToTextList). The default string is the string in
23068 the current locale that is output when an unconvertible
23069 character is found during text conversion. If the string
23070 returned by XDefaultString is the empty string (""), no
23071 character is output in the converted text. XDefaultString does
23072 not return NULL.
23073
23074 The string returned by XDefaultString is independent of the
23075 default string for text drawing; see XCreateFontSet to obtain
23076 the default string for an XFontSet.
23077
23078 The behavior when an invalid codepoint is supplied to any Xlib
23079 function is undefined.
23080
23081 The returned string is null-terminated. It is owned by Xlib and
23082 should not be modified or freed by the client. It may be freed
23083 after the current locale is changed. Until freed, it will not
23084 be modified by Xlib.
23085
23086 To set the specified list of strings in the STRING encoding to
23087 a XTextProperty structure, use XStringListToTextProperty.
23088
23089 Status XStringListToTextProperty(char **list, int count,
23090 XTextProperty *text_prop_return);
23091
23092 list
23093
23094 Specifies a list of null-terminated character strings.
23095
23096 count
23097
23098 Specifies the number of strings.
23099
23100 text_prop_return
23101
23102 Returns the XTextProperty structure.
23103
23104 The XStringListToTextProperty function sets the specified
23105 XTextProperty to be of type STRING (format 8) with a value
23106 representing the concatenation of the specified list of
23107 null-separated character strings. An extra null byte (which is
23108 not included in the nitems member) is stored at the end of the
23109 value field of text_prop_return. The strings are assumed
23110 (without verification) to be in the STRING encoding. If
23111 insufficient memory is available for the new value string,
23112 XStringListToTextProperty does not set any fields in the
23113 XTextProperty structure and returns a zero status. Otherwise,
23114 it returns a nonzero status. To free the storage for the value
23115 field, use XFree.
23116
23117 To obtain a list of strings from a specified XTextProperty
23118 structure in the STRING encoding, use
23119 XTextPropertyToStringList.
23120
23121 Status XTextPropertyToStringList(XTextProperty *text_prop, char
23122 ***list_return, int *count_return);
23123
23124 text_prop
23125
23126 Specifies the XTextProperty structure to be used.
23127
23128 list_return
23129
23130 Returns a list of null-terminated character strings.
23131
23132 count_return
23133
23134 Returns the number of strings.
23135
23136 The XTextPropertyToStringList function returns a list of
23137 strings representing the null-separated elements of the
23138 specified XTextProperty structure. The data in text_prop must
23139 be of type STRING and format 8. Multiple elements of the
23140 property (for example, the strings in a disjoint text
23141 selection) are separated by NULL (encoding 0). The contents of
23142 the property are not null-terminated. If insufficient memory is
23143 available for the list and its elements,
23144 XTextPropertyToStringList sets no return values and returns a
23145 zero status. Otherwise, it returns a nonzero status. To free
23146 the storage for the list and its contents, use XFreeStringList.
23147
23148 To free the in-memory data associated with the specified string
23149 list, use XFreeStringList.
23150
23151 void XFreeStringList(char **list);
23152
23153 list
23154
23155 Specifies the list of strings to be freed.
23156
23157 The XFreeStringList function releases memory allocated by
23158 XmbTextPropertyToTextList and XTextPropertyToStringList and the
23159 missing charset list allocated by XCreateFontSet.
23160
23161Setting and Reading Text Properties
23162
23163 Xlib provides two functions that you can use to set and read
23164 the text properties for a given window. You can use these
23165 functions to set and read those properties of type TEXT
23166 (WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE). In
23167 addition, Xlib provides separate convenience functions that you
23168 can use to set each of these properties. For further
23169 information about these convenience functions, see sections
23170 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.
23171
23172 To set one of a window's text properties, use XSetTextProperty.
23173
23174 void XSetTextProperty(Display *display, Window w, XTextProperty
23175 *text_prop, Atom property);
23176
23177 display
23178
23179 Specifies the connection to the X server.
23180
23181 w
23182
23183 Specifies the window.
23184
23185 text_prop
23186
23187 Specifies the XTextProperty structure to be used.
23188
23189 property
23190
23191 Specifies the property name.
23192
23193 The XSetTextProperty function replaces the existing specified
23194 property for the named window with the data, type, format, and
23195 number of items determined by the value field, the encoding
23196 field, the format field, and the nitems field, respectively, of
23197 the specified XTextProperty structure. If the property does not
23198 already exist, XSetTextProperty sets it for the specified
23199 window.
23200
23201 XSetTextProperty can generate BadAlloc, BadAtom, BadValue, and
23202 BadWindow errors.
23203
23204 To read one of a window's text properties, use
23205 XGetTextProperty.
23206
23207 Status XGetTextProperty(Display *display, Window w,
23208 XTextProperty *text_prop_return, Atom property);
23209
23210 display
23211
23212 Specifies the connection to the X server.
23213
23214 w
23215
23216 Specifies the window.
23217
23218 text_prop_return
23219
23220 Returns the XTextProperty structure.
23221
23222 property
23223
23224 Specifies the property name.
23225
23226 The XGetTextProperty function reads the specified property from
23227 the window and stores the data in the returned XTextProperty
23228 structure. It stores the data in the value field, the type of
23229 the data in the encoding field, the format of the data in the
23230 format field, and the number of items of data in the nitems
23231 field. An extra byte containing null (which is not included in
23232 the nitems member) is stored at the end of the value field of
23233 text_prop_return. The particular interpretation of the
23234 property's encoding and data as text is left to the calling
23235 application. If the specified property does not exist on the
23236 window, XGetTextProperty sets the value field to NULL, the
23237 encoding field to None, the format field to zero, and the
23238 nitems field to zero.
23239
23240 If it was able to read and store the data in the XTextProperty
23241 structure, XGetTextProperty returns a nonzero status;
23242 otherwise, it returns a zero status.
23243
23244 XGetTextProperty can generate BadAtom and BadWindow errors.
23245
23246Setting and Reading the WM_NAME Property
23247
23248 Xlib provides convenience functions that you can use to set and
23249 read the WM_NAME property for a given window.
23250
23251 To set a window's WM_NAME property with the supplied
23252 convenience function, use XSetWMName.
23253
23254 void XSetWMName(Display *display, Window w, XTextProperty
23255 *text_prop);
23256
23257 display
23258
23259 Specifies the connection to the X server.
23260
23261 w
23262
23263 Specifies the window.
23264
23265 text_prop
23266
23267 Specifies the XTextProperty structure to be used.
23268
23269 The XSetWMName convenience function calls XSetTextProperty to
23270 set the WM_NAME property.
23271
23272 To read a window's WM_NAME property with the supplied
23273 convenience function, use XGetWMName.
23274
23275 Status XGetWMName(Display *display, Window w, XTextProperty
23276 *text_prop_return);
23277
23278 display
23279
23280 Specifies the connection to the X server.
23281
23282 w
23283
23284 Specifies the window.
23285
23286 text_prop_return
23287
23288 Returns the XTextProperty structure.
23289
23290 The XGetWMName convenience function calls XGetTextProperty to
23291 obtain the WM_NAME property. It returns a nonzero status on
23292 success; otherwise, it returns a zero status.
23293
23294 The following two functions have been superseded by XSetWMName
23295 and XGetWMName, respectively. You can use these additional
23296 convenience functions for window names that are encoded as
23297 STRING properties.
23298
23299 To assign a name to a window, use XStoreName.
23300
23301 XStoreName(Display *display, Window w, char *window_name);
23302
23303 display
23304
23305 Specifies the connection to the X server.
23306
23307 w
23308
23309 Specifies the window.
23310
23311 window_name
23312
23313 Specifies the window name, which should be a null-terminated
23314 string.
23315
23316 The XStoreName function assigns the name passed to window_name
23317 to the specified window. A window manager can display the
23318 window name in some prominent place, such as the title bar, to
23319 allow users to identify windows easily. Some window managers
23320 may display a window's name in the window's icon, although they
23321 are encouraged to use the window's icon name if one is provided
23322 by the application. If the string is not in the Host Portable
23323 Character Encoding, the result is implementation-dependent.
23324
23325 XStoreName can generate BadAlloc and BadWindow errors.
23326
23327 To get the name of a window, use XFetchName.
23328
23329 Status XFetchName(Display *display, Window w, char
23330 **window_name_return);
23331
23332 display
23333
23334 Specifies the connection to the X server.
23335
23336 w
23337
23338 Specifies the window.
23339
23340 window_name_return
23341
23342 Returns the window name, which is a null-terminated string.
23343
23344 The XFetchName function returns the name of the specified
23345 window. If it succeeds, it returns a nonzero status; otherwise,
23346 no name has been set for the window, and it returns zero. If
23347 the WM_NAME property has not been set for this window,
23348 XFetchName sets window_name_return to NULL. If the data
23349 returned by the server is in the Latin Portable Character
23350 Encoding, then the returned string is in the Host Portable
23351 Character Encoding. Otherwise, the result is
23352 implementation-dependent. When finished with it, a client must
23353 free the window name string using XFree.
23354
23355 XFetchName can generate a BadWindow error.
23356
23357Setting and Reading the WM_ICON_NAME Property
23358
23359 Xlib provides convenience functions that you can use to set and
23360 read the WM_ICON_NAME property for a given window.
23361
23362 To set a window's WM_ICON_NAME property, use XSetWMIconName.
23363
23364 void XSetWMIconName(Display *display, Window w, XTextProperty
23365 *text_prop);
23366
23367 display
23368
23369 Specifies the connection to the X server.
23370
23371 w
23372
23373 Specifies the window.
23374
23375 text_prop
23376
23377 Specifies the XTextProperty structure to be used.
23378
23379 The XSetWMIconName convenience function calls XSetTextProperty
23380 to set the WM_ICON_NAME property.
23381
23382 To read a window's WM_ICON_NAME property, use XGetWMIconName.
23383
23384 Status XGetWMIconName(Display *display, Window w, XTextProperty
23385 *text_prop_return);
23386
23387 display
23388
23389 Specifies the connection to the X server.
23390
23391 w
23392
23393 Specifies the window.
23394
23395 text_prop_return
23396
23397 Returns the XTextProperty structure.
23398
23399 The XGetWMIconName convenience function calls XGetTextProperty
23400 to obtain the WM_ICON_NAME property. It returns a nonzero
23401 status on success; otherwise, it returns a zero status.
23402
23403 The next two functions have been superseded by XSetWMIconName
23404 and XGetWMIconName, respectively. You can use these additional
23405 convenience functions for window names that are encoded as
23406 STRING properties.
23407
23408 To set the name to be displayed in a window's icon, use
23409 XSetIconName.
23410
23411 XSetIconName(Display *display, Window w, char *icon_name);
23412
23413 display
23414
23415 Specifies the connection to the X server.
23416
23417 w
23418
23419 Specifies the window.
23420
23421 icon_name
23422
23423 Specifies the icon name, which should be a null-terminated
23424 string.
23425
23426 If the string is not in the Host Portable Character Encoding,
23427 the result is implementation-dependent. XSetIconName can
23428 generate BadAlloc and BadWindow errors.
23429
23430 To get the name a window wants displayed in its icon, use
23431 XGetIconName.
23432
23433 Status XGetIconName(Display *display, Window w, char
23434 **icon_name_return);
23435
23436 display
23437
23438 Specifies the connection to the X server.
23439
23440 w
23441
23442 Specifies the window.
23443
23444 icon_name_return
23445
23446 Returns the window's icon name, which is a null-terminated
23447 string.
23448
23449 The XGetIconName function returns the name to be displayed in
23450 the specified window's icon. If it succeeds, it returns a
23451 nonzero status; otherwise, if no icon name has been set for the
23452 window, it returns zero. If you never assigned a name to the
23453 window, XGetIconName sets icon_name_return to NULL. If the data
23454 returned by the server is in the Latin Portable Character
23455 Encoding, then the returned string is in the Host Portable
23456 Character Encoding. Otherwise, the result is
23457 implementation-dependent. When finished with it, a client must
23458 free the icon name string using XFree.
23459
23460 XGetIconName can generate a BadWindow error.
23461
23462Setting and Reading the WM_HINTS Property
23463
23464 Xlib provides functions that you can use to set and read the
23465 WM_HINTS property for a given window. These functions use the
23466 flags and the XWMHints structure, as defined in the
23467 <X11/Xutil.h> header file.
23468
23469 To allocate an XWMHints structure, use XAllocWMHints.
23470
23471 XWMHints *XAllocWMHints(void);
23472
23473 The XAllocWMHints function allocates and returns a pointer to
23474 an XWMHints structure. Note that all fields in the XWMHints
23475 structure are initially set to zero. If insufficient memory is
23476 available, XAllocWMHints returns NULL. To free the memory
23477 allocated to this structure, use XFree.
23478
23479 The XWMHints structure contains:
23480/* Window manager hints mask bits */
23481
23482#define InputHint (1L<<0)
23483#define StateHint (1L<<1)
23484#define IconPixmapHint (1L<<2)
23485#define IconWindowHint (1L<<3)
23486#define IconPositionHint (1L<<4)
23487#define IconMaskHint (1L<<5)
23488#define WindowGroupHint (1L<<6)
23489#define UrgencyHint (1L<<8)
23490#define AllHints (InputHint|StateHint|IconPixmapHin
23491t|
23492 IconWIndowHint|IconPositionHint|
23493 IconMaskHint|WindowGroupHint)
23494
23495
23496/* Values */
23497
23498typedef struct {
23499 long flags; /* marks which fields in this structure
23500are defined */
23501 Bool input; /* does this application rely on the win
23502dow manager to
23503 get keyboard input? */
23504 int initial_state; /* see below */
23505 Pixmap icon_pixmap; /* pixmap to be used as icon */
23506 Window icon_window; /* window to be used as icon */
23507 int icon_x, icon_y; /* initial position of icon */
23508 Pixmap icon_mask; /* pixmap to be used as mask for icon_pi
23509xmap */
23510 XID window_group; /* id of related window group */
23511 /* this structure may be extended in the future */
23512} XWMHints;
23513
23514 The input member is used to communicate to the window manager
23515 the input focus model used by the application. Applications
23516 that expect input but never explicitly set focus to any of
23517 their subwindows (that is, use the push model of focus
23518 management), such as X Version 10 style applications that use
23519 real-estate driven focus, should set this member to True.
23520 Similarly, applications that set input focus to their
23521 subwindows only when it is given to their top-level window by a
23522 window manager should also set this member to True.
23523 Applications that manage their own input focus by explicitly
23524 setting focus to one of their subwindows whenever they want
23525 keyboard input (that is, use the pull model of focus
23526 management) should set this member to False. Applications that
23527 never expect any keyboard input also should set this member to
23528 False.
23529
23530 Pull model window managers should make it possible for push
23531 model applications to get input by setting input focus to the
23532 top-level windows of applications whose input member is True.
23533 Push model window managers should make sure that pull model
23534 applications do not break them by resetting input focus to
23535 PointerRoot when it is appropriate (for example, whenever an
23536 application whose input member is False sets input focus to one
23537 of its subwindows).
23538
23539 The definitions for the initial_state flag are:
23540#define WithdrawnState 0
23541#define NormalState 1 /* most applications start this way */
23542#define IconicState 3 /* application wants to start as an icon
23543 */
23544
23545
23546 The icon_mask specifies which pixels of the icon_pixmap should
23547 be used as the icon. This allows for nonrectangular icons. Both
23548 icon_pixmap and icon_mask must be bitmaps. The icon_window lets
23549 an application provide a window for use as an icon for window
23550 managers that support such use. The window_group lets you
23551 specify that this window belongs to a group of other windows.
23552 For example, if a single application manipulates multiple
23553 top-level windows, this allows you to provide enough
23554 information that a window manager can iconify all of the
23555 windows rather than just the one window.
23556
23557 The UrgencyHint flag, if set in the flags field, indicates that
23558 the client deems the window contents to be urgent, requiring
23559 the timely response of the user. The window manager will make
23560 some effort to draw the user's attention to this window while
23561 this flag is set. The client must provide some means by which
23562 the user can cause the urgency flag to be cleared (either
23563 mitigating the condition that made the window urgent or merely
23564 shutting off the alarm) or the window to be withdrawn.
23565
23566 To set a window's WM_HINTS property, use XSetWMHints.
23567
23568 XSetWMHints(Display *display, Window w, XWMHints *wmhints);
23569
23570 display
23571
23572 Specifies the connection to the X server.
23573
23574 w
23575
23576 Specifies the window.
23577
23578 wmhints
23579
23580 Specifies the XWMHints structure to be used.
23581
23582 The XSetWMHints function sets the window manager hints that
23583 include icon information and location, the initial state of the
23584 window, and whether the application relies on the window
23585 manager to get keyboard input.
23586
23587 XSetWMHints can generate BadAlloc and BadWindow errors.
23588
23589 To read a window's WM_HINTS property, use XGetWMHints.
23590
23591 XWMHints *XGetWMHints(Display *display, Window w);
23592
23593 display
23594
23595 Specifies the connection to the X server.
23596
23597 w
23598
23599 Specifies the window.
23600
23601 The XGetWMHints function reads the window manager hints and
23602 returns NULL if no WM_HINTS property was set on the window or
23603 returns a pointer to an XWMHints structure if it succeeds. When
23604 finished with the data, free the space used for it by calling
23605 XFree.
23606
23607 XGetWMHints can generate a BadWindow error.
23608
23609Setting and Reading the WM_NORMAL_HINTS Property
23610
23611 Xlib provides functions that you can use to set or read the
23612 WM_NORMAL_HINTS property for a given window. The functions use
23613 the flags and the XSizeHints structure, as defined in the
23614 <X11/Xutil.h> header file.
23615
23616 The size of the XSizeHints structure may grow in future
23617 releases, as new components are added to support new ICCCM
23618 features. Passing statically allocated instances of this
23619 structure into Xlib may result in memory corruption when
23620 running against a future release of the library. As such, it is
23621 recommended that only dynamically allocated instances of the
23622 structure be used.
23623
23624 To allocate an XSizeHints structure, use XAllocSizeHints.
23625
23626 XSizeHints *XAllocSizeHints(void);
23627
23628 The XAllocSizeHints function allocates and returns a pointer to
23629 an XSizeHints structure. Note that all fields in the XSizeHints
23630 structure are initially set to zero. If insufficient memory is
23631 available, XAllocSizeHints returns NULL. To free the memory
23632 allocated to this structure, use XFree.
23633
23634 The XSizeHints structure contains:
23635/* Size hints mask bits */
23636
23637#define USPosition (1L<<0) /* user specified x,y */
23638#define USSize (1L<<1) /* user specified width,he
23639ight */
23640#define PPosition (1L<<2) /* program specified posis
23641tion */
23642#define PSize (1L<<3) /* program specified size
23643*/
23644#define PMinSize (1L<<4) /* program specified minim
23645um size */
23646#define PMaxSize (1L<<5) /* program specified maxim
23647um size */
23648#define PResizeInc (1L<<5) /* program specified resiz
23649e increments */
23650#define PAspect (1L<<6) /* program specified min a
23651nd max aspect ratios */
23652#define PBaseSize (1L<<8)
23653#define PWinGravity (1L<<9)
23654#define PAllHints (PPosition|Psize|
23655 PMinSize|PMaxSize|
23656 PResizeInc|PAspect)
23657
23658
23659/* Values */
23660
23661typedef struct {
23662 long flags; /* marks which fields in this structure
23663are defined */
23664 int x, y; /* Obsolete */
23665 int width, height; /* Obsolete */
23666 int min_width, min_height;
23667 int max_width, max_height;
23668 int width_inc, height_inc;
23669 struct {
23670 int x; /* numerator */
23671 int y; /* denominator */
23672 } min_aspect, max_aspect;
23673 int base_width, base_height;
23674 int win_gravity;
23675 /* this structure may be extended in the future */
23676} XSizeHints;
23677
23678 The x, y, width, and height members are now obsolete and are
23679 left solely for compatibility reasons. The min_width and
23680 min_height members specify the minimum window size that still
23681 allows the application to be useful. The max_width and
23682 max_height members specify the maximum window size. The
23683 width_inc and height_inc members define an arithmetic
23684 progression of sizes (minimum to maximum) into which the window
23685 prefers to be resized. The min_aspect and max_aspect members
23686 are expressed as ratios of x and y, and they allow an
23687 application to specify the range of aspect ratios it prefers.
23688 The base_width and base_height members define the desired size
23689 of the window. The window manager will interpret the position
23690 of the window and its border width to position the point of the
23691 outer rectangle of the overall window specified by the
23692 win_gravity member. The outer rectangle of the window includes
23693 any borders or decorations supplied by the window manager. In
23694 other words, if the window manager decides to place the window
23695 where the client asked, the position on the parent window's
23696 border named by the win_gravity will be placed where the client
23697 window would have been placed in the absence of a window
23698 manager.
23699
23700 Note that use of the PAllHints macro is highly discouraged.
23701
23702 To set a window's WM_NORMAL_HINTS property, use
23703 XSetWMNormalHints.
23704
23705 void XSetWMNormalHints(Display *display, Window w, XSizeHints
23706 *hints);
23707
23708 display
23709
23710 Specifies the connection to the X server.
23711
23712 w
23713
23714 Specifies the window.
23715
23716 hints
23717
23718 Specifies the size hints for the window in its normal state.
23719
23720 The XSetWMNormalHints function replaces the size hints for the
23721 WM_NORMAL_HINTS property on the specified window. If the
23722 property does not already exist, XSetWMNormalHints sets the
23723 size hints for the WM_NORMAL_HINTS property on the specified
23724 window. The property is stored with a type of WM_SIZE_HINTS and
23725 a format of 32.
23726
23727 XSetWMNormalHints can generate BadAlloc and BadWindow errors.
23728
23729 To read a window's WM_NORMAL_HINTS property, use
23730 XGetWMNormalHints.
23731
23732 Status XGetWMNormalHints(Display *display, Window w, XSizeHints
23733 *hints_return, long *supplied_return);
23734
23735 display
23736
23737 Specifies the connection to the X server.
23738
23739 w
23740
23741 Specifies the window.
23742
23743 hints_return
23744
23745 Returns the size hints for the window in its normal state.
23746
23747 supplied_return
23748
23749 Returns the hints that were supplied by the user.
23750
23751 The XGetWMNormalHints function returns the size hints stored in
23752 the WM_NORMAL_HINTS property on the specified window. If the
23753 property is of type WM_SIZE_HINTS, is of format 32, and is long
23754 enough to contain either an old (pre-ICCCM) or new size hints
23755 structure, XGetWMNormalHints sets the various fields of the
23756 XSizeHints structure, sets the supplied_return argument to the
23757 list of fields that were supplied by the user (whether or not
23758 they contained defined values), and returns a nonzero status.
23759 Otherwise, it returns a zero status.
23760
23761 If XGetWMNormalHints returns successfully and a pre-ICCCM size
23762 hints property is read, the supplied_return argument will
23763 contain the following bits:
23764
23765(USPosition|USSize|PPosition|PSize|PMinSize|
23766 PMaxSize|PResizeInc|PAspect)
23767
23768 If the property is large enough to contain the base size and
23769 window gravity fields as well, the supplied_return argument
23770 will also contain the following bits:
23771
23772PBaseSize|PWinGravity
23773
23774 XGetWMNormalHints can generate a BadWindow error.
23775
23776 To set a window's WM_SIZE_HINTS property, use XSetWMSizeHints.
23777
23778 void XSetWMSizeHints(Display *display, Window w, XSizeHints
23779 *hints, Atom property);
23780
23781 display
23782
23783 Specifies the connection to the X server.
23784
23785 w
23786
23787 Specifies the window.
23788
23789 hints
23790
23791 Specifies the XSizeHints structure to be used.
23792
23793 property
23794
23795 Specifies the property name.
23796
23797 The XSetWMSizeHints function replaces the size hints for the
23798 specified property on the named window. If the specified
23799 property does not already exist, XSetWMSizeHints sets the size
23800 hints for the specified property on the named window. The
23801 property is stored with a type of WM_SIZE_HINTS and a format of
23802 32. To set a window's normal size hints, you can use the
23803 XSetWMNormalHints function.
23804
23805 XSetWMSizeHints can generate BadAlloc, BadAtom, and BadWindow
23806 errors.
23807
23808 To read a window's WM_SIZE_HINTS property, use XGetWMSizeHints.
23809
23810 Status XGetWMSizeHints(Display *display, Window w, XSizeHints
23811 *hints_return, long *supplied_return, Atom property);
23812
23813 display
23814
23815 Specifies the connection to the X server.
23816
23817 w
23818
23819 Specifies the window.
23820
23821 hints_return
23822
23823 Returns the XSizeHints structure.
23824
23825 supplied_return
23826
23827 Returns the hints that were supplied by the user.
23828
23829 property
23830
23831 Specifies the property name.
23832
23833 The XGetWMSizeHints function returns the size hints stored in
23834 the specified property on the named window. If the property is
23835 of type WM_SIZE_HINTS, is of format 32, and is long enough to
23836 contain either an old (pre-ICCCM) or new size hints structure,
23837 XGetWMSizeHints sets the various fields of the XSizeHints
23838 structure, sets the supplied_return argument to the list of
23839 fields that were supplied by the user (whether or not they
23840 contained defined values), and returns a nonzero status.
23841 Otherwise, it returns a zero status. To get a window's normal
23842 size hints, you can use the XGetWMNormalHints function.
23843
23844 If XGetWMSizeHints returns successfully and a pre-ICCCM size
23845 hints property is read, the supplied_return argument will
23846 contain the following bits:
23847
23848(USPosition|USSize|PPosition|PSize|PMinSize|
23849 PMaxSize|PResizeInc|PAspect)
23850
23851 If the property is large enough to contain the base size and
23852 window gravity fields as well, the supplied_return argument
23853 will also contain the following bits:
23854
23855PBaseSize|PWinGravity
23856
23857 XGetWMSizeHints can generate BadAtom and BadWindow errors.
23858
23859Setting and Reading the WM_CLASS Property
23860
23861 Xlib provides functions that you can use to set and get the
23862 WM_CLASS property for a given window. These functions use the
23863 XClassHint structure, which is defined in the <X11/Xutil.h>
23864 header file.
23865
23866 To allocate an XClassHint structure, use XAllocClassHint.
23867
23868 XClassHint *XAllocClassHint(void);
23869
23870 The XAllocClassHint function allocates and returns a pointer to
23871 an XClassHint structure. Note that the pointer fields in the
23872 XClassHint structure are initially set to NULL. If insufficient
23873 memory is available, XAllocClassHint returns NULL. To free the
23874 memory allocated to this structure, use XFree.
23875
23876 The XClassHint contains:
23877
23878
23879
23880typedef struct {
23881 char *res_name;
23882 char *res_class;
23883} XClassHint;
23884
23885 The res_name member contains the application name, and the
23886 res_class member contains the application class. Note that the
23887 name set in this property may differ from the name set as
23888 WM_NAME. That is, WM_NAME specifies what should be displayed in
23889 the title bar and, therefore, can contain temporal information
23890 (for example, the name of a file currently in an editor's
23891 buffer). On the other hand, the name specified as part of
23892 WM_CLASS is the formal name of the application that should be
23893 used when retrieving the application's resources from the
23894 resource database.
23895
23896 To set a window's WM_CLASS property, use XSetClassHint.
23897
23898 XSetClassHint(Display *display, Window w, XClassHint
23899 *class_hints);
23900
23901 display
23902
23903 Specifies the connection to the X server.
23904
23905 w
23906
23907 Specifies the window.
23908
23909 class_hints
23910
23911 Specifies the XClassHint structure that is to be used.
23912
23913 The XSetClassHint function sets the class hint for the
23914 specified window. If the strings are not in the Host Portable
23915 Character Encoding, the result is implementation-dependent.
23916
23917 XSetClassHint can generate BadAlloc and BadWindow errors.
23918
23919 To read a window's WM_CLASS property, use XGetClassHint.
23920
23921 Status XGetClassHint(Display *display, Window w, XClassHint
23922 *class_hints_return);
23923
23924 display
23925
23926 Specifies the connection to the X server.
23927
23928 w
23929
23930 Specifies the window.
23931
23932 class_hints_return
23933
23934 Returns the XClassHint structure.
23935
23936 The XGetClassHint function returns the class hint of the
23937 specified window to the members of the supplied structure. If
23938 the data returned by the server is in the Latin Portable
23939 Character Encoding, then the returned strings are in the Host
23940 Portable Character Encoding. Otherwise, the result is
23941 implementation-dependent. It returns a nonzero status on
23942 success; otherwise, it returns a zero status. To free res_name
23943 and res_class when finished with the strings, use XFree on each
23944 individually.
23945
23946 XGetClassHint can generate a BadWindow error.
23947
23948Setting and Reading the WM_TRANSIENT_FOR Property
23949
23950 Xlib provides functions that you can use to set and read the
23951 WM_TRANSIENT_FOR property for a given window.
23952
23953 To set a window's WM_TRANSIENT_FOR property, use
23954 XSetTransientForHint.
23955
23956 XSetTransientForHint(Display *display, Window w, Window
23957 prop_window);
23958
23959 display
23960
23961 Specifies the connection to the X server.
23962
23963 w
23964
23965 Specifies the window.
23966
23967 prop_window
23968
23969 Specifies the window that the WM_TRANSIENT_FOR property is to
23970 be set to.
23971
23972 The XSetTransientForHint function sets the WM_TRANSIENT_FOR
23973 property of the specified window to the specified prop_window.
23974
23975 XSetTransientForHint can generate BadAlloc and BadWindow
23976 errors.
23977
23978 To read a window's WM_TRANSIENT_FOR property, use
23979 XGetTransientForHint.
23980
23981 Status XGetTransientForHint(Display *display, Window w, Window
23982 *prop_window_return);
23983
23984 display
23985
23986 Specifies the connection to the X server.
23987
23988 w
23989
23990 Specifies the window.
23991
23992 prop_window_return
23993
23994 Returns the WM_TRANSIENT_FOR property of the specified window.
23995
23996 The XGetTransientForHint function returns the WM_TRANSIENT_FOR
23997 property for the specified window. It returns a nonzero status
23998 on success; otherwise, it returns a zero status.
23999
24000 XGetTransientForHint can generate a BadWindow error.
24001
24002Setting and Reading the WM_PROTOCOLS Property
24003
24004 Xlib provides functions that you can use to set and read the
24005 WM_PROTOCOLS property for a given window.
24006
24007 To set a window's WM_PROTOCOLS property, use XSetWMProtocols.
24008
24009 Status XSetWMProtocols(Display *display, Window w, Atom
24010 *protocols, int count);
24011
24012 display
24013
24014 Specifies the connection to the X server.
24015
24016 w
24017
24018 Specifies the window.
24019
24020 protocols
24021
24022 Specifies the list of protocols.
24023
24024 count
24025
24026 Specifies the number of protocols in the list.
24027
24028 The XSetWMProtocols function replaces the WM_PROTOCOLS property
24029 on the specified window with the list of atoms specified by the
24030 protocols argument. If the property does not already exist,
24031 XSetWMProtocols sets the WM_PROTOCOLS property on the specified
24032 window to the list of atoms specified by the protocols
24033 argument. The property is stored with a type of ATOM and a
24034 format of 32. If it cannot intern the WM_PROTOCOLS atom,
24035 XSetWMProtocols returns a zero status. Otherwise, it returns a
24036 nonzero status.
24037
24038 XSetWMProtocols can generate BadAlloc and BadWindow errors.
24039
24040 To read a window's WM_PROTOCOLS property, use XGetWMProtocols.
24041
24042 Status XGetWMProtocols(Display *display, Window w, Atom
24043 **protocols_return, int *count_return);
24044
24045 display
24046
24047 Specifies the connection to the X server.
24048
24049 w
24050
24051 Specifies the window.
24052
24053 protocols_return
24054
24055 Returns the list of protocols.
24056
24057 count_return
24058
24059 Returns the number of protocols in the list.
24060
24061 The XGetWMProtocols function returns the list of atoms stored
24062 in the WM_PROTOCOLS property on the specified window. These
24063 atoms describe window manager protocols in which the owner of
24064 this window is willing to participate. If the property exists,
24065 is of type ATOM, is of format 32, and the atom WM_PROTOCOLS can
24066 be interned, XGetWMProtocols sets the protocols_return argument
24067 to a list of atoms, sets the count_return argument to the
24068 number of elements in the list, and returns a nonzero status.
24069 Otherwise, it sets neither of the return arguments and returns
24070 a zero status. To release the list of atoms, use XFree.
24071
24072 XGetWMProtocols can generate a BadWindow error.
24073
24074Setting and Reading the WM_COLORMAP_WINDOWS Property
24075
24076 Xlib provides functions that you can use to set and read the
24077 WM_COLORMAP_WINDOWS property for a given window.
24078
24079 To set a window's WM_COLORMAP_WINDOWS property, use
24080 XSetWMColormapWindows.
24081
24082 Status XSetWMColormapWindows(Display *display, Window w, Window
24083 *colormap_windows, int count);
24084
24085 display
24086
24087 Specifies the connection to the X server.
24088
24089 w
24090
24091 Specifies the window.
24092
24093 colormap_windows
24094
24095 Specifies the list of windows.
24096
24097 count
24098
24099 Specifies the number of windows in the list.
24100
24101 The XSetWMColormapWindows function replaces the
24102 WM_COLORMAP_WINDOWS property on the specified window with the
24103 list of windows specified by the colormap_windows argument. If
24104 the property does not already exist, XSetWMColormapWindows sets
24105 the WM_COLORMAP_WINDOWS property on the specified window to the
24106 list of windows specified by the colormap_windows argument. The
24107 property is stored with a type of WINDOW and a format of 32. If
24108 it cannot intern the WM_COLORMAP_WINDOWS atom,
24109 XSetWMColormapWindows returns a zero status. Otherwise, it
24110 returns a nonzero status.
24111
24112 XSetWMColormapWindows can generate BadAlloc and BadWindow
24113 errors.
24114
24115 To read a window's WM_COLORMAP_WINDOWS property, use
24116 XGetWMColormapWindows.
24117
24118 Status XGetWMColormapWindows(Display *display, Window w, Window
24119 **colormap_windows_return, int *count_return);
24120
24121 display
24122
24123 Specifies the connection to the X server.
24124
24125 w
24126
24127 Specifies the window.
24128
24129 colormap_windows_return
24130
24131 Returns the list of windows.
24132
24133 count_return
24134
24135 Returns the number of windows in the list.
24136
24137 The XGetWMColormapWindows function returns the list of window
24138 identifiers stored in the WM_COLORMAP_WINDOWS property on the
24139 specified window. These identifiers indicate the colormaps that
24140 the window manager may need to install for this window. If the
24141 property exists, is of type WINDOW, is of format 32, and the
24142 atom WM_COLORMAP_WINDOWS can be interned, XGetWMColormapWindows
24143 sets the windows_return argument to a list of window
24144 identifiers, sets the count_return argument to the number of
24145 elements in the list, and returns a nonzero status. Otherwise,
24146 it sets neither of the return arguments and returns a zero
24147 status. To release the list of window identifiers, use XFree.
24148
24149 XGetWMColormapWindows can generate a BadWindow error.
24150
24151Setting and Reading the WM_ICON_SIZE Property
24152
24153 Xlib provides functions that you can use to set and read the
24154 WM_ICON_SIZE property for a given window. These functions use
24155 the XIconSize structure, which is defined in the <X11/Xutil.h>
24156 header file.
24157
24158 To allocate an XIconSize structure, use XAllocIconSize.
24159
24160 XIconSize *XAllocIconSize(void);
24161
24162 The XAllocIconSize function allocates and returns a pointer to
24163 an XIconSize structure. Note that all fields in the XIconSize
24164 structure are initially set to zero. If insufficient memory is
24165 available, XAllocIconSize returns NULL. To free the memory
24166 allocated to this structure, use XFree.
24167
24168 The XIconSize structure contains:
24169
24170
24171
24172typedef struct {
24173 int min_width, min_height;
24174 int max_width, max_height;
24175 int width_inc, height_inc;
24176} XIconSize;
24177
24178 The width_inc and height_inc members define an arithmetic
24179 progression of sizes (minimum to maximum) that represent the
24180 supported icon sizes.
24181
24182 To set a window's WM_ICON_SIZE property, use XSetIconSizes.
24183
24184 XSetIconSizes(Display *display, Window w, XIconSize *size_list,
24185 int count);
24186
24187 display
24188
24189 Specifies the connection to the X server.
24190
24191 w
24192
24193 Specifies the window.
24194
24195 size_list
24196
24197 Specifies the size list.
24198
24199 count
24200
24201 Specifies the number of items in the size list.
24202
24203 The XSetIconSizes function is used only by window managers to
24204 set the supported icon sizes.
24205
24206 XSetIconSizes can generate BadAlloc and BadWindow errors.
24207
24208 To read a window's WM_ICON_SIZE property, use XGetIconSizes.
24209
24210 Status XGetIconSizes(Display *display, Window w, XIconSize
24211 **size_list_return, int *count_return);
24212
24213 display
24214
24215 Specifies the connection to the X server.
24216
24217 w
24218
24219 Specifies the window.
24220
24221 size_list_return
24222
24223 Returns the size list.
24224
24225 count_return
24226
24227 Returns the number of items in the size list.
24228
24229 The XGetIconSizes function returns zero if a window manager has
24230 not set icon sizes; otherwise, it returns nonzero.
24231 XGetIconSizes should be called by an application that wants to
24232 find out what icon sizes would be most appreciated by the
24233 window manager under which the application is running. The
24234 application should then use XSetWMHints to supply the window
24235 manager with an icon pixmap or window in one of the supported
24236 sizes. To free the data allocated in size_list_return, use
24237 XFree.
24238
24239 XGetIconSizes can generate a BadWindow error.
24240
24241Using Window Manager Convenience Functions
24242
24243 The XmbSetWMProperties function stores the standard set of
24244 window manager properties, with text properties in standard
24245 encodings for internationalized text communication. The
24246 standard window manager properties for a given window are
24247 WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
24248 WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME.
24249
24250 void XmbSetWMProperties(Display *display, Window w, char
24251 *window_name, char *icon_name, char *argv[], int argc,
24252 XSizeHints *normal_hints, XWMHints *wm_hints, XClassHint
24253 *class_hints);
24254
24255 display
24256
24257 Specifies the connection to the X server.
24258
24259 w
24260
24261 Specifies the window.
24262
24263 window_name
24264
24265 Specifies the window name, which should be a null-terminated
24266 string.
24267
24268 icon_name
24269
24270 Specifies the icon name, which should be a null-terminated
24271 string.
24272
24273 argv
24274
24275 Specifies the application's argument list.
24276
24277 argc
24278
24279 Specifies the number of arguments.
24280
24281 hints
24282
24283 Specifies the size hints for the window in its normal state.
24284
24285 wm_hints
24286
24287 Specifies the XWMHints structure to be used.
24288
24289 class_hints
24290
24291 Specifies the XClassHint structure to be used.
24292
24293 The XmbSetWMProperties convenience function provides a simple
24294 programming interface for setting those essential window
24295 properties that are used for communicating with other clients
24296 (particularly window and session managers).
24297
24298 If the window_name argument is non-NULL, XmbSetWMProperties
24299 sets the WM_NAME property. If the icon_name argument is
24300 non-NULL, XmbSetWMProperties sets the WM_ICON_NAME property.
24301 The window_name and icon_name arguments are null-terminated
24302 strings in the encoding of the current locale. If the arguments
24303 can be fully converted to the STRING encoding, the properties
24304 are created with type ``STRING''; otherwise, the arguments are
24305 converted to Compound Text, and the properties are created with
24306 type ``COMPOUND_TEXT''.
24307
24308 If the normal_hints argument is non-NULL, XmbSetWMProperties
24309 calls XSetWMNormalHints, which sets the WM_NORMAL_HINTS
24310 property (see section 14.1.7). If the wm_hints argument is
24311 non-NULL, XmbSetWMProperties calls XSetWMHints, which sets the
24312 WM_HINTS property (see section 14.1.6).
24313
24314 If the argv argument is non-NULL, XmbSetWMProperties sets the
24315 WM_COMMAND property from argv and argc. An argc of zero
24316 indicates a zero-length command.
24317
24318 The hostname of the machine is stored using XSetWMClientMachine
24319 (see section 14.2.2).
24320
24321 If the class_hints argument is non-NULL, XmbSetWMProperties
24322 sets the WM_CLASS property. If the res_name member in the
24323 XClassHint structure is set to the NULL pointer and the
24324 RESOURCE_NAME environment variable is set, the value of the
24325 environment variable is substituted for res_name. If the
24326 res_name member is NULL, the environment variable is not set,
24327 and argv and argv[0] are set, then the value of argv[0],
24328 stripped of any directory prefixes, is substituted for
24329 res_name.
24330
24331 It is assumed that the supplied class_hints.res_name and argv,
24332 the RESOURCE_NAME environment variable, and the hostname of the
24333 machine are in the encoding of the locale announced for the
24334 LC_CTYPE category (on POSIX-compliant systems, the LC_CTYPE,
24335 else LANG environment variable). The corresponding WM_CLASS,
24336 WM_COMMAND, and WM_CLIENT_MACHINE properties are typed
24337 according to the local host locale announcer. No encoding
24338 conversion is performed prior to storage in the properties.
24339
24340 For clients that need to process the property text in a locale,
24341 XmbSetWMProperties sets the WM_LOCALE_NAME property to be the
24342 name of the current locale. The name is assumed to be in the
24343 Host Portable Character Encoding and is converted to STRING for
24344 storage in the property.
24345
24346 XmbSetWMProperties can generate BadAlloc and BadWindow errors.
24347
24348 To set a window's standard window manager properties with
24349 strings in client-specified encodings, use XSetWMProperties.
24350 The standard window manager properties for a given window are
24351 WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
24352 WM_COMMAND, and WM_CLIENT_MACHINE.
24353
24354 void XSetWMProperties(Display *display, Window w, XTextProperty
24355 *window_name, XTextProperty *icon_name, char **argv, int argc,
24356 XSizeHints *normal_hints, XWMHints *wm_hints, XClassHint
24357 *class_hints);
24358
24359 display
24360
24361 Specifies the connection to the X server.
24362
24363 w
24364
24365 Specifies the window.
24366
24367 window_name
24368
24369 Specifies the window name, which should be a null-terminated
24370 string.
24371
24372 icon_name
24373
24374 Specifies the icon name, which should be a null-terminated
24375 string.
24376
24377 argv
24378
24379 Specifies the application's argument list.
24380
24381 argc
24382
24383 Specifies the number of arguments.
24384
24385 normal_hints
24386
24387 Specifies the size hints for the window in its normal state.
24388
24389 wm_hints
24390
24391 Specifies the XWMHints structure to be used.
24392
24393 class_hints
24394
24395 Specifies the XClassHint structure to be used.
24396
24397 The XSetWMProperties convenience function provides a single
24398 programming interface for setting those essential window
24399 properties that are used for communicating with other clients
24400 (particularly window and session managers).
24401
24402 If the window_name argument is non-NULL, XSetWMProperties calls
24403 XSetWMName, which, in turn, sets the WM_NAME property (see
24404 section 14.1.4). If the icon_name argument is non-NULL,
24405 XSetWMProperties calls XSetWMIconName, which sets the
24406 WM_ICON_NAME property (see section 14.1.5). If the argv
24407 argument is non-NULL, XSetWMProperties calls XSetCommand, which
24408 sets the WM_COMMAND property (see section 14.2.1). Note that an
24409 argc of zero is allowed to indicate a zero-length command. Note
24410 also that the hostname of this machine is stored using
24411 XSetWMClientMachine (see section 14.2.2).
24412
24413 If the normal_hints argument is non-NULL, XSetWMProperties
24414 calls XSetWMNormalHints, which sets the WM_NORMAL_HINTS
24415 property (see section 14.1.7). If the wm_hints argument is
24416 non-NULL, XSetWMProperties calls XSetWMHints, which sets the
24417 WM_HINTS property (see section 14.1.6).
24418
24419 If the class_hints argument is non-NULL, XSetWMProperties calls
24420 XSetClassHint, which sets the WM_CLASS property (see section
24421 14.1.8). If the res_name member in the XClassHint structure is
24422 set to the NULL pointer and the RESOURCE_NAME environment
24423 variable is set, then the value of the environment variable is
24424 substituted for res_name. If the res_name member is NULL, the
24425 environment variable is not set, and argv and argv[0] are set,
24426 then the value of argv[0], stripped of any directory prefixes,
24427 is substituted for res_name.
24428
24429 XSetWMProperties can generate BadAlloc and BadWindow errors.
24430
24431Client to Session Manager Communication
24432
24433 This section discusses how to:
24434 * Set and read the WM_COMMAND property
24435 * Set and read the WM_CLIENT_MACHINE property
24436
24437Setting and Reading the WM_COMMAND Property
24438
24439 Xlib provides functions that you can use to set and read the
24440 WM_COMMAND property for a given window.
24441
24442 To set a window's WM_COMMAND property, use XSetCommand.
24443
24444 XSetCommand(Display *display, Window w, char **argv, int argc);
24445
24446 display
24447
24448 Specifies the connection to the X server.
24449
24450 w
24451
24452 Specifies the window.
24453
24454 argv
24455
24456 Specifies the application's argument list.
24457
24458 argc
24459
24460 Specifies the number of arguments.
24461
24462 The XSetCommand function sets the command and arguments used to
24463 invoke the application. (Typically, argv is the argv array of
24464 your main program.) If the strings are not in the Host Portable
24465 Character Encoding, the result is implementation-dependent.
24466
24467 XSetCommand can generate BadAlloc and BadWindow errors.
24468
24469 To read a window's WM_COMMAND property, use XGetCommand.
24470
24471 Status XGetCommand(Display *display, Window w, char
24472 ***argv_return, int *argc_return);
24473
24474 display
24475
24476 Specifies the connection to the X server.
24477
24478 w
24479
24480 Specifies the window.
24481
24482 argv_return
24483
24484 Returns the application's argument list.
24485
24486 argc_return
24487
24488 Returns the number of arguments returned.
24489
24490 The XGetCommand function reads the WM_COMMAND property from the
24491 specified window and returns a string list. If the WM_COMMAND
24492 property exists, it is of type STRING and format 8. If
24493 sufficient memory can be allocated to contain the string list,
24494 XGetCommand fills in the argv_return and argc_return arguments
24495 and returns a nonzero status. Otherwise, it returns a zero
24496 status. If the data returned by the server is in the Latin
24497 Portable Character Encoding, then the returned strings are in
24498 the Host Portable Character Encoding. Otherwise, the result is
24499 implementation-dependent. To free the memory allocated to the
24500 string list, use XFreeStringList.
24501
24502Setting and Reading the WM_CLIENT_MACHINE Property
24503
24504 Xlib provides functions that you can use to set and read the
24505 WM_CLIENT_MACHINE property for a given window.
24506
24507 To set a window's WM_CLIENT_MACHINE property, use
24508 XSetWMClientMachine.
24509
24510 void XSetWMClientMachine(Display *display, Window w,
24511 XTextProperty *text_prop);
24512
24513 display
24514
24515 Specifies the connection to the X server.
24516
24517 w
24518
24519 Specifies the window.
24520
24521 text_prop
24522
24523 Specifies the XTextProperty structure to be used.
24524
24525 The XSetWMClientMachine convenience function calls
24526 XSetTextProperty to set the WM_CLIENT_MACHINE property.
24527
24528 To read a window's WM_CLIENT_MACHINE property, use
24529 XGetWMClientMachine.
24530
24531 Status XGetWMClientMachine(Display *display, Window w,
24532 XTextProperty *text_prop_return);
24533
24534 display
24535
24536 Specifies the connection to the X server.
24537
24538 w
24539
24540 Specifies the window.
24541
24542 text_prop_return
24543
24544 Returns the XTextProperty structure.
24545
24546 The XGetWMClientMachine convenience function performs an
24547 XGetTextProperty on the WM_CLIENT_MACHINE property. It returns
24548 a nonzero status on success; otherwise, it returns a zero
24549 status.
24550
24551Standard Colormaps
24552
24553 Applications with color palettes, smooth-shaded drawings, or
24554 digitized images demand large numbers of colors. In addition,
24555 these applications often require an efficient mapping from
24556 color triples to pixel values that display the appropriate
24557 colors.
24558
24559 As an example, consider a three-dimensional display program
24560 that wants to draw a smoothly shaded sphere. At each pixel in
24561 the image of the sphere, the program computes the intensity and
24562 color of light reflected back to the viewer. The result of each
24563 computation is a triple of red, green, and blue (RGB)
24564 coefficients in the range 0.0 to 1.0. To draw the sphere, the
24565 program needs a colormap that provides a large range of
24566 uniformly distributed colors. The colormap should be arranged
24567 so that the program can convert its RGB triples into pixel
24568 values very quickly, because drawing the entire sphere requires
24569 many such conversions.
24570
24571 On many current workstations, the display is limited to 256 or
24572 fewer colors. Applications must allocate colors carefully, not
24573 only to make sure they cover the entire range they need but
24574 also to make use of as many of the available colors as
24575 possible. On a typical X display, many applications are active
24576 at once. Most workstations have only one hardware look-up table
24577 for colors, so only one application colormap can be installed
24578 at a given time. The application using the installed colormap
24579 is displayed correctly, and the other applications go
24580 technicolor and are displayed with false colors.
24581
24582 As another example, consider a user who is running an image
24583 processing program to display earth-resources data. The image
24584 processing program needs a colormap set up with 8 reds, 8
24585 greens, and 4 blues, for a total of 256 colors. Because some
24586 colors are already in use in the default colormap, the image
24587 processing program allocates and installs a new colormap.
24588
24589 The user decides to alter some of the colors in the image by
24590 invoking a color palette program to mix and choose colors. The
24591 color palette program also needs a colormap with eight reds,
24592 eight greens, and four blues, so just like the image processing
24593 program, it must allocate and install a new colormap.
24594
24595 Because only one colormap can be installed at a time, the color
24596 palette may be displayed incorrectly whenever the image
24597 processing program is active. Conversely, whenever the palette
24598 program is active, the image may be displayed incorrectly. The
24599 user can never match or compare colors in the palette and
24600 image. Contention for colormap resources can be reduced if
24601 applications with similar color needs share colormaps.
24602
24603 The image processing program and the color palette program
24604 could share the same colormap if there existed a convention
24605 that described how the colormap was set up. Whenever either
24606 program was active, both would be displayed correctly.
24607
24608 The standard colormap properties define a set of commonly used
24609 colormaps. Applications that share these colormaps and
24610 conventions display true colors more often and provide a better
24611 interface to the user.
24612
24613 Standard colormaps allow applications to share commonly used
24614 color resources. This allows many applications to be displayed
24615 in true colors simultaneously, even when each application needs
24616 an entirely filled colormap.
24617
24618 Several standard colormaps are described in this section.
24619 Usually, a window manager creates these colormaps. Applications
24620 should use the standard colormaps if they already exist.
24621
24622 To allocate an XStandardColormap structure, use
24623 XAllocStandardColormap.
24624
24625 XStandardColormap *XAllocStandardColormap(void);
24626
24627 The XAllocStandardColormap function allocates and returns a
24628 pointer to an XStandardColormap structure. Note that all fields
24629 in the XStandardColormap structure are initially set to zero.
24630 If insufficient memory is available, XAllocStandardColormap
24631 returns NULL. To free the memory allocated to this structure,
24632 use XFree.
24633
24634 The XStandardColormap structure contains:
24635/* Hints */
24636
24637#define ReeaseByFreeingColormap ((XID)1L)
24638
24639/* Values */
24640
24641typedef struct {
24642 Colormap colormap;
24643 unsigned long red_max;
24644 unsigned long red_mult;
24645 unsigned long green_max;
24646 unsigned long green_mult;
24647 unsigned long blue_max;
24648 unsigned long blue_mult;
24649 unsigned long base_pixel;
24650 VisualID visualid;
24651 XID killid;
24652} XStandardColormap;
24653
24654 The colormap member is the colormap created by the
24655 XCreateColormap function. The red_max, green_max, and blue_max
24656 members give the maximum red, green, and blue values,
24657 respectively. Each color coefficient ranges from zero to its
24658 max, inclusive. For example, a common colormap allocation is
24659 3/3/2 (3 planes for red, 3 planes for green, and 2 planes for
24660 blue). This colormap would have red_max = 7, green_max = 7, and
24661 blue_max = 3. An alternate allocation that uses only 216 colors
24662 is red_max = 5, green_max = 5, and blue_max = 5.
24663
24664 The red_mult, green_mult, and blue_mult members give the scale
24665 factors used to compose a full pixel value. (See the discussion
24666 of the base_pixel members for further information.) For a 3/3/2
24667 allocation, red_mult might be 32, green_mult might be 4, and
24668 blue_mult might be 1. For a 6-colors-each allocation, red_mult
24669 might be 36, green_mult might be 6, and blue_mult might be 1.
24670
24671 The base_pixel member gives the base pixel value used to
24672 compose a full pixel value. Usually, the base_pixel is obtained
24673 from a call to the XAllocColorPlanes function. Given integer
24674 red, green, and blue coefficients in their appropriate ranges,
24675 one then can compute a corresponding pixel value by using the
24676 following expression:
24677
24678
24679
24680(r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFF
24681F
24682
24683 For GrayScale colormaps, only the colormap, red_max, red_mult,
24684 and base_pixel members are defined. The other members are
24685 ignored. To compute a GrayScale pixel value, use the following
24686 expression:
24687
24688
24689
24690(gray * red_mult + base_pixel) & 0xFFFFFFFF
24691
24692 Negative multipliers can be represented by converting the 2's
24693 complement representation of the multiplier into an unsigned
24694 long and storing the result in the appropriate _mult field. The
24695 step of masking by 0xFFFFFFFF effectively converts the
24696 resulting positive multiplier into a negative one. The masking
24697 step will take place automatically on many machine
24698 architectures, depending on the size of the integer type used
24699 to do the computation.
24700
24701 The visualid member gives the ID number of the visual from
24702 which the colormap was created. The killid member gives a
24703 resource ID that indicates whether the cells held by this
24704 standard colormap are to be released by freeing the colormap ID
24705 or by calling the XKillClient function on the indicated
24706 resource. (Note that this method is necessary for allocating
24707 out of an existing colormap.)
24708
24709 The properties containing the XStandardColormap information
24710 have the type RGB_COLOR_MAP.
24711
24712 The remainder of this section discusses standard colormap
24713 properties and atoms as well as how to manipulate standard
24714 colormaps.
24715
24716Standard Colormap Properties and Atoms
24717
24718 Several standard colormaps are available. Each standard
24719 colormap is defined by a property, and each such property is
24720 identified by an atom. The following list names the atoms and
24721 describes the colormap associated with each one. The
24722 <X11/Xatom.h> header file contains the definitions for each of
24723 the following atoms, which are prefixed with XA_.
24724
24725 RGB_DEFAULT_MAP
24726
24727 This atom names a property. The value of the property is an
24728 array of XStandardColormap structures. Each entry in the array
24729 describes an RGB subset of the default color map for the Visual
24730 specified by visual_id.
24731
24732 Some applications only need a few RGB colors and may be able to
24733 allocate them from the system default colormap. This is the
24734 ideal situation because the fewer colormaps that are active in
24735 the system the more applications are displayed with correct
24736 colors at all times.
24737
24738 A typical allocation for the RGB_DEFAULT_MAP on 8-plane
24739 displays is 6 reds, 6 greens, and 6 blues. This gives 216
24740 uniformly distributed colors (6 intensities of 36 different
24741 hues) and still leaves 40 elements of a 256-element colormap
24742 available for special-purpose colors for text, borders, and so
24743 on.
24744
24745 RGB_BEST_MAP
24746
24747 This atom names a property. The value of the property is an
24748 XStandardColormap.
24749
24750 The property defines the best RGB colormap available on the
24751 screen. (Of course, this is a subjective evaluation.) Many
24752 image processing and three-dimensional applications need to use
24753 all available colormap cells and to distribute as many
24754 perceptually distinct colors as possible over those cells. This
24755 implies that there may be more green values available than red,
24756 as well as more green or red than blue.
24757
24758 For an 8-plane PseudoColor visual, RGB_BEST_MAP is likely to be
24759 a 3/3/2 allocation. For a 24-plane DirectColor visual,
24760 RGB_BEST_MAP is normally an 8/8/8 allocation.
24761
24762 RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP
24763
24764 These atoms name properties. The value of each property is an
24765 XStandardColormap.
24766
24767 The properties define all-red, all-green, and all-blue
24768 colormaps, respectively. These maps are used by applications
24769 that want to make color-separated images. For example, a user
24770 might generate a full-color image on an 8-plane display both by
24771 rendering an image three times (once with high color resolution
24772 in red, once with green, and once with blue) and by multiply
24773 exposing a single frame in a camera.
24774
24775 RGB_GRAY_MAP
24776
24777 This atom names a property. The value of the property is an
24778 XStandardColormap.
24779
24780 The property describes the best GrayScale colormap available on
24781 the screen. As previously mentioned, only the colormap,
24782 red_max, red_mult, and base_pixel members of the
24783 XStandardColormap structure are used for GrayScale colormaps.
24784
24785Setting and Obtaining Standard Colormaps
24786
24787 Xlib provides functions that you can use to set and obtain an
24788 XStandardColormap structure.
24789
24790 To set an XStandardColormap structure, use XSetRGBColormaps.
24791
24792 void XSetRGBColormaps(Display *display, Window w,
24793 XStandardColormap *std_colormap, int count, Atom property);
24794
24795 display
24796
24797 Specifies the connection to the X server.
24798
24799 w
24800
24801 Specifies the window.
24802
24803 std_colormap
24804
24805 Specifies the XStandardColormap structure to be used.
24806
24807 count
24808
24809 Specifies the number of colormaps.
24810
24811 property
24812
24813 Specifies the property name.
24814
24815 The XSetRGBColormaps function replaces the RGB colormap
24816 definition in the specified property on the named window. If
24817 the property does not already exist, XSetRGBColormaps sets the
24818 RGB colormap definition in the specified property on the named
24819 window. The property is stored with a type of RGB_COLOR_MAP and
24820 a format of 32. Note that it is the caller's responsibility to
24821 honor the ICCCM restriction that only RGB_DEFAULT_MAP contain
24822 more than one definition.
24823
24824 The XSetRGBColormaps function usually is only used by window or
24825 session managers. To create a standard colormap, follow this
24826 procedure:
24827 * Open a new connection to the same server.
24828 * Grab the server.
24829 * See if the property is on the property list of the root
24830 window for the screen.
24831 * If the desired property is not present:
24832 * Create a colormap (unless you are using the default
24833 colormap of the screen).
24834 * Determine the color characteristics of the visual.
24835 * Allocate cells in the colormap (or create it with
24836 AllocAll).
24837 * Call XStoreColors to store appropriate color values in the
24838 colormap.
24839 * Fill in the descriptive members in the XStandardColormap
24840 structure.
24841 * Attach the property to the root window.
24842 * Use XSetCloseDownMode to make the resource permanent.
24843 * Ungrab the server.
24844
24845 XSetRGBColormaps can generate BadAlloc, BadAtom, and BadWindow
24846 errors.
24847
24848 To obtain the XStandardColormap structure associated with the
24849 specified property, use XGetRGBColormaps.
24850
24851 Status XGetRGBColormaps(Display *display, Window w,
24852 XStandardColormap **std_colormap_return, int *count_return,
24853 Atom property);
24854
24855 display
24856
24857 Specifies the connection to the X server.
24858
24859 w
24860
24861 Specifies the window.
24862
24863 std_colormap_return
24864
24865 Returns the XStandardColormap structure.
24866
24867 count_return
24868
24869 Returns the number of colormaps.
24870
24871 property
24872
24873 Specifies the property name.
24874
24875 The XGetRGBColormaps function returns the RGB colormap
24876 definitions stored in the specified property on the named
24877 window. If the property exists, is of type RGB_COLOR_MAP, is of
24878 format 32, and is long enough to contain a colormap definition,
24879 XGetRGBColormaps allocates and fills in space for the returned
24880 colormaps and returns a nonzero status. If the visualid is not
24881 present, XGetRGBColormaps assumes the default visual for the
24882 screen on which the window is located; if the killid is not
24883 present, None is assumed, which indicates that the resources
24884 cannot be released. Otherwise, none of the fields are set, and
24885 XGetRGBColormaps returns a zero status. Note that it is the
24886 caller's responsibility to honor the ICCCM restriction that
24887 only RGB_DEFAULT_MAP contain more than one definition.
24888
24889 XGetRGBColormaps can generate BadAtom and BadWindow errors.
24890
24891Chapter 15. Resource Manager Functions
24892
24893 Table of Contents
24894
24895 Resource File Syntax
24896 Resource Manager Matching Rules
24897 Quarks
24898 Creating and Storing Databases
24899 Merging Resource Databases
24900 Looking Up Resources
24901 Storing into a Resource Database
24902 Enumerating Database Entries
24903 Parsing Command Line Options
24904
24905 A program often needs a variety of options in the X environment
24906 (for example, fonts, colors, icons, and cursors). Specifying
24907 all of these options on the command line is awkward because
24908 users may want to customize many aspects of the program and
24909 need a convenient way to establish these customizations as the
24910 default settings. The resource manager is provided for this
24911 purpose. Resource specifications are usually stored in
24912 human-readable files and in server properties.
24913
24914 The resource manager is a database manager with a twist. In
24915 most database systems, you perform a query using an imprecise
24916 specification, and you get back a set of records. The resource
24917 manager, however, allows you to specify a large set of values
24918 with an imprecise specification, to query the database with a
24919 precise specification, and to get back only a single value.
24920 This should be used by applications that need to know what the
24921 user prefers for colors, fonts, and other resources. It is this
24922 use as a database for dealing with X resources that inspired
24923 the name "Resource Manager," although the resource manager can
24924 be and is used in other ways.
24925
24926 For example, a user of your application may want to specify
24927 that all windows should have a blue background but that all
24928 mail-reading windows should have a red background. With
24929 well-engineered and coordinated applications, a user can define
24930 this information using only two lines of specifications.
24931
24932 As an example of how the resource manager works, consider a
24933 mail-reading application called xmh. Assume that it is designed
24934 so that it uses a complex window hierarchy all the way down to
24935 individual command buttons, which may be actual small
24936 subwindows in some toolkits. These are often called objects or
24937 widgets. In such toolkit systems, each user interface object
24938 can be composed of other objects and can be assigned a name and
24939 a class. Fully qualified names or classes can have arbitrary
24940 numbers of component names, but a fully qualified name always
24941 has the same number of component names as a fully qualified
24942 class. This generally reflects the structure of the application
24943 as composed of these objects, starting with the application
24944 itself.
24945
24946 For example, the xmh mail program has a name "xmh" and is one
24947 of a class of "Mail" programs. By convention, the first
24948 character of class components is capitalized, and the first
24949 letter of name components is in lowercase. Each name and class
24950 finally has an attribute (for example, "foreground" or "font").
24951 If each window is properly assigned a name and class, it is
24952 easy for the user to specify attributes of any portion of the
24953 application.
24954
24955 At the top level, the application might consist of a paned
24956 window (that is, a window divided into several sections) named
24957 "toc". One pane of the paned window is a button box window
24958 named "buttons" and is filled with command buttons. One of
24959 these command buttons is used to incorporate new mail and has
24960 the name "incorporate". This window has a fully qualified name,
24961 "xmh.toc.buttons.incorporate", and a fully qualified class,
24962 "Xmh.Paned.Box.Command". Its fully qualified name is the name
24963 of its parent, "xmh.toc.buttons", followed by its name,
24964 "incorporate". Its class is the class of its parent,
24965 "Xmh.Paned.Box", followed by its particular class, "Command".
24966 The fully qualified name of a resource is the attribute's name
24967 appended to the object's fully qualified name, and the fully
24968 qualified class is its class appended to the object's class.
24969
24970 The incorporate button might need the following resources:
24971 Title string, Font, Foreground color for its inactive state,
24972 Background color for its inactive state, Foreground color for
24973 its active state, and Background color for its active state.
24974 Each resource is considered to be an attribute of the button
24975 and, as such, has a name and a class. For example, the
24976 foreground color for the button in its active state might be
24977 named "activeForeground", and its class might be "Foreground".
24978
24979 When an application looks up a resource (for example, a color),
24980 it passes the complete name and complete class of the resource
24981 to a look-up routine. The resource manager compares this
24982 complete specification against the incomplete specifications of
24983 entries in the resource database, finds the best match, and
24984 returns the corresponding value for that entry.
24985
24986 The definitions for the resource manager are contained in
24987 <X11/Xresource.h>.
24988
24989Resource File Syntax
24990
24991 The syntax of a resource file is a sequence of resource lines
24992 terminated by newline characters or the end of the file. The
24993 syntax of an individual resource line is:
24994
24995
24996
24997ResourceLine = Comment | IncludeFile | ResourceSpec | <empty lin
24998e>
24999Comment = "!" {<any character except null or newline>}
25000IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName White
25001Space
25002FileName = <valid filename for operating system>
25003ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace
25004 Value
25005ResourceName = [Binding] {Component Binding} ComponentName
25006Binding = "." | "*"
25007WhiteSpace = {<space> | <horizontal tab>}
25008Component = "?" | ComponentName
25009ComponentName = NameChar {NameChar}
25010NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
25011Value = {<any character except null or unescaped newline>}
25012
25013 Elements separated by vertical bar (|) are alternatives. Curly
25014 braces ({......}) indicate zero or more repetitions of the
25015 enclosed elements. Square brackets ([......]) indicate that the
25016 enclosed element is optional. Quotes ("......") are used around
25017 literal characters.
25018
25019 IncludeFile lines are interpreted by replacing the line with
25020 the contents of the specified file. The word "include" must be
25021 in lowercase. The file name is interpreted relative to the
25022 directory of the file in which the line occurs (for example, if
25023 the file name contains no directory or contains a relative
25024 directory specification).
25025
25026 If a ResourceName contains a contiguous sequence of two or more
25027 Binding characters, the sequence will be replaced with a single
25028 ".." character if the sequence contains only ".." characters;
25029 otherwise, the sequence will be replaced with a single "*"
25030 character.
25031
25032 A resource database never contains more than one entry for a
25033 given ResourceName. If a resource file contains multiple lines
25034 with the same ResourceName, the last line in the file is used.
25035
25036 Any white space characters before or after the name or colon in
25037 a ResourceSpec are ignored. To allow a Value to begin with
25038 white space, the two-character sequence "\\space" (backslash
25039 followed by space) is recognized and replaced by a space
25040 character, and the two-character sequence "\\tab" (backslash
25041 followed by horizontal tab) is recognized and replaced by a
25042 horizontal tab character. To allow a Value to contain embedded
25043 newline characters, the two-character sequence "\\n" is
25044 recognized and replaced by a newline character. To allow a
25045 Value to be broken across multiple lines in a text file, the
25046 two-character sequence "\\newline" (backslash followed by
25047 newline) is recognized and removed from the value. To allow a
25048 Value to contain arbitrary character codes, the four-character
25049 sequence "\\nnn", where each n is a digit character in the
25050 range of "0"-"7", is recognized and replaced with a single byte
25051 that contains the octal value specified by the sequence.
25052 Finally, the two-character sequence "\newline" is recognized
25053 and replaced with a single backslash.
25054
25055 As an example of these sequences, the following resource line
25056 contains a value consisting of four characters: a backslash, a
25057 null, a "z", and a newline:
25058magic.values: \\000\
25059z\n
25060
25061Resource Manager Matching Rules
25062
25063 The algorithm for determining which resource database entry
25064 matches a given query is the heart of the resource manager. All
25065 queries must fully specify the name and class of the desired
25066 resource (use of the characters "*" and "?" is not permitted).
25067 The library supports up to 100 components in a full name or
25068 class. Resources are stored in the database with only partially
25069 specified names and classes, using pattern matching constructs.
25070 An asterisk (*) is a loose binding and is used to represent any
25071 number of intervening components, including none. A period (.)
25072 is a tight binding and is used to separate immediately adjacent
25073 components. A question mark (?) is used to match any single
25074 component name or class. A database entry cannot end in a loose
25075 binding; the final component (which cannot be the character
25076 "?") must be specified. The lookup algorithm searches the
25077 database for the entry that most closely matches (is most
25078 specific for) the full name and class being queried. When more
25079 than one database entry matches the full name and class,
25080 precedence rules are used to select just one.
25081
25082 The full name and class are scanned from left to right (from
25083 highest level in the hierarchy to lowest), one component at a
25084 time. At each level, the corresponding component and/or binding
25085 of each matching entry is determined, and these matching
25086 components and bindings are compared according to precedence
25087 rules. Each of the rules is applied at each level before moving
25088 to the next level, until a rule selects a single entry over all
25089 others. The rules, in order of precedence, are:
25090 * An entry that contains a matching component (whether name,
25091 class, or the character "?") takes precedence over entries
25092 that elide the level (that is, entries that match the level
25093 in a loose binding).
25094 * An entry with a matching name takes precedence over both
25095 entries with a matching class and entries that match using
25096 the character "?". An entry with a matching class takes
25097 precedence over entries that match using the character "?".
25098 * An entry preceded by a tight binding takes precedence over
25099 entries preceded by a loose binding.
25100
25101 To illustrate these rules, consider the following resource
25102 database entries:
25103
25104
25105xmh*Paned*activeForeground: red (entry A)
25106*incorporate.Foreground: blue (entry B)
25107xmh.toc*Command*activeForeground: green (entry C)
25108xmh.toc*?.Foreground: white (entry D)
25109xmh.toc*Command.activeForeground: black (entry E)
25110
25111 Consider a query for the resource:
25112
25113
25114
25115xmh.toc.messagefunctions.incorporate.activeForeground (name)
25116Xmh.Paned.Box.Command.Foreground (class)
25117
25118 At the first level (xmh, Xmh), rule 1 eliminates entry B. At
25119 the second level (toc, Paned), rule 2 eliminates entry A. At
25120 the third level (messagefunctions, Box), no entries are
25121 eliminated. At the fourth level (incorporate, Command), rule 2
25122 eliminates entry D. At the fifth level (activeForeground,
25123 Foreground), rule 3 eliminates entry C.
25124
25125Quarks
25126
25127 Most uses of the resource manager involve defining names,
25128 classes, and representation types as string constants. However,
25129 always referring to strings in the resource manager can be
25130 slow, because it is so heavily used in some toolkits. To solve
25131 this problem, a shorthand for a string is used in place of the
25132 string in many of the resource manager functions. Simple
25133 comparisons can be performed rather than string comparisons.
25134 The shorthand name for a string is called a quark and is the
25135 type XrmQuark. On some occasions, you may want to allocate a
25136 quark that has no string equivalent.
25137
25138 A quark is to a string what an atom is to a string in the
25139 server, but its use is entirely local to your application.
25140
25141 To allocate a new quark, use XrmUniqueQuark.
25142
25143 XrmQuark XrmUniqueQuark(void);
25144
25145 The XrmUniqueQuark function allocates a quark that is
25146 guaranteed not to represent any string that is known to the
25147 resource manager.
25148
25149 Each name, class, and representation type is typedef'd as an
25150 XrmQuark.
25151
25152typedef int XrmQuark, *XrmQuarkList;
25153typedef XrmQuark XrmName;
25154typedef XrmQuark XrmClass;
25155typedef XrmQuark XrmRepresentation;
25156#define NULLQUARK ((XrmQuark) 0)
25157
25158 Lists are represented as null-terminated arrays of quarks. The
25159 size of the array must be large enough for the number of
25160 components used.
25161
25162typedef XrmQuarkList XrmNameList;
25163typedef XrmQuarkList XrmClassList;
25164
25165 To convert a string to a quark, use XrmStringToQuark or
25166 XrmPermStringToQuark.
25167#define XrmStringToName(string) XrmStringToQuark(string)
25168#define XrmStringToClass(string) XrmStringToQuark(string)
25169#define XrmStringToRepresentation(string) XrmStringToQuark(string)
25170
25171 XrmQuark XrmStringToQuark(char *string);
25172
25173 string
25174
25175 Specifies the string for which a quark(Ql is to be allocated.
25176
25177 These functions can be used to convert from string to quark
25178 representation. If the string is not in the Host Portable
25179 Character Encoding, the conversion is implementation-dependent.
25180 The string argument to XrmStringToQuark need not be permanently
25181 allocated storage. XrmPermStringToQuark is just like
25182 XrmStringToQuark, except that Xlib is permitted to assume the
25183 string argument is permanently allocated, and, hence, that it
25184 can be used as the value to be returned by XrmQuarkToString.
25185
25186 For any given quark, if XrmStringToQuark returns a non-NULL
25187 value, all future calls will return the same value (identical
25188 address).
25189
25190 To convert a quark to a string, use XrmQuarkToString.
25191#define XrmNameToString(name) XrmQuarkToString(name)
25192#define XrmClassToString(class) XrmQuarkToString(name)
25193#define XrmRepresentationToString(type) XrmQuarkToString(type)
25194
25195 char *XrmQuarkToString(XrmQuark quark);
25196
25197 quark
25198
25199 Specifies the quark for which the equivalent string is desired.
25200
25201 These functions can be used to convert from quark
25202 representation to string. The string pointed to by the return
25203 value must not be modified or freed. The returned string is
25204 byte-for-byte equal to the original string passed to one of the
25205 string-to-quark routines. If no string exists for that quark,
25206 XrmQuarkToString returns NULL. For any given quark, if
25207 XrmQuarkToString returns a non-NULL value, all future calls
25208 will return the same value (identical address).
25209
25210 To convert a string with one or more components to a quark
25211 list, use XrmStringToQuarkList.
25212#define XrmStringToNameList(str,name) XrmStringToQuarkList((str), (name
25213))
25214#define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (cl
25215ass))
25216
25217 void XrmStringToQuarkList(char *string, XrmQuarkList
25218 quarks_return);
25219
25220 string
25221
25222 Specifies the string for which a quark list is to be allocated.
25223
25224 quarks_return
25225
25226 Returns the list of quarks. The caller must allocate sufficient
25227 space for the quarks list before calling XrmStringToQuarkList.
25228
25229 The XrmStringToQuarkList function converts the null-terminated
25230 string (generally a fully qualified name) to a list of quarks.
25231 Note that the string must be in the valid ResourceName format
25232 (see section 15.1). If the string is not in the Host Portable
25233 Character Encoding, the conversion is implementation-dependent.
25234
25235 A binding list is a list of type XrmBindingList and indicates
25236 if components of name or class lists are bound tightly or
25237 loosely (that is, if wildcarding of intermediate components is
25238 specified).
25239
25240typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingLis
25241t;
25242
25243 XrmBindTightly indicates that a period separates the
25244 components, and XrmBindLoosely indicates that an asterisk
25245 separates the components.
25246
25247 To convert a string with one or more components to a binding
25248 list and a quark list, use XrmStringToBindingQuarkList.
25249
25250 XrmStringToBindingQuarkList(char *string, XrmBindingList
25251 bindings_return, XrmQuarkList quarks_return);
25252
25253 string
25254
25255 Specifies the string for which a quark list is to be allocated.
25256
25257 bindings_return
25258
25259 Returns the binding list. The caller must allocate sufficient
25260 space for the binding list before calling
25261 XrmStringToBindingQuarkList.
25262
25263 quarks_return
25264
25265 Returns the list of quarks. The caller must allocate sufficient
25266 space for the quarks list before calling
25267 XrmStringToBindingQuarkList.
25268
25269 Component names in the list are separated by a period or an
25270 asterisk character. The string must be in the format of a valid
25271 ResourceName (see section 15.1). If the string does not start
25272 with a period or an asterisk, a tight binding is assumed. For
25273 example, the string ``*a.b*c'' becomes:
25274
25275
25276
25277quarks: a b c
25278bindings: loose tight loose
25279
25280Creating and Storing Databases
25281
25282 A resource database is an opaque type, XrmDatabase. Each
25283 database value is stored in an XrmValue structure. This
25284 structure consists of a size, an address, and a representation
25285 type. The size is specified in bytes. The representation type
25286 is a way for you to store data tagged by some
25287 application-defined type (for example, the strings ``font'' or
25288 ``color''). It has nothing to do with the C data type or with
25289 its class. The XrmValue structure is defined as:
25290
25291
25292
25293typedef struct {
25294 unsigned int size;
25295 XPointer addr;
25296} XrmValue, *XrmValuePtr;
25297
25298 To initialize the resource manager, use XrmInitialize.
25299
25300 void XrmInitialize(void XrmInitialize(\|));
25301
25302 To retrieve a database from disk, use XrmGetFileDatabase.
25303
25304 XrmDatabase XrmGetFileDatabase(char *filename);
25305
25306 filename
25307
25308 Specifies the resource database file name.
25309
25310 The XrmGetFileDatabase function opens the specified file,
25311 creates a new resource database, and loads it with the
25312 specifications read in from the specified file. The specified
25313 file should contain a sequence of entries in valid ResourceLine
25314 format (see section 15.1); the database that results from
25315 reading a file with incorrect syntax is
25316 implementation-dependent. The file is parsed in the current
25317 locale, and the database is created in the current locale. If
25318 it cannot open the specified file, XrmGetFileDatabase returns
25319 NULL.
25320
25321 To store a copy of a database to disk, use XrmPutFileDatabase.
25322
25323 void XrmPutFileDatabase(XrmDatabase database, char *stored_db);
25324
25325 database
25326
25327 Specifies the database that is to be used.
25328
25329 stored_db
25330
25331 Specifies the file name for the stored database.
25332
25333 The XrmPutFileDatabase function stores a copy of the specified
25334 database in the specified file. Text is written to the file as
25335 a sequence of entries in valid ResourceLine format (see section
25336 15.1). The file is written in the locale of the database.
25337 Entries containing resource names that are not in the Host
25338 Portable Character Encoding or containing values that are not
25339 in the encoding of the database locale, are written in an
25340 implementation-dependent manner. The order in which entries are
25341 written is implementation-dependent. Entries with
25342 representation types other than ``String'' are ignored.
25343
25344 To obtain a pointer to the screen-independent resources of a
25345 display, use XResourceManagerString.
25346
25347 char *XResourceManagerString(Display *display);
25348
25349 display
25350
25351 Specifies the connection to the X server.
25352
25353 The XResourceManagerString function returns the
25354 RESOURCE_MANAGER property from the server's root window of
25355 screen zero, which was returned when the connection was opened
25356 using XOpenDisplay. The property is converted from type STRING
25357 to the current locale. The conversion is identical to that
25358 produced by XmbTextPropertyToTextList for a single element
25359 STRING property. The returned string is owned by Xlib and
25360 should not be freed by the client. The property value must be
25361 in a format that is acceptable to XrmGetStringDatabase. If no
25362 property exists, NULL is returned.
25363
25364 To obtain a pointer to the screen-specific resources of a
25365 screen, use XScreenResourceString.
25366
25367 char *XScreenResourceString(Screen *screen);
25368
25369 screen
25370
25371 Specifies the screen.
25372
25373 The XScreenResourceString function returns the SCREEN_RESOURCES
25374 property from the root window of the specified screen. The
25375 property is converted from type STRING to the current locale.
25376 The conversion is identical to that produced by
25377 XmbTextPropertyToTextList for a single element STRING property.
25378 The property value must be in a format that is acceptable to
25379 XrmGetStringDatabase. If no property exists, NULL is returned.
25380 The caller is responsible for freeing the returned string by
25381 using XFree.
25382
25383 To create a database from a string, use XrmGetStringDatabase.
25384
25385 XrmDatabase XrmGetStringDatabase(char *data);
25386
25387 data
25388
25389 Specifies the database contents using a string.
25390
25391 The XrmGetStringDatabase function creates a new database and
25392 stores the resources specified in the specified null-terminated
25393 string. XrmGetStringDatabase is similar to XrmGetFileDatabase
25394 except that it reads the information out of a string instead of
25395 out of a file. The string should contain a sequence of entries
25396 in valid ResourceLine format (see section 15.1) terminated by a
25397 null character; the database that results from using a string
25398 with incorrect syntax is implementation-dependent. The string
25399 is parsed in the current locale, and the database is created in
25400 the current locale.
25401
25402 To obtain the locale name of a database, use
25403 XrmLocaleOfDatabase.
25404
25405 char *XrmLocaleOfDatabase(XrmDatabase database);
25406
25407 database
25408
25409 Specifies the resource database.
25410
25411 The XrmLocaleOfDatabase function returns the name of the locale
25412 bound to the specified database, as a null-terminated string.
25413 The returned locale name string is owned by Xlib and should not
25414 be modified or freed by the client. Xlib is not permitted to
25415 free the string until the database is destroyed. Until the
25416 string is freed, it will not be modified by Xlib.
25417
25418 To destroy a resource database and free its allocated memory,
25419 use XrmDestroyDatabase.
25420
25421 void XrmDestroyDatabase(XrmDatabase database);
25422
25423 database
25424
25425 Specifies the resource database.
25426
25427 If database is NULL, XrmDestroyDatabase returns immediately.
25428
25429 To associate a resource database with a display, use
25430 XrmSetDatabase.
25431
25432 void XrmSetDatabase(Display *display, XrmDatabase database);
25433
25434 display
25435
25436 Specifies the connection to the X server.
25437
25438 database
25439
25440 Specifies the resource database.
25441
25442 The XrmSetDatabase function associates the specified resource
25443 database (or NULL) with the specified display. The database
25444 previously associated with the display (if any) is not
25445 destroyed. A client or toolkit may find this function
25446 convenient for retaining a database once it is constructed.
25447
25448 To get the resource database associated with a display, use
25449 XrmGetDatabase.
25450
25451 XrmDatabase XrmGetDatabase(Display *display);
25452
25453 display
25454
25455 Specifies the connection to the X server.
25456
25457 The XrmGetDatabase function returns the database associated
25458 with the specified display. It returns NULL if a database has
25459 not yet been set.
25460
25461Merging Resource Databases
25462
25463 To merge the contents of a resource file into a database, use
25464 XrmCombineFileDatabase.
25465
25466 Status XrmCombineFileDatabase(char *filename, XrmDatabase
25467 *target_db, Bool override);
25468
25469 filename
25470
25471 Specifies the resource database file name.
25472
25473 target_db
25474
25475 Specifies the resource database into which the source database
25476 is to be merged.
25477
25478 override
25479
25480 Specifies whether source entries override target ones.
25481
25482 The XrmCombineFileDatabase function merges the contents of a
25483 resource file into a database. If the same specifier is used
25484 for an entry in both the file and the database, the entry in
25485 the file will replace the entry in the database if override is
25486 True; otherwise, the entry in the file is discarded. The file
25487 is parsed in the current locale. If the file cannot be read, a
25488 zero status is returned; otherwise, a nonzero status is
25489 returned. If target_db contains NULL, XrmCombineFileDatabase
25490 creates and returns a new database to it. Otherwise, the
25491 database pointed to by target_db is not destroyed by the merge.
25492 The database entries are merged without changing values or
25493 types, regardless of the locale of the database. The locale of
25494 the target database is not modified.
25495
25496 To merge the contents of one database into another database,
25497 use XrmCombineDatabase.
25498
25499 void XrmCombineDatabase(XrmDatabase source_db, XrmDatabase
25500 *target_db, Bool override);
25501
25502 source_db
25503
25504 Specifies the resource database that is to be merged into the
25505 target database.
25506
25507 target_db
25508
25509 Specifies the resource database into which the source database
25510 is to be merged.
25511
25512 override
25513
25514 Specifies whether source entries override target ones.
25515
25516 The XrmCombineDatabase function merges the contents of one
25517 database into another. If the same specifier is used for an
25518 entry in both databases, the entry in the source_db will
25519 replace the entry in the target_db if override is True;
25520 otherwise, the entry in source_db is discarded. If target_db
25521 contains NULL, XrmCombineDatabase simply stores source_db in
25522 it. Otherwise, source_db is destroyed by the merge, but the
25523 database pointed to by target_db is not destroyed. The database
25524 entries are merged without changing values or types, regardless
25525 of the locales of the databases. The locale of the target
25526 database is not modified.
25527
25528 To merge the contents of one database into another database
25529 with override semantics, use XrmMergeDatabases.
25530
25531 void XrmMergeDatabases(XrmDatabase source_db, XrmDatabase
25532 *target_db);
25533
25534 source_db
25535
25536 Specifies the resource database that is to be merged into the
25537 target database.
25538
25539 target_db
25540
25541 Specifies the resource database into which the source database
25542 is to be merged.
25543
25544 Calling the XrmMergeDatabases function is equivalent to calling
25545 the XrmCombineDatabase function with an override argument of
25546 True.
25547
25548Looking Up Resources
25549
25550 To retrieve a resource from a resource database, use
25551 XrmGetResource, XrmQGetResource, or XrmQGetSearchResource.
25552
25553 Bool XrmGetResource(XrmDatabase database, char *str_name, char
25554 *str_class, char **str_type_return, XrmValue *value_return);
25555
25556 database
25557
25558 Specifies the database that is to be used.
25559
25560 str_name
25561
25562 Specifies the fully qualified name of the value being retrieved
25563 (as a string).
25564
25565 str_class
25566
25567 Specifies the fully qualified class of the value being
25568 retrieved (as a string).
25569
25570 str_type_return
25571
25572 Returns the representation type of the destination (as a
25573 string).
25574
25575 value_return
25576
25577 Returns the value in the database.
25578
25579 Bool XrmQGetResource(XrmDatabase database, XrmNameList
25580 quark_name, XrmClassList quark_class, XrmRepresentation
25581 *quark_type_return, XrmValue *value_return);
25582
25583 database
25584
25585 Specifies the database that is to be used.
25586
25587 quark_name
25588
25589 Specifies the fully qualified name of the value being retrieved
25590 (as a quark).
25591
25592 quark_class
25593
25594 Specifies the fully qualified class of the value being
25595 retrieved (as a quark).
25596
25597 quark_type_return
25598
25599 Returns the representation type of the destination (as a
25600 quark).
25601
25602 value_return
25603
25604 Returns the value in the database.
25605
25606 The XrmGetResource and XrmQGetResource functions retrieve a
25607 resource from the specified database. Both take a fully
25608 qualified name/class pair, a destination resource
25609 representation, and the address of a value (size/address pair).
25610 The value and returned type point into database memory;
25611 therefore, you must not modify the data.
25612
25613 The database only frees or overwrites entries on
25614 XrmPutResource, XrmQPutResource, or XrmMergeDatabases. A client
25615 that is not storing new values into the database or is not
25616 merging the database should be safe using the address passed
25617 back at any time until it exits. If a resource was found, both
25618 XrmGetResource and XrmQGetResource return True; otherwise, they
25619 return False.
25620
25621 Most applications and toolkits do not make random probes into a
25622 resource database to fetch resources. The X toolkit access
25623 pattern for a resource database is quite stylized. A series of
25624 from 1 to 20 probes is made with only the last name/class
25625 differing in each probe. The XrmGetResource function is at
25626 worst a 2^n algorithm, where n is the length of the name/class
25627 list. This can be improved upon by the application programmer
25628 by prefetching a list of database levels that might match the
25629 first part of a name/class list.
25630
25631 To obtain a list of database levels, use XrmQGetSearchList.
25632
25633 Bool XrmQGetSearchResource(XrmDatabase database, XrmNameList
25634 names, XrmClassList classes, XrmSearchList list_return, int
25635 list_length);
25636
25637 database
25638
25639 Specifies the database that is to be used.
25640
25641 names
25642
25643 Specifies a list of resource names.
25644
25645 classes
25646
25647 Specifies a list of resource classes.
25648
25649 list_return
25650
25651 Returns a search list for further use. The caller must allocate
25652 sufficient space for the list before calling XrmQGetSearchList.
25653
25654 list_length
25655
25656 Specifies the number of entries (not the byte size) allocated
25657 for list_return.
25658
25659 The XrmQGetSearchList function takes a list of names and
25660 classes and returns a list of database levels where a match
25661 might occur. The returned list is in best-to-worst order and
25662 uses the same algorithm as XrmGetResource for determining
25663 precedence. If list_return was large enough for the search
25664 list, XrmQGetSearchList returns True; otherwise, it returns
25665 False.
25666
25667 The size of the search list that the caller must allocate is
25668 dependent upon the number of levels and wildcards in the
25669 resource specifiers that are stored in the database. The worst
25670 case length is 3^n, where n is the number of name or class
25671 components in names or classes.
25672
25673 When using XrmQGetSearchList followed by multiple probes for
25674 resources with a common name and class prefix, only the common
25675 prefix should be specified in the name and class list to
25676 XrmQGetSearchList.
25677
25678 To search resource database levels for a given resource, use
25679 XrmQGetSearchResource.
25680
25681 Bool XrmQGetSearchResource(XrmSearchList list, XrmName name,
25682 XrmClass class, XrmRepresentation *type_return, XrmValue
25683 *value_return);
25684
25685 list
25686
25687 Specifies the search list returned by XrmQGetSearchList.
25688
25689 name
25690
25691 Specifies the resource name.
25692
25693 class
25694
25695 Specifies the resource class.
25696
25697 type_return
25698
25699 Returns data representation type.
25700
25701 value_return
25702
25703 Returns the value in the database.
25704
25705 The XrmQGetSearchResource function searches the specified
25706 database levels for the resource that is fully identified by
25707 the specified name and class. The search stops with the first
25708 match. XrmQGetSearchResource returns True if the resource was
25709 found; otherwise, it returns False.
25710
25711 A call to XrmQGetSearchList with a name and class list
25712 containing all but the last component of a resource name
25713 followed by a call to XrmQGetSearchResource with the last
25714 component name and class returns the same database entry as
25715 XrmGetResource and XrmQGetResource with the fully qualified
25716 name and class.
25717
25718Storing into a Resource Database
25719
25720 To store resources into the database, use XrmPutResource or
25721 XrmQPutResource. Both functions take a partial resource
25722 specification, a representation type, and a value. This value
25723 is copied into the specified database.
25724
25725 void XrmPutResource(XrmDatabase *database, char *specifier,
25726 char *type, XrmValue *value);
25727
25728 database
25729
25730 Specifies the resource database.
25731
25732 specifier
25733
25734 Specifies a complete or partial specification of the resource.
25735
25736 type
25737
25738 Specifies the type of the resource.
25739
25740 value
25741
25742 Specifies the value of the resource, which is specified as a
25743 string.
25744
25745 If database contains NULL, XrmPutResource creates a new
25746 database and returns a pointer to it. XrmPutResource is a
25747 convenience function that calls XrmStringToBindingQuarkList
25748 followed by:
25749
25750XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), valu
25751e)
25752
25753 If the specifier and type are not in the Host Portable
25754 Character Encoding, the result is implementation-dependent. The
25755 value is stored in the database without modification.
25756
25757 void XrmQPutResource(XrmDatabase *database, XrmBindingList
25758 bindings, XrmQuarkList quarks, XrmRepresentation type, XrmValue
25759 *value);
25760
25761 database
25762
25763 Specifies the resource database.
25764
25765 bindings
25766
25767 Specifies a list of bindings.
25768
25769 quarks
25770
25771 Specifies the complete or partial name or the class list of the
25772 resource.
25773
25774 type
25775
25776 Specifies the type of the resource.
25777
25778 value
25779
25780 Specifies the value of the resource, which is specified as a
25781 string.
25782
25783 If database contains NULL, XrmQPutResource creates a new
25784 database and returns a pointer to it. If a resource entry with
25785 the identical bindings and quarks already exists in the
25786 database, the previous type and value are replaced by the new
25787 specified type and value. The value is stored in the database
25788 without modification.
25789
25790 To add a resource that is specified as a string, use
25791 XrmPutStringResource.
25792
25793 void XrmPutStringResource(XrmDatabase *database, char
25794 *specifier, char *value);
25795
25796 database
25797
25798 Specifies the resource database.
25799
25800 specifier
25801
25802 Specifies a complete or partial specification of the resource.
25803
25804 value
25805
25806 Specifies the value of the resource, which is specified as a
25807 string.
25808
25809 If database contains NULL, XrmPutStringResource creates a new
25810 database and returns a pointer to it. XrmPutStringResource adds
25811 a resource with the specified value to the specified database.
25812 XrmPutStringResource is a convenience function that first calls
25813 XrmStringToBindingQuarkList on the specifier and then calls
25814 XrmQPutResource, using a ``String'' representation type. If the
25815 specifier is not in the Host Portable Character Encoding, the
25816 result is implementation-dependent. The value is stored in the
25817 database without modification.
25818
25819 To add a string resource using quarks as a specification, use
25820 XrmQPutStringResource.
25821
25822 void XrmQPutStringResource(XrmDatabase *database,
25823 XrmBindingList bindings, XrmQuarkList quarks, char *value);
25824
25825 database
25826
25827 Specifies the resource database.
25828
25829 bindings
25830
25831 Specifies a list of bindings.
25832
25833 quarks
25834
25835 Specifies the complete or partial name or the class list of the
25836 resource.
25837
25838 value
25839
25840 Specifies the value of the resource, which is specified as a
25841 string.
25842
25843 If database contains NULL, XrmQPutStringResource creates a new
25844 database and returns a pointer to it. XrmQPutStringResource is
25845 a convenience routine that constructs an XrmValue for the value
25846 string (by calling strlen to compute the size) and then calls
25847 XrmQPutResource, using a ``String'' representation type. The
25848 value is stored in the database without modification.
25849
25850 To add a single resource entry that is specified as a string
25851 that contains both a name and a value, use XrmPutLineResource.
25852
25853 void XrmPutLineResource(XrmDatabase *database, char *line);
25854
25855 database
25856
25857 Specifies the resource database.
25858
25859 line
25860
25861 Specifies the resource name and value pair as a single string.
25862
25863 If database contains NULL, XrmPutLineResource creates a new
25864 database and returns a pointer to it. XrmPutLineResource adds a
25865 single resource entry to the specified database. The line
25866 should be in valid ResourceLine format (see section 15.1)
25867 terminated by a newline or null character; the database that
25868 results from using a string with incorrect syntax is
25869 implementation-dependent. The string is parsed in the locale of
25870 the database. If the ResourceName is not in the Host Portable
25871 Character Encoding, the result is implementation-dependent.
25872 Note that comment lines are not stored.
25873
25874Enumerating Database Entries
25875
25876 To enumerate the entries of a database, use
25877 XrmEnumerateDatabase.
25878#define XrmEnumAllLevels 0
25879#define XrmEnumOneLevel 0
25880
25881 Bool XrmEnumerateDatabase(XrmDatabase database, XrmNameList
25882 name_prefix, XrmClassList class_prefix, int mode, Bool
25883 (*proc)(), XPointer arg);
25884
25885 database
25886
25887 Specifies the resource database.
25888
25889 name_prefix
25890
25891 Specifies the resource name prefix.
25892
25893 class_prefix
25894
25895 Specifies the resource class prefix.
25896
25897 mode
25898
25899 Specifies the number of levels to enumerate.
25900
25901 proc
25902
25903 Specifies the procedure that is to be called for each matching
25904 entry.
25905
25906 arg
25907
25908 Specifies the user-supplied argument that will be passed to the
25909 procedure.
25910
25911 The XrmEnumerateDatabase function calls the specified procedure
25912 for each resource in the database that would match some
25913 completion of the given name/class resource prefix. The order
25914 in which resources are found is implementation-dependent. If
25915 mode is XrmEnumOneLevel, a resource must match the given
25916 name/class prefix with just a single name and class appended.
25917 If mode is XrmEnumAllLevels, the resource must match the given
25918 name/class prefix with one or more names and classes appended.
25919 If the procedure returns True, the enumeration terminates and
25920 the function returns True. If the procedure always returns
25921 False, all matching resources are enumerated and the function
25922 returns False.
25923
25924 The procedure is called with the following arguments:
25925
25926
25927
25928(*proc)(database, bindings, quarks, type, value, arg)
25929 XrmDatabase *database;
25930 XrmBindingList bindings;
25931 XrmQuarkList quarks;
25932 XrmRepresentation *type;
25933 XrmValue *value;
25934 XPointer arg;
25935
25936 The bindings and quarks lists are terminated by NULLQUARK. Note
25937 that pointers to the database and type are passed, but these
25938 values should not be modified.
25939
25940 The procedure must not modify the database. If Xlib has been
25941 initialized for threads, the procedure is called with the
25942 database locked and the result of a call by the procedure to
25943 any Xlib function using the same database is not defined.
25944
25945Parsing Command Line Options
25946
25947 The XrmParseCommand function can be used to parse the command
25948 line arguments to a program and modify a resource database with
25949 selected entries from the command line.
25950
25951
25952
25953typedef enum {
25954 XrmoptionNoArg, /* Value is specified in XrmOptionDescRec.value
25955 */
25956 XrmoptionIsArg, /* Value is the option string itself */
25957 XrmoptionStickyArg, /* Value is characters immediately followin
25958g option */
25959 XrmoptionSepArg, /* Value is next argument in argv */
25960 XrmoptionResArg, /* Resource and value in next argument in argv
25961 */
25962 XrmoptionSkipArg, /* Ignore this option and the next argument i
25963n argv */
25964 XrmoptionSkipLine, /* Ignore this option and the rest of argv *
25965/
25966 XrmoptionSkipNArgs /* Ignore this option and the next
25967 \ \ \ XrmOptionDescRec.value arguments in argv */
25968} XrmOptionKind;
25969
25970 Note that XrmoptionSkipArg is equivalent to XrmoptionSkipNArgs
25971 with the XrmOptionDescRec.value field containing the value one.
25972 Note also that the value zero for XrmoptionSkipNArgs indicates
25973 that only the option itself is to be skipped.
25974
25975
25976
25977typedef struct {
25978 char *option; /* Option specification string in argv
25979 */
25980 char *specifier; /* Binding and resource name (sans application
25981 name) */
25982 XrmOptionKind argKind; /* Which style of option it is *
25983/
25984 XPointer value; /* Value to provide if XrmoptionNoArg or
25985 \ \ \ XrmoptionSkipNArgs */
25986} XrmOptionDescRec, *XrmOptionDescList;
25987
25988 To load a resource database from a C command line, use
25989 XrmParseCommand.
25990
25991 void XrmParseCommand(XrmDatabase *database, XrmOptionDescList
25992 table, int table_count, char *name, int *argc_in_out, char
25993 **argv_in_out);
25994
25995 database
25996
25997 Specifies the resource database.
25998
25999 table
26000
26001 Specifies the table of command line arguments to be parsed.
26002
26003 table_count
26004
26005 Specifies the number of entries in the table.
26006
26007 name
26008
26009 Specifies the application name.
26010
26011 argc_in_out
26012
26013 Specifies the number of arguments and returns the number of
26014 remaining arguments.
26015
26016 argv_in_out
26017
26018 Specifies the command line arguments and returns the remaining
26019 arguments.
26020
26021 The XrmParseCommand function parses an (argc, argv) pair
26022 according to the specified option table, loads recognized
26023 options into the specified database with type ``String,'' and
26024 modifies the (argc, argv) pair to remove all recognized
26025 options. If database contains NULL, XrmParseCommand creates a
26026 new database and returns a pointer to it. Otherwise, entries
26027 are added to the database specified. If a database is created,
26028 it is created in the current locale.
26029
26030 The specified table is used to parse the command line.
26031 Recognized options in the table are removed from argv, and
26032 entries are added to the specified resource database in the
26033 order they occur in argv. The table entries contain information
26034 on the option string, the option name, the style of option, and
26035 a value to provide if the option kind is XrmoptionNoArg. The
26036 option names are compared byte-for-byte to arguments in argv,
26037 independent of any locale. The resource values given in the
26038 table are stored in the resource database without modification.
26039 All resource database entries are created using a ``String''
26040 representation type. The argc argument specifies the number of
26041 arguments in argv and is set on return to the remaining number
26042 of arguments that were not parsed. The name argument should be
26043 the name of your application for use in building the database
26044 entry. The name argument is prefixed to the resourceName in the
26045 option table before storing a database entry. The name argument
26046 is treated as a single component, even if it has embedded
26047 periods. No separating (binding) character is inserted, so the
26048 table must contain either a period (.) or an asterisk (*) as
26049 the first character in each resourceName entry. To specify a
26050 more completely qualified resource name, the resourceName entry
26051 can contain multiple components. If the name argument and the
26052 resourceNames are not in the Host Portable Character Encoding,
26053 the result is implementation-dependent.
26054
26055 The following provides a sample option table:
26056
26057
26058
26059static XrmOptionDescRec opTable[] = {
26060{"-background", "*background", XrmoptionSepArg, (
26061XPointer) NULL},
26062{"-bd", "*borderColor", XrmoptionSepArg, (
26063XPointer) NULL},
26064{"-bg", "*background", XrmoptionSepArg, (
26065XPointer) NULL},
26066{"-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, (
26067XPointer) NULL},
26068{"-bordercolor", "*borderColor", XrmoptionSepArg, (
26069XPointer) NULL},
26070{"-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, (
26071XPointer) NULL},
26072{"-display", ".display", XrmoptionSepArg, (
26073XPointer) NULL},
26074{"-fg", "*foreground", XrmoptionSepArg, (
26075XPointer) NULL},
26076{"-fn", "*font", XrmoptionSepArg, (
26077XPointer) NULL},
26078{"-font", "*font", XrmoptionSepArg, (
26079XPointer) NULL},
26080{"-foreground", "*foreground", XrmoptionSepArg, (
26081XPointer) NULL},
26082{"-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, (
26083XPointer) NULL},
26084{"-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, (
26085XPointer) "on"},
26086{"-name", ".name", XrmoptionSepArg, (
26087XPointer) NULL},
26088{"-reverse", "*reverseVideo", XrmoptionNoArg, (
26089XPointer) "on"},
26090{"-rv", "*reverseVideo", XrmoptionNoArg, (
26091XPointer) "on"},
26092{"-synchronous", "*synchronous", XrmoptionNoArg, (
26093XPointer) "on"},
26094{"-title", ".TopLevelShell.title", XrmoptionSepArg, (
26095XPointer) NULL},
26096{"-xrm", NULL, XrmoptionResArg, (
26097XPointer) NULL},
26098};
26099
26100 In this table, if the -background (or -bg) option is used to
26101 set background colors, the stored resource specifier matches
26102 all resources of attribute background. If the -borderwidth
26103 option is used, the stored resource specifier applies only to
26104 border width attributes of class TopLevelShell (that is,
26105 outer-most windows, including pop-up windows). If the -title
26106 option is used to set a window name, only the topmost
26107 application windows receive the resource.
26108
26109 When parsing the command line, any unique unambiguous
26110 abbreviation for an option name in the table is considered a
26111 match for the option. Note that uppercase and lowercase matter.
26112
26113Chapter 16. Application Utility Functions
26114
26115 Table of Contents
26116
26117 Using Keyboard Utility Functions
26118
26119 KeySym Classification Macros
26120
26121 Using Latin-1 Keyboard Event Functions
26122 Allocating Permanent Storage
26123 Parsing the Window Geometry
26124 Manipulating Regions
26125
26126 Creating, Copying, or Destroying Regions
26127 Moving or Shrinking Regions
26128 Computing with Regions
26129 Determining if Regions Are Empty or Equal
26130 Locating a Point or a Rectangle in a Region
26131
26132 Using Cut Buffers
26133 Determining the Appropriate Visual Type
26134 Manipulating Images
26135 Manipulating Bitmaps
26136 Using the Context Manager
26137
26138 Once you have initialized the X system, you can use the Xlib
26139 utility functions to:
26140 * Use keyboard utility functions
26141 * Use Latin-1 keyboard event functions
26142 * Allocate permanent storage
26143 * Parse the window geometry
26144 * Manipulate regions
26145 * Use cut buffers
26146 * Determine the appropriate visual type
26147 * Manipulate images
26148 * Manipulate bitmaps
26149 * Use the context manager
26150
26151 As a group, the functions discussed in this chapter provide the
26152 functionality that is frequently needed and that spans
26153 toolkits. Many of these functions do not generate actual
26154 protocol requests to the server.
26155
26156Using Keyboard Utility Functions
26157
26158 This section discusses mapping between KeyCodes and KeySyms,
26159 classifying KeySyms, and mapping between KeySyms and string
26160 names. The first three functions in this section operate on a
26161 cached copy of the server keyboard mapping. The first four
26162 KeySyms for each KeyCode are modified according to the rules
26163 given in section 12.7. To obtain the untransformed KeySyms
26164 defined for a key, use the functions described in section 12.7.
26165
26166 To obtain a KeySym for the KeyCode of an event, use
26167 XLookupKeysym.
26168
26169 KeySym XLookupKeysym(XKeyEvent *key_event, int index);
26170
26171 key_event
26172
26173 Specifies the KeyPress or KeyRelease event.
26174
26175 index
26176
26177 Specifies the index into the KeySyms list for the event's
26178 KeyCode.
26179
26180 The XLookupKeysym function uses a given keyboard event and the
26181 index you specified to return the KeySym from the list that
26182 corresponds to the KeyCode member in the XKeyPressedEvent or
26183 XKeyReleasedEvent structure. If no KeySym is defined for the
26184 KeyCode of the event, XLookupKeysym returns NoSymbol.
26185
26186 To obtain a KeySym for a specific KeyCode, use
26187 XKeycodeToKeysym.
26188
26189 KeySym XKeycodeToKeysym(Display *display, KeyCode keycode, int
26190 index);
26191
26192 display
26193
26194 Specifies the connection to the X server.
26195
26196 keycode
26197
26198 Specifies the KeyCode.
26199
26200 index
26201
26202 Specifies the element of KeyCode vector.
26203
26204 The XKeycodeToKeysym function uses internal Xlib tables and
26205 returns the KeySym defined for the specified KeyCode and the
26206 element of the KeyCode vector. If no symbol is defined,
26207 XKeycodeToKeysym returns NoSymbol.
26208
26209 To obtain a KeyCode for a key having a specific KeySym, use
26210 XKeysymToKeycode.
26211
26212 KeyCode XKeysymToKeycode(Display *display, KeySym keysym);
26213
26214 display
26215
26216 Specifies the connection to the X server.
26217
26218 keysym
26219
26220 Specifies the KeySym that is to be searched for.
26221
26222 If the specified KeySym is not defined for any KeyCode,
26223 XKeysymToKeycode returns zero.
26224
26225 The mapping between KeyCodes and KeySyms is cached internal to
26226 Xlib. When this information is changed at the server, an Xlib
26227 function must be called to refresh the cache. To refresh the
26228 stored modifier and keymap information, use
26229 XRefreshKeyboardMapping.
26230
26231 XRefreshKeyboardMapping(XMappingEvent *event_map);
26232
26233 event_map
26234
26235 Specifies the mapping event that is to be used.
26236
26237 The XRefreshKeyboardMapping function refreshes the stored
26238 modifier and keymap information. You usually call this function
26239 when a MappingNotify event with a request member of
26240 MappingKeyboard or MappingModifier occurs. The result is to
26241 update Xlib's knowledge of the keyboard.
26242
26243 To obtain the uppercase and lowercase forms of a KeySym, use
26244 XConvertCase.
26245
26246 void XConvertCase(KeySym keysym, KeySym *lower_return, KeySym
26247 *upper_return);
26248
26249 keysym
26250
26251 Specifies the KeySym that is to be converted.
26252
26253 lower_return
26254
26255 Returns the lowercase form of keysym, or keysym.
26256
26257 upper_return
26258
26259 Returns the uppercase form of keysym, or keysym.
26260
26261 The XConvertCase function returns the uppercase and lowercase
26262 forms of the specified Keysym, if the KeySym is subject to case
26263 conversion; otherwise, the specified KeySym is returned to both
26264 lower_return and upper_return. Support for conversion of other
26265 than Latin and Cyrillic KeySyms is implementation-dependent.
26266
26267 KeySyms have string names as well as numeric codes. To convert
26268 the name of the KeySym to the KeySym code, use XStringToKeysym.
26269
26270 KeySym XStringToKeysym(char *string);
26271
26272 string
26273
26274 Specifies the name of the KeySym that is to be converted.
26275
26276 Standard KeySym names are obtained from <X11/keysymdef.h> by
26277 removing the XK_ prefix from each name. KeySyms that are not
26278 part of the Xlib standard also may be obtained with this
26279 function. The set of KeySyms that are available in this manner
26280 and the mechanisms by which Xlib obtains them is
26281 implementation-dependent.
26282
26283 If the KeySym name is not in the Host Portable Character
26284 Encoding, the result is implementation-dependent. If the
26285 specified string does not match a valid KeySym, XStringToKeysym
26286 returns NoSymbol.
26287
26288 To convert a KeySym code to the name of the KeySym, use
26289 XKeysymToString.
26290
26291 char *XKeysymToString(KeySym keysym);
26292
26293 keysym
26294
26295 Specifies the KeySym that is to be converted.
26296
26297 The returned string is in a static area and must not be
26298 modified. The returned string is in the Host Portable Character
26299 Encoding. If the specified KeySym is not defined,
26300 XKeysymToString returns a NULL.
26301
26302KeySym Classification Macros
26303
26304 You may want to test if a KeySym is, for example, on the keypad
26305 or on one of the function keys. You can use KeySym macros to
26306 perform the following tests.
26307
26308 IsCursorKey(keysym)
26309
26310 keysym
26311
26312 Specifies the KeySym that is to be tested.
26313
26314 Returns True if the specified KeySym is a cursor key.
26315
26316 IsFunctionKey(keysym)
26317
26318 keysym
26319
26320 Specifies the KeySym that is to be tested.
26321
26322 Returns True if the specified KeySym is a function key.
26323
26324 IsKeypadKey(keysym)
26325
26326 keysym
26327
26328 Specifies the KeySym that is to be tested.
26329
26330 Returns True if the specified KeySym is a standard keypad key.
26331
26332 IsPrivateKeypadKey(keysym)
26333
26334 keysym
26335
26336 Specifies the KeySym that is to be tested.
26337
26338 Returns True if the specified KeySym is a vendor-private keypad
26339 key.
26340
26341 IsMiscFunctionKey(keysym)
26342
26343 keysym
26344
26345 Specifies the KeySym that is to be tested.
26346
26347 Returns True if the specified KeySym is a miscellaneous
26348 function key.
26349
26350 IsModifierKey(keysym)
26351
26352 keysym
26353
26354 Specifies the KeySym that is to be tested.
26355
26356 Returns True if the specified KeySym is a modifier key.
26357
26358 IsPFKey(keysym)
26359
26360 keysym
26361
26362 Specifies the KeySym that is to be tested.
26363
26364 Returns True if the specified KeySym is a PF key.
26365
26366Using Latin-1 Keyboard Event Functions
26367
26368 Chapter 13 describes internationalized text input facilities,
26369 but sometimes it is expedient to write an application that only
26370 deals with Latin-1 characters and ASCII controls, so Xlib
26371 provides a simple function for that purpose. XLookupString
26372 handles the standard modifier semantics described in section
26373 12.7. This function does not use any of the input method
26374 facilities described in chapter 13 and does not depend on the
26375 current locale.
26376
26377 To map a key event to an ISO Latin-1 string, use XLookupString.
26378
26379 int XLookupString(XKeyEvent *event_struct, char *buffer_return,
26380 int bytes_buffer, KeySym *keysym_return, XComposeStatus
26381 *status_in_out);
26382
26383 event_struct
26384
26385 Specifies the key event structure to be used. You can pass
26386 XKeyPressedEvent or XKeyReleasedEvent.
26387
26388 buffer_return
26389
26390 Returns the translated characters.
26391
26392 bytes_buffer
26393
26394 Specifies the length of the buffer. No more than bytes_buffer
26395 of translation are returned.
26396
26397 keysym_return
26398
26399 Returns the KeySym computed from the event if this argument is
26400 not NULL.
26401
26402 status_in_out
26403
26404 Specifies or returns the XComposeStatus structure or NULL.
26405
26406 The XLookupString function translates a key event to a KeySym
26407 and a string. The KeySym is obtained by using the standard
26408 interpretation of the Shift, Lock, group, and numlock modifiers
26409 as defined in the X Protocol specification. If the KeySym has
26410 been rebound (see XRebindKeysym), the bound string will be
26411 stored in the buffer. Otherwise, the KeySym is mapped, if
26412 possible, to an ISO Latin-1 character or (if the Control
26413 modifier is on) to an ASCII control character, and that
26414 character is stored in the buffer. XLookupString returns the
26415 number of characters that are stored in the buffer.
26416
26417 If present (non-NULL), the XComposeStatus structure records the
26418 state, which is private to Xlib, that needs preservation across
26419 calls to XLookupString to implement compose processing. The
26420 creation of XComposeStatus structures is
26421 implementation-dependent; a portable program must pass NULL for
26422 this argument.
26423
26424 XLookupString depends on the cached keyboard information
26425 mentioned in the previous section, so it is necessary to use
26426 XRefreshKeyboardMapping to keep this information up-to-date.
26427
26428 To rebind the meaning of a KeySym for XLookupString, use
26429 XRebindKeysym.
26430
26431 XRebindKeysym(Display *display, KeySym keysym, KeySym list[],
26432 int mod_count, unsignedchar *string, int num_bytes);
26433
26434 display
26435
26436 Specifies the connection to the X server.
26437
26438 keysym
26439
26440 Specifies the KeySym that is to be rebound.
26441
26442 list
26443
26444 Specifies the KeySyms to be used as modifiers.
26445
26446 mod_count
26447
26448 Specifies the number of modifiers in the modifier list.
26449
26450 string
26451
26452 Specifies the string that is copied and will be returned by
26453 XLookupString.
26454
26455 num_bytes
26456
26457 Specifies the number of bytes in the string argument.
26458
26459 The XRebindKeysym function can be used to rebind the meaning of
26460 a KeySym for the client. It does not redefine any key in the X
26461 server but merely provides an easy way for long strings to be
26462 attached to keys. XLookupString returns this string when the
26463 appropriate set of modifier keys are pressed and when the
26464 KeySym would have been used for the translation. No text
26465 conversions are performed; the client is responsible for
26466 supplying appropriately encoded strings. Note that you can
26467 rebind a KeySym that may not exist.
26468
26469Allocating Permanent Storage
26470
26471 To allocate some memory you will never give back, use
26472 Xpermalloc.
26473
26474 char *Xpermalloc(unsigned int size);
26475
26476 The Xpermalloc function allocates storage that can never be
26477 freed for the life of the program. The memory is allocated with
26478 alignment for the C type double. This function may provide some
26479 performance and space savings over the standard operating
26480 system memory allocator.
26481
26482Parsing the Window Geometry
26483
26484 To parse standard window geometry strings, use XParseGeometry.
26485
26486 int XParseGeometry(char *parsestring, int *x_return, int
26487 *y_return, unsigned int *width_return, unsigned int
26488 *height_return);
26489
26490 parsestring
26491
26492 Specifies the string you want to parse.
26493
26494 x_return
26495
26496 y_return
26497
26498 Return the x and y offsets.
26499
26500 width_return
26501
26502 height_return
26503
26504 Return the width and height determined.
26505
26506 By convention, X applications use a standard string to indicate
26507 window size and placement. XParseGeometry makes it easier to
26508 conform to this standard because it allows you to parse the
26509 standard window geometry. Specifically, this function lets you
26510 parse strings of the form:
26511
26512[=][<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>]
26513
26514 The fields map into the arguments associated with this
26515 function. (Items enclosed in <> are integers, items in [] are
26516 optional, and items enclosed in {} indicate ``choose one of.''
26517 Note that the brackets should not appear in the actual string.)
26518 If the string is not in the Host Portable Character Encoding,
26519 the result is implementation-dependent.
26520
26521 The XParseGeometry function returns a bitmask that indicates
26522 which of the four values (width, height, xoffset, and yoffset)
26523 were actually found in the string and whether the x and y
26524 values are negative. By convention, -0 is not equal to +0,
26525 because the user needs to be able to say ``position the window
26526 relative to the right or bottom edge.'' For each value found,
26527 the corresponding argument is updated. For each value not
26528 found, the argument is left unchanged. The bits are represented
26529 by XValue, YValue, WidthValue, HeightValue, XNegative, or
26530 YNegative and are defined in <X11/Xutil.h>. They will be set
26531 whenever one of the values is defined or one of the signs is
26532 set.
26533
26534 If the function returns either the XValue or YValue flag, you
26535 should place the window at the requested position.
26536
26537 To construct a window's geometry information, use XWMGeometry.
26538
26539 int XWMGeometry(Display *display, int screen, char *user_geom,
26540 char *def_geom, unsigned int bwidth, XSizeHints *hints, int
26541 *x_return, int *y_return, int *width_return, int
26542 *height_return, int *gravity_return);
26543
26544 display
26545
26546 Specifies the connection to the X server.
26547
26548 screen
26549
26550 Specifies the screen.
26551
26552 user_geom
26553
26554 Specifies the user-specified geometry or NULL.
26555
26556 def_geom
26557
26558 Specifies the application's default geometry or NULL.
26559
26560 bwidth
26561
26562 Specifies the border width.
26563
26564 hints
26565
26566 Specifies the size hints for the window in its normal state.
26567
26568 x_return
26569
26570 y_return
26571
26572 Return the x and y offsets.
26573
26574 width_return
26575
26576 height_return
26577
26578 Return the width and height determined.
26579
26580 gravity_return
26581
26582 Returns the window gravity.
26583
26584 The XWMGeometry function combines any geometry information
26585 (given in the format used by XParseGeometry) specified by the
26586 user and by the calling program with size hints (usually the
26587 ones to be stored in WM_NORMAL_HINTS) and returns the position,
26588 size, and gravity (NorthWestGravity, NorthEastGravity,
26589 SouthEastGravity, or SouthWestGravity) that describe the
26590 window. If the base size is not set in the XSizeHints
26591 structure, the minimum size is used if set. Otherwise, a base
26592 size of zero is assumed. If no minimum size is set in the hints
26593 structure, the base size is used. A mask (in the form returned
26594 by XParseGeometry) that describes which values came from the
26595 user specification and whether or not the position coordinates
26596 are relative to the right and bottom edges is returned. Note
26597 that these coordinates will have already been accounted for in
26598 the x_return and y_return values.
26599
26600 Note that invalid geometry specifications can cause a width or
26601 height of zero to be returned. The caller may pass the address
26602 of the hints win_gravity field as gravity_return to update the
26603 hints directly.
26604
26605Manipulating Regions
26606
26607 Regions are arbitrary sets of pixel locations. Xlib provides
26608 functions for manipulating regions. The opaque type Region is
26609 defined in <X11/Xutil.h>. Xlib provides functions that you can
26610 use to manipulate regions. This section discusses how to:
26611 * Create, copy, or destroy regions
26612 * Move or shrink regions
26613 * Compute with regions
26614 * Determine if regions are empty or equal
26615 * Locate a point or rectangle in a region
26616
26617Creating, Copying, or Destroying Regions
26618
26619 To create a new empty region, use XCreateRegion.
26620
26621 Region XCreateRegion(void);
26622
26623 To generate a region from a polygon, use XPolygonRegion.
26624
26625 Region XPolygonRegion(XPoint points[], int n, int fill_rule);
26626
26627 points
26628
26629 Specifies an array of points.
26630
26631 n
26632
26633 Specifies the number of points in the polygon.
26634
26635 fill_rule
26636
26637 Specifies the fill-rule you want to set for the specified GC.
26638 You can pass EvenOddRule or WindingRule.
26639
26640 The XPolygonRegion function returns a region for the polygon
26641 defined by the points array. For an explanation of fill_rule,
26642 see XCreateGC.
26643
26644 To set the clip-mask of a GC to a region, use XSetRegion.
26645
26646 XSetRegion(Display *display, GC gc, Region r);
26647
26648 display
26649
26650 Specifies the connection to the X server.
26651
26652 gc
26653
26654 Specifies the GC.
26655
26656 r
26657
26658 Specifies the region.
26659
26660 The XSetRegion function sets the clip-mask in the GC to the
26661 specified region. The region is specified relative to the
26662 drawable's origin. The resulting GC clip origin is
26663 implementation-dependent. Once it is set in the GC, the region
26664 can be destroyed.
26665
26666 To deallocate the storage associated with a specified region,
26667 use XDestroyRegion.
26668
26669 XDestroyRegion(Region r);
26670
26671 r
26672
26673 Specifies the region.
26674
26675Moving or Shrinking Regions
26676
26677 To move a region by a specified amount, use XOffsetRegion.
26678
26679 XOffsetRegion(Region r, int dx, int dy);
26680
26681 r
26682
26683 Specifies the region.
26684
26685 dx
26686
26687 dy
26688
26689 Specify the x and y coordinates, which define the amount you
26690 want to move the specified region.
26691
26692 To reduce a region by a specified amount, use XShrinkRegion.
26693
26694 XShrinkRegion(Region r, int dx, int dy);
26695
26696 r
26697
26698 Specifies the region.
26699
26700 dx
26701
26702 dy
26703
26704 Specify the x and y coordinates, which define the amount you
26705 want to shrink the specified region.
26706
26707 Positive values shrink the size of the region, and negative
26708 values expand the region.
26709
26710Computing with Regions
26711
26712 To generate the smallest rectangle enclosing a region, use
26713 XClipBox.
26714
26715 XClipBox(Region r, XRectangle *rect_return);
26716
26717 r
26718
26719 Specifies the region.
26720
26721 rect_return
26722
26723 Returns the smallest enclosing rectangle.
26724
26725 The XClipBox function returns the smallest rectangle enclosing
26726 the specified region.
26727
26728 To compute the intersection of two regions, use
26729 XIntersectRegion.
26730
26731 XIntersectRegion(Region sra, Region srb, Region dr_return);
26732
26733 sra
26734
26735 srb
26736
26737 Specify the two regions with which you want to perform the
26738 computation.
26739
26740 dr_return
26741
26742 Returns the result of the computation.
26743
26744 To compute the union of two regions, use XUnionRegion.
26745
26746 XUnionRegion(Region sra, Region srb, Region dr_return);
26747
26748 sra
26749
26750 srb
26751
26752 Specify the two regions with which you want to perform the
26753 computation.
26754
26755 dr_return
26756
26757 Returns the result of the computation.
26758
26759 To create a union of a source region and a rectangle, use
26760 XUnionRectWithRegion.
26761
26762 XUnionRectWithRegion(XRectangle *rectangle, Region src_region,
26763 Region dest_region_return);
26764
26765 rectangle
26766
26767 Specifies the rectangle.
26768
26769 src_region
26770
26771 Specifies the source region to be used.
26772
26773 dest_region_return
26774
26775 Returns the destination region.
26776
26777 The XUnionRectWithRegion function updates the destination
26778 region from a union of the specified rectangle and the
26779 specified source region.
26780
26781 To subtract two regions, use XSubtractRegion.
26782
26783 XSubtractRegion(Region sra, Region srb, Region dr_return);
26784
26785 sra
26786
26787 srb
26788
26789 Specify the two regions with which you want to perform the
26790 computation.
26791
26792 dr_return
26793
26794 Returns the result of the computation.
26795
26796 The XSubtractRegion function subtracts srb from sra and stores
26797 the results in dr_return.
26798
26799 To calculate the difference between the union and intersection
26800 of two regions, use XXorRegion.
26801
26802 XXorRegion(Region sra, Region srb, Region dr_return);
26803
26804 sra
26805
26806 srb
26807
26808 Specify the two regions with which you want to perform the
26809 computation.
26810
26811 dr_return
26812
26813 Returns the result of the computation.
26814
26815Determining if Regions Are Empty or Equal
26816
26817 To determine if the specified region is empty, use
26818 XEmptyRegion.
26819
26820 Bool XEmptyRegion(Region r);
26821
26822 r
26823
26824 Specifies the region.
26825
26826 The XEmptyRegion function returns True if the region is empty.
26827
26828 To determine if two regions have the same offset, size, and
26829 shape, use XEqualRegion.
26830
26831 Bool XEqualRegion(Region r1, Region r2);
26832
26833 r1
26834
26835 r2
26836
26837 Specify the two regions.
26838
26839 The XEqualRegion function returns True if the two regions have
26840 the same offset, size, and shape.
26841
26842Locating a Point or a Rectangle in a Region
26843
26844 To determine if a specified point resides in a specified
26845 region, use XPointInRegion.
26846
26847 Bool XPointInRegion(Region r, int x, int y);
26848
26849 r
26850
26851 Specifies the region.
26852
26853 x
26854
26855 y
26856
26857 Specify the x and y coordinates, which define the point.
26858
26859 The XPointInRegion function returns True if the point (x, y) is
26860 contained in the region r.
26861
26862 To determine if a specified rectangle is inside a region, use
26863 XRectInRegion.
26864
26865 int XRectInRegion(Region r, int x, int y, unsigned int width,
26866 unsigned int height);
26867
26868 r
26869
26870 Specifies the region.
26871
26872 x
26873
26874 y
26875
26876 Specify the x and y coordinates, which define the coordinates
26877 of the upper-left corner of the rectangle.
26878
26879 width
26880
26881 height
26882
26883 Specify the width and height, which define the rectangle.
26884
26885 The XRectInRegion function returns RectangleIn if the rectangle
26886 is entirely in the specified region, RectangleOut if the
26887 rectangle is entirely out of the specified region, and
26888 RectanglePart if the rectangle is partially in the specified
26889 region.
26890
26891Using Cut Buffers
26892
26893 Xlib provides functions to manipulate cut buffers, a very
26894 simple form of cut-and-paste inter-client communication.
26895 Selections are a much more powerful and useful mechanism for
26896 interchanging data between client (see section 4.5) and
26897 generally should be used instead of cut buffers.
26898
26899 Cut buffers are implemented as properties on the first root
26900 window of the display. The buffers can only contain text, in
26901 the STRING encoding. The text encoding is not changed by Xlib
26902 when fetching or storing. Eight buffers are provided and can be
26903 accessed as a ring or as explicit buffers (numbered 0 through
26904 7).
26905
26906 To store data in cut buffer 0, use XStoreBytes.
26907
26908 XStoreBytes(Display *display, char *bytes, int nbytes);
26909
26910 display
26911
26912 Specifies the connection to the X server.
26913
26914 bytes
26915
26916 Specifies the bytes, which are not necessarily ASCII or
26917 null-terminated.
26918
26919 nbytes
26920
26921 Specifies the number of bytes to be stored.
26922
26923 The data can have embedded null characters and need not be
26924 null-terminated. The cut buffer's contents can be retrieved
26925 later by any client calling XFetchBytes.
26926
26927 XStoreBytes can generate a BadAlloc error.
26928
26929 To store data in a specified cut buffer, use XStoreBuffer.
26930
26931 XStoreBuffer(Display *display, char *bytes, int nbytes, int
26932 buffer);
26933
26934 display
26935
26936 Specifies the connection to the X server.
26937
26938 bytes
26939
26940 Specifies the bytes, which are not necessarily ASCII or
26941 null-terminated.
26942
26943 nbytes
26944
26945 Specifies the number of bytes to be stored.
26946
26947 buffer
26948
26949 Specifies the buffer in which you want to store the bytes.
26950
26951 If an invalid buffer is specified, the call has no effect. The
26952 data can have embedded null characters and need not be
26953 null-terminated.
26954
26955 XStoreBuffer can generate a BadAlloc error.
26956
26957 To return data from cut buffer 0, use XFetchBytes.
26958
26959 char *XFetchBytes(Display *display, int *nbytes_return);
26960
26961 display
26962
26963 Specifies the connection to the X server.
26964
26965 nbytes_return
26966
26967 Returns the number of bytes in the buffer.
26968
26969 The XFetchBytes function returns the number of bytes in the
26970 nbytes_return argument, if the buffer contains data. Otherwise,
26971 the function returns NULL and sets nbytes to 0. The appropriate
26972 amount of storage is allocated and the pointer returned. The
26973 client must free this storage when finished with it by calling
26974 XFree.
26975
26976 To return data from a specified cut buffer, use XFetchBuffer.
26977
26978 char *XFetchBuffer(Display *display, int *nbytes_return, int
26979 buffer);
26980
26981 display
26982
26983 Specifies the connection to the X server.
26984
26985 nbytes_return
26986
26987 Returns the number of bytes in the buffer.
26988
26989 buffer
26990
26991 Specifies the buffer from which you want the stored data
26992 returned.
26993
26994 The XFetchBuffer function returns zero to the nbytes_return
26995 argument if there is no data in the buffer or if an invalid
26996 buffer is specified.
26997
26998 To rotate the cut buffers, use XRotateBuffers.
26999
27000 XRotateBuffers(Display *display, int rotate);
27001
27002 display
27003
27004 Specifies the connection to the X server.
27005
27006 rotate
27007
27008 Specifies how much to rotate the cut buffers.
27009
27010 The XRotateBuffers function rotates the cut buffers, such that
27011 buffer 0 becomes buffer n, buffer 1 becomes n + 1 mod 8, and so
27012 on. This cut buffer numbering is global to the display. Note
27013 that XRotateBuffers generates BadMatch errors if any of the
27014 eight buffers have not been created.
27015
27016Determining the Appropriate Visual Type
27017
27018 A single display can support multiple screens. Each screen can
27019 have several different visual types supported at different
27020 depths. You can use the functions described in this section to
27021 determine which visual to use for your application.
27022
27023 The functions in this section use the visual information masks
27024 and the XVisualInfo structure, which is defined in
27025 <X11/Xutil.h> and contains:
27026
27027/* Visual information mask bits */
27028
27029
27030#define VisualNoMask 0x0
27031#define VisualIDMask 0x1
27032#define VisualScreenMask 0x2
27033#define VisualDepthMask 0x4
27034#define VisualClassMask 0x8
27035#define VisualRedMaskMask 0x10
27036#define VisualGreenMaskMask 0x20
27037#define VisualBlueMaskMask 0x40
27038#define VisualColormapSizeMask 0x80
27039#define VisualBitsPerRGBMask 0x100
27040#define VisualAllMask 0x1FF
27041
27042
27043
27044
27045/* Values */
27046
27047typedef struct {
27048 Visual *visual;
27049 VisualID visualid;
27050 int screen;
27051 unsigned int depth;
27052 int class;
27053 unsigned long red_mask;
27054 unsigned long green_mask;
27055 unsigned long blue_mask;
27056 int colormap_size;
27057 int bits_per_rgb;
27058} XVisualInfo;
27059
27060 To obtain a list of visual information structures that match a
27061 specified template, use XGetVisualInfo.
27062
27063 XVisualInfo *XGetVisualInfo(Display *display, long vinfo_mask,
27064 XVisualInfo *vinfo_template, int *nitems_return);
27065
27066 display
27067
27068 Specifies the connection to the X server.
27069
27070 vinfo_mask
27071
27072 Specifies the visual mask value.
27073
27074 vinfo_template
27075
27076 Specifies the visual attributes that are to be used in matching
27077 the visual structures.
27078
27079 nitems_return
27080
27081 Returns the number of matching visual structures.
27082
27083 The XGetVisualInfo function returns a list of visual structures
27084 that have attributes equal to the attributes specified by
27085 vinfo_template. If no visual structures match the template
27086 using the specified vinfo_mask, XGetVisualInfo returns a NULL.
27087 To free the data returned by this function, use XFree.
27088
27089 To obtain the visual information that matches the specified
27090 depth and class of the screen, use XMatchVisualInfo.
27091
27092 Status XMatchVisualInfo(Display *display, int screen, int
27093 depth, int class, XVisualInfo *vinfo_return);
27094
27095 display
27096
27097 Specifies the connection to the X server.
27098
27099 screen
27100
27101 Specifies the screen.
27102
27103 depth
27104
27105 Specifies the depth of the screen.
27106
27107 class
27108
27109 Specifies the class of the screen.
27110
27111 vinfo_return
27112
27113 Returns the matched visual information.
27114
27115 The XMatchVisualInfo function returns the visual information
27116 for a visual that matches the specified depth and class for a
27117 screen. Because multiple visuals that match the specified depth
27118 and class can exist, the exact visual chosen is undefined. If a
27119 visual is found, XMatchVisualInfo returns nonzero and the
27120 information on the visual to vinfo_return. Otherwise, when a
27121 visual is not found, XMatchVisualInfo returns zero.
27122
27123Manipulating Images
27124
27125 Xlib provides several functions that perform basic operations
27126 on images. All operations on images are defined using an XImage
27127 structure, as defined in <X11/Xlib.h>. Because the number of
27128 different types of image formats can be very large, this hides
27129 details of image storage properly from applications.
27130
27131 This section describes the functions for generic operations on
27132 images. Manufacturers can provide very fast implementations of
27133 these for the formats frequently encountered on their hardware.
27134 These functions are neither sufficient nor desirable to use for
27135 general image processing. Rather, they are here to provide
27136 minimal functions on screen format images. The basic operations
27137 for getting and putting images are XGetImage and XPutImage.
27138
27139 Note that no functions have been defined, as yet, to read and
27140 write images to and from disk files.
27141
27142 The XImage structure describes an image as it exists in the
27143 client's memory. The user can request that some of the members
27144 such as height, width, and xoffset be changed when the image is
27145 sent to the server. Note that bytes_per_line in concert with
27146 offset can be used to extract a subset of the image. Other
27147 members (for example, byte order, bitmap_unit, and so forth)
27148 are characteristics of both the image and the server. If these
27149 members differ between the image and the server, XPutImage
27150 makes the appropriate conversions. The first byte of the first
27151 line of plane n must be located at the address (data + (n *
27152 height * bytes_per_line)). For a description of the XImage
27153 structure, see section 8.7.
27154
27155 To allocate an XImage structure and initialize it with image
27156 format values from a display, use XCreateImage.
27157
27158 XImage *XCreateImage(Display *display, Visual *visual, unsigned
27159 int depth, int format, int offset, char *data, unsigned int
27160 width, unsigned int height, int bitmap_pad, int
27161 bytes_per_line);
27162
27163 display
27164
27165 Specifies the connection to the X server.
27166
27167 visual
27168
27169 Specifies the Visual structure.
27170
27171 depth
27172
27173 Specifies the depth of the image.
27174
27175 format
27176
27177 Specifies the format for the image. You can pass XYBitmap,
27178 XYPixmap, or ZPixmap.
27179
27180 offset
27181
27182 Specifies the number of pixels to ignore at the beginning of
27183 the scanline.
27184
27185 data
27186
27187 Specifies the image data.
27188
27189 width
27190
27191 Specifies the width of the image, in pixels.
27192
27193 height
27194
27195 Specifies the height of the image, in pixels.
27196
27197 bitmap_pad
27198
27199 Specifies the quantum of a scanline (8, 16, or 32). In other
27200 words, the start of one scanline is separated in client memory
27201 from the start of the next scanline by an integer multiple of
27202 this many bits.
27203
27204 bytes_per_line
27205
27206 Specifies the number of bytes in the client image between the
27207 start of one scanline and the start of the next.
27208
27209 The XCreateImage function allocates the memory needed for an
27210 XImage structure for the specified display but does not
27211 allocate space for the image itself. Rather, it initializes the
27212 structure byte-order, bit-order, and bitmap-unit values from
27213 the display and returns a pointer to the XImage structure. The
27214 red, green, and blue mask values are defined for Z format
27215 images only and are derived from the Visual structure passed
27216 in. Other values also are passed in. The offset permits the
27217 rapid displaying of the image without requiring each scanline
27218 to be shifted into position. If you pass a zero value in
27219 bytes_per_line, Xlib assumes that the scanlines are contiguous
27220 in memory and calculates the value of bytes_per_line itself.
27221
27222 Note that when the image is created using XCreateImage,
27223 XGetImage, or XSubImage, the destroy procedure that the
27224 XDestroyImage function calls frees both the image structure and
27225 the data pointed to by the image structure.
27226
27227 The basic functions used to get a pixel, set a pixel, create a
27228 subimage, and add a constant value to an image are defined in
27229 the image object. The functions in this section are really
27230 macro invocations of the functions in the image object and are
27231 defined in <X11/Xutil.h>.
27232
27233 To obtain a pixel value in an image, use XGetPixel.
27234
27235 unsigned long XGetPixel(XImage *ximage, int x, int y);
27236
27237 ximage
27238
27239 Specifies the image.
27240
27241 x
27242
27243 y
27244
27245 Specify the x and y coordinates.
27246
27247 The XGetPixel function returns the specified pixel from the
27248 named image. The pixel value is returned in normalized format
27249 (that is, the least significant byte of the long is the least
27250 significant byte of the pixel). The image must contain the x
27251 and y coordinates.
27252
27253 To set a pixel value in an image, use XPutPixel.
27254
27255 XPutPixel(XImage *ximage, int x, int y, unsigned long pixel);
27256
27257 ximage
27258
27259 Specifies the image.
27260
27261 x
27262
27263 y
27264
27265 Specify the x and y coordinates.
27266
27267 pixel
27268
27269 Specifies the new pixel value.
27270
27271 The XPutPixel function overwrites the pixel in the named image
27272 with the specified pixel value. The input pixel value must be
27273 in normalized format (that is, the least significant byte of
27274 the long is the least significant byte of the pixel). The image
27275 must contain the x and y coordinates.
27276
27277 To create a subimage, use XSubImage.
27278
27279 XImage *XSubImage(XImage *ximage, int x, int y, unsigned int
27280 subimage_width, unsigned int subimage_height);
27281
27282 ximage
27283
27284 Specifies the image.
27285
27286 x
27287
27288 y
27289
27290 Specify the x and y coordinates.
27291
27292 subimage_width
27293
27294 Specifies the width of the new subimage, in pixels.
27295
27296 subimage_height
27297
27298 Specifies the height of the new subimage, in pixels.
27299
27300 The XSubImage function creates a new image that is a subsection
27301 of an existing one. It allocates the memory necessary for the
27302 new XImage structure and returns a pointer to the new image.
27303 The data is copied from the source image, and the image must
27304 contain the rectangle defined by x, y, subimage_width, and
27305 subimage_height.
27306
27307 To increment each pixel in an image by a constant value, use
27308 XAddPixel.
27309
27310 XAddPixel(XImage *ximage, long value);
27311
27312 ximage
27313
27314 Specifies the image.
27315
27316 value
27317
27318 Specifies the constant value that is to be added.
27319
27320 The XAddPixel function adds a constant value to every pixel in
27321 an image. It is useful when you have a base pixel value from
27322 allocating color resources and need to manipulate the image to
27323 that form.
27324
27325 To deallocate the memory allocated in a previous call to
27326 XCreateImage, use XDestroyImage.
27327
27328 XDestroyImage(XImage *ximage);
27329
27330 ximage
27331
27332 Specifies the image.
27333
27334 The XDestroyImage function deallocates the memory associated
27335 with the XImage structure.
27336
27337 Note that when the image is created using XCreateImage,
27338 XGetImage, or XSubImage, the destroy procedure that this macro
27339 calls frees both the image structure and the data pointed to by
27340 the image structure.
27341
27342Manipulating Bitmaps
27343
27344 Xlib provides functions that you can use to read a bitmap from
27345 a file, save a bitmap to a file, or create a bitmap. This
27346 section describes those functions that transfer bitmaps to and
27347 from the client's file system, thus allowing their reuse in a
27348 later connection (for example, from an entirely different
27349 client or to a different display or server).
27350
27351 The X version 11 bitmap file format is:
27352
27353#define name_width width
27354#define name_height height
27355#define name_x_hot x
27356#define name_y_hot y
27357static unsigned char name_bits[] = { 0xNN,... }
27358
27359 The lines for the variables ending with _x_hot and _y_hot
27360 suffixes are optional because they are present only if a
27361 hotspot has been defined for this bitmap. The lines for the
27362 other variables are required. The word ``unsigned'' is
27363 optional; that is, the type of the _bits array can be ``char''
27364 or ``unsigned char''. The _bits array must be large enough to
27365 contain the size bitmap. The bitmap unit is 8.
27366
27367 To read a bitmap from a file and store it in a pixmap, use
27368 XReadBitmapFile.
27369
27370 int XReadBitmapFile(Display *display, Drawable d, char
27371 *filename, unsigned int *width_return, unsigned int
27372 *height_return, Pixmap *bitmap_return, int *x_hot_return, int
27373 *y_hot_return);
27374
27375 display
27376
27377 Specifies the connection to the X server.
27378
27379 d
27380
27381 Specifies the drawable that indicates the screen.
27382
27383 filename
27384
27385 Specifies the file name to use. The format of the file name is
27386 operating-system dependent.
27387
27388 width_return
27389
27390 height_return
27391
27392 Return the width and height values of the read in bitmap file.
27393
27394 bitmap_return
27395
27396 Returns the bitmap that is created.
27397
27398 x_hot_return
27399
27400 y_hot_return
27401
27402 Return the hotspot coordinates.
27403
27404 The XReadBitmapFile function reads in a file containing a
27405 bitmap. The file is parsed in the encoding of the current
27406 locale. The ability to read other than the standard format is
27407 implementation-dependent. If the file cannot be opened,
27408 XReadBitmapFile returns BitmapOpenFailed. If the file can be
27409 opened but does not contain valid bitmap data, it returns
27410 BitmapFileInvalid. If insufficient working storage is
27411 allocated, it returns BitmapNoMemory. If the file is readable
27412 and valid, it returns BitmapSuccess.
27413
27414 XReadBitmapFile returns the bitmap's height and width, as read
27415 from the file, to width_return and height_return. It then
27416 creates a pixmap of the appropriate size, reads the bitmap data
27417 from the file into the pixmap, and assigns the pixmap to the
27418 caller's variable bitmap. The caller must free the bitmap using
27419 XFreePixmap when finished. If name_x_hot and name_y_hot exist,
27420 XReadBitmapFile returns them to x_hot_return and y_hot_return;
27421 otherwise, it returns -1,-1.
27422
27423 XReadBitmapFile can generate BadAlloc, BadDrawable, and BadGC
27424 errors.
27425
27426 To read a bitmap from a file and return it as data, use
27427 XReadBitmapFileData.
27428
27429 int XReadBitmapFileData(char *filename, unsigned int
27430 *width_return, unsigned int *height_return, unsignedchar
27431 *data_return, int *x_hot_return, int *y_hot_return);
27432
27433 filename
27434
27435 Specifies the file name to use. The format of the file name is
27436 operating-system dependent.
27437
27438 width_return
27439
27440 height_return
27441
27442 Return the width and height values of the read in bitmap file.
27443
27444 data_return
27445
27446 Returns the bitmap data.
27447
27448 x_hot_return
27449
27450 y_hot_return
27451
27452 Return the hotspot coordinates.
27453
27454 The XReadBitmapFileData function reads in a file containing a
27455 bitmap, in the same manner as XReadBitmapFile, but returns the
27456 data directly rather than creating a pixmap in the server. The
27457 bitmap data is returned in data_return; the client must free
27458 this storage when finished with it by calling XFree. The status
27459 and other return values are the same as for XReadBitmapFile.
27460
27461 To write out a bitmap from a pixmap to a file, use
27462 XWriteBitmapFile.
27463
27464 int XWriteBitmapFile(Display *display, char *filename, Pixmap
27465 bitmap, unsigned int width, unsigned int height, int x_hot, int
27466 y_hot);
27467
27468 display
27469
27470 Specifies the connection to the X server.
27471
27472 filename
27473
27474 Specifies the file name to use. The format of the file name is
27475 operating-system dependent.
27476
27477 bitmap
27478
27479 Specifies the bitmap.
27480
27481 width
27482
27483 height
27484
27485 Specify the width and height.
27486
27487 x_hot
27488
27489 y_hot
27490
27491 Specify where to place the hotspot coordinates (or -1,-1 if
27492 none are present) in the file.
27493
27494 The XWriteBitmapFile function writes a bitmap out to a file in
27495 the X Version 11 format. The name used in the output file is
27496 derived from the file name by deleting the directory prefix.
27497 The file is written in the encoding of the current locale. If
27498 the file cannot be opened for writing, it returns
27499 BitmapOpenFailed. If insufficient memory is allocated,
27500 XWriteBitmapFile returns BitmapNoMemory; otherwise, on no
27501 error, it returns BitmapSuccess. If x_hot and y_hot are not -1,
27502 -1, XWriteBitmapFile writes them out as the hotspot coordinates
27503 for the bitmap.
27504
27505 XWriteBitmapFile can generate BadDrawable and BadMatch errors.
27506
27507 To create a pixmap and then store bitmap-format data into it,
27508 use XCreatePixmapFromBitmapData.
27509
27510 Pixmap XCreatePixmapFromBitmapData(Display *display, Drawable
27511 d, char *data, unsigned int width, unsigned int height,
27512 unsigned long fg, unsigned long bg, unsigned int depth);
27513
27514 display
27515
27516 Specifies the connection to the X server.
27517
27518 d
27519
27520 Specifies the drawable that indicates the screen.
27521
27522 data
27523
27524 Specifies the data in bitmap format.
27525
27526 width
27527
27528 height
27529
27530 Specify the width and height.
27531
27532 fg
27533
27534 bg
27535
27536 Specify the foreground and background pixel values to use.
27537
27538 depth
27539
27540 Specifies the depth of the pixmap.
27541
27542 The XCreatePixmapFromBitmapData function creates a pixmap of
27543 the given depth and then does a bitmap-format XPutImage of the
27544 data into it. The depth must be supported by the screen of the
27545 specified drawable, or a BadMatch error results.
27546
27547 XCreatePixmapFromBitmapData can generate BadAlloc, BadDrawable,
27548 BadGC, and BadValue errors.
27549
27550 To include a bitmap written out by XWriteBitmapFile in a
27551 program directly, as opposed to reading it in every time at run
27552 time, use XCreateBitmapFromData.
27553
27554 Pixmap XCreateBitmapFromData(Display *display, Drawable d, char
27555 *data, unsigned int width, unsigned int height);
27556
27557 display
27558
27559 Specifies the connection to the X server.
27560
27561 d
27562
27563 Specifies the drawable that indicates the screen.
27564
27565 data
27566
27567 Specifies the location of the bitmap data.
27568
27569 width
27570
27571 height
27572
27573 Specify the width and height.
27574
27575 The XCreateBitmapFromData function allows you to include in
27576 your C program (using #include) a bitmap file that was written
27577 out by XWriteBitmapFile (X version 11 format only) without
27578 reading in the bitmap file. The following example creates a
27579 gray bitmap:
27580
27581#include "gray.bitmap"
27582
27583Pixmap bitmap;
27584bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, g
27585ray_height);
27586
27587 If insufficient working storage was allocated,
27588 XCreateBitmapFromData returns None. It is your responsibility
27589 to free the bitmap using XFreePixmap when finished.
27590
27591 XCreateBitmapFromData can generate BadAlloc and BadGC errors.
27592
27593Using the Context Manager
27594
27595 The context manager provides a way of associating data with an
27596 X resource ID (mostly typically a window) in your program. Note
27597 that this is local to your program; the data is not stored in
27598 the server on a property list. Any amount of data in any number
27599 of pieces can be associated with a resource ID, and each piece
27600 of data has a type associated with it. The context manager
27601 requires knowledge of the resource ID and type to store or
27602 retrieve data.
27603
27604 Essentially, the context manager can be viewed as a
27605 two-dimensional, sparse array: one dimension is subscripted by
27606 the X resource ID and the other by a context type field. Each
27607 entry in the array contains a pointer to the data. Xlib
27608 provides context management functions with which you can save
27609 data values, get data values, delete entries, and create a
27610 unique context type. The symbols used are in <X11/Xutil.h>.
27611
27612 To save a data value that corresponds to a resource ID and
27613 context type, use XSaveContext.
27614
27615 int XSaveContext(Display *display, XID rid, XContext context,
27616 XPointer data);
27617
27618 display
27619
27620 Specifies the connection to the X server.
27621
27622 rid
27623
27624 Specifies the resource ID with which the data is associated.
27625
27626 context
27627
27628 Specifies the context type to which the data belongs.
27629
27630 data
27631
27632 Specifies the data to be associated with the window and type.
27633
27634 If an entry with the specified resource ID and type already
27635 exists, XSaveContext overrides it with the specified context.
27636 The XSaveContext function returns a nonzero error code if an
27637 error has occurred and zero otherwise. Possible errors are
27638 XCNOMEM (out of memory).
27639
27640 To get the data associated with a resource ID and type, use
27641 XFindContext.
27642
27643 int XFindContext(Display *display, XID rid, XContext context,
27644 XPointer *data_return);
27645
27646 display
27647
27648 Specifies the connection to the X server.
27649
27650 rid
27651
27652 Specifies the resource ID with which the data is associated.
27653
27654 context
27655
27656 Specifies the context type to which the data belongs.
27657
27658 data_return
27659
27660 Returns the data.
27661
27662 Because it is a return value, the data is a pointer. The
27663 XFindContext function returns a nonzero error code if an error
27664 has occurred and zero otherwise. Possible errors are XCNOENT
27665 (context-not-found).
27666
27667 To delete an entry for a given resource ID and type, use
27668 XDeleteContext.
27669
27670 int XDeleteContext(Display *display, XID rid, XContext
27671 context);
27672
27673 display
27674
27675 Specifies the connection to the X server.
27676
27677 rid
27678
27679 Specifies the resource ID with which the data is associated.
27680
27681 context
27682
27683 Specifies the context type to which the data belongs.
27684
27685 The XDeleteContext function deletes the entry for the given
27686 resource ID and type from the data structure. This function
27687 returns the same error codes that XFindContext returns if
27688 called with the same arguments. XDeleteContext does not free
27689 the data whose address was saved.
27690
27691 To create a unique context type that may be used in subsequent
27692 calls to XSaveContext and XFindContext, use XUniqueContext.
27693
27694 XContext XUniqueContext(void);
27695
27696Appendix A. Xlib Functions and Protocol Requests
27697
27698 This appendix provides two tables that relate to Xlib functions
27699 and the X protocol. The following table lists each Xlib
27700 function (in alphabetical order) and the corresponding protocol
27701 request that it generates.
27702
27703 Table A.1. Protocol requests made by each Xlib function
27704 Xlib Function Protocol Request
27705 XActivateScreenSaver ForceScreenSaver
27706 XAddHost ChangeHosts
27707 XAddHosts ChangeHosts
27708 XAddToSaveSet ChangeSaveSet
27709 XAllocColor AllocColor
27710 XAllocColorCells AllocColorCells
27711 XAllocColorPlanes AllocColorPlanes
27712 XAllocNamedColor AllocNamedColor
27713 XAllowEvents AllowEvents
27714 XAutoRepeatOff ChangeKeyboardControl
27715 XAutoRepeatOn ChangeKeyboardControl
27716 XBell Bell
27717 XChangeActivePointerGrab ChangeActivePointerGrab
27718 XChangeGC ChangeGC
27719 XChangeKeyboardControl ChangeKeyboardControl
27720 XChangeKeyboardMapping ChangeKeyboardMapping
27721 XChangePointerControl ChangePointerControl
27722 XChangeProperty ChangeProperty
27723 XChangeSaveSet ChangeSaveSet
27724 XChangeWindowAttributes ChangeWindowAttributes
27725 XCirculateSubwindows CirculateWindow
27726 XCirculateSubwindowsDown CirculateWindow
27727 XCirculateSubwindowsUp CirculateWindow
27728 XClearArea ClearArea
27729 XClearWindow ClearArea
27730 XConfigureWindow ConfigureWindow
27731 XConvertSelection ConvertSelection
27732 XCopyArea CopyArea
27733 XCopyColormapAndFree CopyColormapAndFree
27734 XCopyGC CopyGC
27735 XCopyPlane CopyPlane
27736 XCreateBitmapFromData CreateGC
27737 CreatePixmap
27738 FreeGC
27739 PutImage
27740 XCreateColormap CreateColormap
27741 XCreateFontCursor CreateGlyphCursor
27742 XCreateGC CreateGC
27743 XCreateGlyphCursor CreateGlyphCursor
27744 XCreatePixmap CreatePixmap
27745 XCreatePixmapCursor CreateCursor
27746 XCreatePixmapFromData CreateGC
27747 CreatePixmap
27748 FreeGC
27749 PutImage
27750 XCreateSimpleWindow CreateWindow
27751 XCreateWindow CreateWindow
27752 XDefineCursor ChangeWindowAttributes
27753 XDeleteProperty DeleteProperty
27754 XDestroySubwindows DestroySubwindows
27755 XDestroyWindow DestroyWindow
27756 XDisableAccessControl SetAccessControl
27757 XDrawArc PolyArc
27758 XDrawArcs PolyArc
27759 XDrawImageString ImageText8
27760 XDrawImageString16 ImageText16
27761 XDrawLine PolySegment
27762 XDrawLines PolyLine
27763 XDrawPoint PolyPoint
27764 XDrawPoints PolyPoint
27765 XDrawRectangle PolyRectangle
27766 XDrawRectangles PolyRectangle
27767 XDrawSegments PolySegment
27768 XDrawString PolyText8
27769 XDrawString16 PolyText16
27770 XDrawText PolyText8
27771 XDrawText16 PolyText16
27772 XEnableAccessControl SetAccessControl
27773 XFetchBytes GetProperty
27774 XFetchName GetProperty
27775 XFillArc PolyFillArc
27776 XFillArcs PolyFillArc
27777 XFillPolygon FillPoly
27778 XFillRectangle PolyFillRectangle
27779 XFillRectangles PolyFillRectangle
27780 XForceScreenSaver ForceScreenSaver
27781 XFreeColormap FreeColormap
27782 XFreeColors FreeColors
27783 XFreeCursor FreeCursor
27784 XFreeFont CloseFont
27785 XFreeGC FreeGC
27786 XFreePixmap FreePixmap
27787 XGetAtomName GetAtomName
27788 XGetClassHint GetProperty
27789 XGetFontPath GetFontPath
27790 XGetGeometry GetGeometry
27791 XGetIconName GetProperty
27792 XGetIconSizes GetProperty
27793 XGetImage GetImage
27794 XGetInputFocus GetInputFocus
27795 XGetKeyboardControl GetKeyboardControl
27796 XGetKeyboardMapping GetKeyboardMapping
27797 XGetModifierMapping GetModifierMapping
27798 GetMotionEvents
27799 XGetNormalHints GetProperty
27800 XGetPointerControl GetPointerControl
27801 XGetPointerMapping GetPointerMapping
27802 XGetRGBColormaps GetProperty
27803 XGetScreenSaver GetScreenSaver
27804 XGetSelectionOwner GetSelectionOwner
27805 XGetSizeHints GetProperty
27806 XGetTextProperty GetProperty
27807 XGetTransientForHint GetProperty
27808 XGetWMClientMachine GetProperty
27809 XGetWMColormapWindows GetProperty
27810 InternAtom
27811 XGetWMHints GetProperty
27812 XGetWMIconName GetProperty
27813 XGetWMName GetProperty
27814 XGetWMNormalHints GetProperty
27815 XGetWMProtocols GetProperty
27816 InternAtom
27817 XGetWMSizeHints GetProperty
27818 XGetWindowAttributes GetWindowAttributes
27819 GetGeometry
27820 XGetWindowProperty GetProperty
27821 XGetZoomHints GetProperty
27822 XGrabButton GrabButton
27823 XGrabKey GrabKey
27824 XGrabKeyboard GrabKeyboard
27825 XGrabPointer GrabPointer
27826 XGrabServer GrabServer
27827 XIconifyWindow InternAtom
27828 SendEvent
27829 XInitExtension QueryExtension
27830 XInstallColormap InstallColormap
27831 XInternAtom InternAtom
27832 XKillClient KillClient
27833 XListExtensions ListExtensions
27834 XListFonts ListFonts
27835 XListFontsWithInfo ListFontsWithInfo
27836 XListHosts ListHosts
27837 XListInstalledColormaps ListInstalledColormaps
27838 XListProperties ListProperties
27839 XLoadFont OpenFont
27840 XLoadQueryFont OpenFont
27841 QueryFont
27842 XLookupColor LookupColor
27843 XLowerWindow ConfigureWindow
27844 XMapRaised ConfigureWindow
27845 MapWindow
27846 XMapSubwindows MapSubwindows
27847 XMapWindow MapWindow
27848 XMoveResizeWindow ConfigureWindow
27849 XMoveWindow ConfigureWindow
27850 XNoOp NoOperation
27851 XOpenDisplay CreateGC
27852 XParseColor LookupColor
27853 XPutImage PutImage
27854 XQueryBestCursor QueryBestSize
27855 XQueryBestSize QueryBestSize
27856 XQueryBestStipple QueryBestSize
27857 XQueryBestTile QueryBestSize
27858 XQueryColor QueryColors
27859 XQueryColors QueryColors
27860 XQueryExtension QueryExtension
27861 XQueryFont QueryFont
27862 XQueryKeymap QueryKeymap
27863 XQueryPointer QueryPointer
27864 XQueryTextExtents QueryTextExtents
27865 XQueryTextExtents16 QueryTextExtents
27866 XQueryTree QueryTree
27867 XRaiseWindow ConfigureWindow
27868 XReadBitmapFile CreateGC
27869 CreatePixmap
27870 FreeGC
27871 PutImage
27872 XRecolorCursor RecolorCursor
27873 XReconfigureWMWindow ConfigureWindow
27874 SendEvent
27875 XRemoveFromSaveSet ChangeSaveSet
27876 XRemoveHost ChangeHosts
27877 XRemoveHosts ChangeHosts
27878 XReparentWindow ReparentWindow
27879 XResetScreenSaver ForceScreenSaver
27880 XResizeWindow ConfigureWindow
27881 XRestackWindows ConfigureWindow
27882 XRotateBuffers RotateProperties
27883 XRotateWindowProperties RotateProperties
27884 XSelectInput ChangeWindowAttributes
27885 XSendEvent SendEvent
27886 XSetAccessControl SetAccessControl
27887 XSetArcMode ChangeGC
27888 XSetBackground ChangeGC
27889 XSetClassHint ChangeProperty
27890 XSetClipMask ChangeGC
27891 XSetClipOrigin ChangeGC
27892 XSetClipRectangles SetClipRectangles
27893 XSetCloseDownMode SetCloseDownMode
27894 XSetCommand ChangeProperty
27895 XSetDashes SetDashes
27896 XSetFillRule ChangeGC
27897 XSetFillStyle ChangeGC
27898 XSetFont ChangeGC
27899 XSetFontPath SetFontPath
27900 XSetForeground ChangeGC
27901 XSetFunction ChangeGC
27902 XSetGraphicsExposures ChangeGC
27903 XSetIconName ChangeProperty
27904 XSetIconSizes ChangeProperty
27905 XSetInputFocus SetInputFocus
27906 XSetLineAttributes ChangeGC
27907 XSetModifierMapping SetModifierMapping
27908 XSetNormalHints ChangeProperty
27909 XSetPlaneMask ChangeGC
27910 XSetPointerMapping SetPointerMapping
27911 XSetRGBColormaps ChangeProperty
27912 XSetScreenSaver SetScreenSaver
27913 XSetSelectionOwner SetSelectionOwner
27914 XSetSizeHints ChangeProperty
27915 XSetStandardProperties ChangeProperty
27916 XSetState ChangeGC
27917 XSetStipple ChangeGC
27918 XSetSubwindowMode ChangeGC
27919 XSetTextProperty ChangeProperty
27920 XSetTile ChangeGC
27921 XSetTransientForHint ChangeProperty
27922 XSetTSOrigin ChangeGC
27923 XSetWMClientMachine ChangeProperty
27924 XSetWMColormapWindows ChangeProperty
27925 InternAtom
27926 XSetWMHints ChangeProperty
27927 XSetWMIconName ChangeProperty
27928 XSetWMName ChangeProperty
27929 XSetWMNormalHints ChangeProperty
27930 XSetWMProperties ChangeProperty
27931 XSetWMProtocols ChangeProperty
27932 InternAtom
27933 XSetWMSizeHints ChangeProperty
27934 XSetWindowBackground ChangeWindowAttributes
27935 XSetWindowBackgroundPixmap ChangeWindowAttributes
27936 XSetWindowBorder ChangeWindowAttributes
27937 XSetWindowBorderPixmap ChangeWindowAttributes
27938 XSetWindowBorderWidth ConfigureWindow
27939 XSetWindowColormap ChangeWindowAttributes
27940 XSetZoomHints ChangeProperty
27941 XStoreBuffer ChangeProperty
27942 XStoreBytes ChangeProperty
27943 XStoreColor StoreColors
27944 XStoreColors StoreColors
27945 XStoreName ChangeProperty
27946 XStoreNamedColor StoreNamedColor
27947 XSync GetInputFocus
27948 XSynchronize GetInputFocus
27949 XTranslateCoordinates TranslateCoordinates
27950 XUndefineCursor ChangeWindowAttributes
27951 XUngrabButton UngrabButton
27952 XUngrabKey UngrabKey
27953 XUngrabKeyboard UngrabKeyboard
27954 XUngrabPointer UngrabPointer
27955 XUngrabServer UngrabServer
27956 XUninstallColormap UninstallColormap
27957 XUnloadFont CloseFont
27958 XUnmapSubwindows UnmapSubwindows
27959 XUnmapWindow UnmapWindow
27960 XWarpPointer WarpPointer
27961 XWithdrawWindow SendEvent
27962 UnmapWindow
27963
27964 The following table lists each X protocol request (in
27965 alphabetical order) and the Xlib functions that reference it.
27966
27967 Table A.2. Xlib functions which use each Protocol Request
27968 Protocol Request Xlib Function
27969 AllocColor XAllocColor
27970 AllocColorCells XAllocColorCells
27971 AllocColorPlanes XAllocColorPlanes
27972 AllocNamedColor XAllocNamedColor
27973 AllowEvents XAllowEvents
27974 Bell XBell
27975 ChangeActivePointerGrab XChangeActivePointerGrab
27976 ChangeGC XChangeGC
27977 XSetArcMode
27978 XSetBackground
27979 XSetClipMask
27980 XSetClipOrigin
27981 XSetFillRule
27982 XSetFillStyle
27983 XSetFont
27984 XSetForeground
27985 XSetFunction
27986 XSetGraphicsExposures
27987 XSetLineAttributes
27988 XSetPlaneMask
27989 XSetState
27990 XSetStipple
27991 XSetSubwindowMode
27992 XSetTile
27993 XSetTSOrigin
27994 ChangeHosts XAddHost
27995 XAddHosts
27996 XRemoveHost
27997 XRemoveHosts
27998 ChangeKeyboardControl XAutoRepeatOff
27999 XAutoRepeatOn
28000 XChangeKeyboardControl
28001 ChangeKeyboardMapping XChangeKeyboardMapping
28002 ChangePointerControl XChangePointerControl
28003 ChangeProperty XChangeProperty
28004 XSetClassHint
28005 XSetCommand
28006 XSetIconName
28007 XSetIconSizes
28008 XSetNormalHints
28009 XSetRGBColormaps
28010 XSetSizeHints
28011 XSetStandardProperties
28012 XSetTextProperty
28013 XSetTransientForHint
28014 XSetWMClientMachine
28015 XSetWMColormapWindows
28016 XSetWMHints
28017 XSetWMIconName
28018 XSetWMName
28019 XSetWMNormalHints
28020 XSetWMProperties
28021 XSetWMProtocols
28022 XSetWMSizeHints
28023 XSetZoomHints
28024 XStoreBuffer
28025 XStoreBytes
28026 XStoreName
28027 ChangeSaveSet XAddToSaveSet
28028 XChangeSaveSet
28029 XRemoveFromSaveSet
28030 ChangeWindowAttributes XChangeWindowAttributes
28031 XDefineCursor
28032 XSelectInput
28033 XSetWindowBackground
28034 XSetWindowBackgroundPixmap
28035 XSetWindowBorder
28036 XSetWindowBorderPixmap
28037 XSetWindowColormap
28038 XUndefineCursor
28039 CirculateWindow XCirculateSubwindowsDown
28040 XCirculateSubwindowsUp
28041 XCirculateSubwindows
28042 ClearArea XClearArea
28043 XClearWindow
28044 CloseFont XFreeFont
28045 XUnloadFont
28046 ConfigureWindow XConfigureWindow
28047 XLowerWindow
28048 XMapRaised
28049 XMoveResizeWindow
28050 XMoveWindow
28051 XRaiseWindow
28052 XReconfigureWMWindow
28053 XResizeWindow
28054 XRestackWindows
28055 XSetWindowBorderWidth
28056 ConvertSelection XConvertSelection
28057 CopyArea XCopyArea
28058 CopyColormapAndFree XCopyColormapAndFree
28059 CopyGC XCopyGC
28060 CopyPlane XCopyPlane
28061 CreateColormap XCreateColormap
28062 CreateCursor XCreatePixmapCursor
28063 CreateGC XCreateGC
28064 XCreateBitmapFromData
28065 XCreatePixmapFromData
28066 XOpenDisplay
28067 XReadBitmapFile
28068 CreateGlyphCursor XCreateFontCursor
28069 XCreateGlyphCursor
28070 CreatePixmap XCreatePixmap
28071 XCreateBitmapFromData
28072 XCreatePixmapFromData
28073 XReadBitmapFile
28074 CreateWindow XCreateSimpleWindow
28075 XCreateWindow
28076 DeleteProperty XDeleteProperty
28077 DestroySubwindows XDestroySubwindows
28078 DestroyWindow XDestroyWindow
28079 FillPoly XFillPolygon
28080 ForceScreenSaver XActivateScreenSaver
28081 XForceScreenSaver
28082 XResetScreenSaver
28083 FreeColormap XFreeColormap
28084 FreeColors XFreeColors
28085 FreeCursor XFreeCursor
28086 FreeGC XFreeGC
28087 XCreateBitmapFromData
28088 XCreatePixmapFromData
28089 XReadBitmapFile
28090 FreePixmap XFreePixmap
28091 GetAtomName XGetAtomName
28092 GetFontPath XGetFontPath
28093 GetGeometry XGetGeometry
28094 XGetWindowAttributes
28095 GetImage XGetImage
28096 GetInputFocus XGetInputFocus
28097 XSync
28098 XSynchronize
28099 GetKeyboardControl XGetKeyboardControl
28100 GetKeyboardMapping XGetKeyboardMapping
28101 GetModifierMapping XGetModifierMapping
28102 GetMotionEvents
28103 GetPointerControl XGetPointerControl
28104 GetPointerMapping XGetPointerMapping
28105 GetProperty XFetchBytes
28106 XFetchName
28107 XGetClassHint
28108 XGetIconName
28109 XGetIconSizes
28110 XGetNormalHints
28111 XGetRGBColormaps
28112 XGetSizeHints
28113 XGetTextProperty
28114 XGetTransientForHint
28115 XGetWMClientMachine
28116 XGetWMColormapWindows
28117 XGetWMHints
28118 XGetWMIconName
28119 XGetWMName
28120 XGetWMNormalHints
28121 XGetWMProtocols
28122 XGetWMSizeHints
28123 XGetWindowProperty
28124 XGetZoomHints
28125 GetSelectionOwner XGetSelectionOwner
28126 GetWindowAttributes XGetWindowAttributes
28127 GrabButton XGrabButton
28128 GrabKey XGrabKey
28129 GrabKeyboard XGrabKeyboard
28130 GrabPointer XGrabPointer
28131 GrabServer XGrabServer
28132 ImageText8 XDrawImageString
28133 ImageText16 XDrawImageString16
28134 InstallColormap XInstallColormap
28135 InternAtom XGetWMColormapWindows
28136 XGetWMProtocols
28137 XIconifyWindow
28138 XInternAtom
28139 XSetWMColormapWindows
28140 XSetWMProtocols
28141 KillClient XKillClient
28142 ListExtensions XListExtensions
28143 ListFonts XListFonts
28144 ListFontsWithInfo XListFontsWithInfo
28145 ListHosts XListHosts
28146 ListInstalledColormaps XListInstalledColormaps
28147 ListProperties XListProperties
28148 LookupColor XLookupColor
28149 XParseColor
28150 MapSubwindows XMapSubwindows
28151 MapWindow XMapRaised
28152 XMapWindow
28153 NoOperation XNoOp
28154 OpenFont XLoadFont
28155 XLoadQueryFont
28156 PolyArc XDrawArc
28157 XDrawArcs
28158 PolyFillArc XFillArc
28159 XFillArcs
28160 PolyFillRectangle XFillRectangle
28161 XFillRectangles
28162 PolyLine XDrawLines
28163 PolyPoint XDrawPoint
28164 XDrawPoints
28165 PolyRectangle XDrawRectangle
28166 XDrawRectangles
28167 PolySegment XDrawLine
28168 XDrawSegments
28169 PolyText8 XDrawString
28170 XDrawText
28171 PolyText16 XDrawString16
28172 XDrawText16
28173 PutImage XPutImage
28174 XCreateBitmapFromData
28175 XCreatePixmapFromData
28176 XReadBitmapFile
28177 QueryBestSize XQueryBestCursor
28178 XQueryBestSize
28179 XQueryBestStipple
28180 XQueryBestTile
28181 QueryColors XQueryColor
28182 XQueryColors
28183 QueryExtension XInitExtension
28184 XQueryExtension
28185 QueryFont XLoadQueryFont
28186 XQueryFont
28187 QueryKeymap XQueryKeymap
28188 QueryPointer XQueryPointer
28189 QueryTextExtents XQueryTextExtents
28190 XQueryTextExtents16
28191 QueryTree XQueryTree
28192 RecolorCursor XRecolorCursor
28193 ReparentWindow XReparentWindow
28194 RotateProperties XRotateBuffers
28195 XRotateWindowProperties
28196 SendEvent XIconifyWindow
28197 XReconfigureWMWindow
28198 XSendEvent
28199 XWithdrawWindow
28200 SetAccessControl XDisableAccessControl
28201 XEnableAccessControl
28202 XSetAccessControl
28203 SetClipRectangles XSetClipRectangles
28204 SetCloseDownMode XSetCloseDownMode
28205 SetDashes XSetDashes
28206 SetFontPath XSetFontPath
28207 SetInputFocus XSetInputFocus
28208 SetModifierMapping XSetModifierMapping
28209 SetPointerMapping XSetPointerMapping
28210 SetScreenSaver XGetScreenSaver
28211 XSetScreenSaver
28212 SetSelectionOwner XSetSelectionOwner
28213 StoreColors XStoreColor
28214 XStoreColors
28215 StoreNamedColor XStoreNamedColor
28216 TranslateCoordinates XTranslateCoordinates
28217 UngrabButton XUngrabButton
28218 UngrabKey XUngrabKey
28219 UngrabKeyboard XUngrabKeyboard
28220 UngrabPointer XUngrabPointer
28221 UngrabServer XUngrabServer
28222 UninstallColormap XUninstallColormap
28223 UnmapSubwindows XUnmapSubWindows
28224 UnmapWindow XUnmapWindow
28225 XWithdrawWindow
28226 WarpPointer XWarpPointer
28227
28228Appendix B. X Font Cursors
28229
28230 The following are the available cursors that can be used with
28231 XCreateFontCursor.
28232#define XC_X_cursor 0 #define XC_ll_angle 76
28233#define XC_arrow 2 #define XC_lr_angle 78
28234#define XC_based_arrow_down 4 #define XC_man 80
28235#define XC_based_arrow_up 6 #define XC_middlebutton 82
28236#define XC_boat 8 #define XC_mouse 84
28237#define XC_bogosity 10 #define XC_pencil 86
28238#define XC_bottom_left_corner 12 #define XC_pirate 88
28239#define XC_bottom_right_corner 14 #define XC_plus 90
28240#define XC_bottom_side 16 #define XC_question_arrow 92
28241#define XC_bottom_tee 18 #define XC_right_ptr 94
28242#define XC_box_spiral 20 #define XC_right_side 96
28243#define XC_center_ptr 22 #define XC_right_tee 98
28244#define XC_circle 24 #define XC_rightbutton 100
28245#define XC_clock 26 #define XC_rtl_logo 102
28246#define XC_coffee_mug 28 #define XC_sailboat 104
28247#define XC_cross 30 #define XC_sb_down_arrow 106
28248#define XC_cross_reverse 32 #define XC_sb_h_double_arrow 1
2824908
28250#define XC_crosshair 34 #define XC_sb_left_arrow 110
28251#define XC_diamond_cross 36 #define XC_sb_right_arrow 112
28252#define XC_dot 38 #define XC_sb_up_arrow 114
28253#define XC_dot_box_mask 40 #define XC_sb_v_double_arrow 1
2825416
28255#define XC_double_arrow 42 #define XC_shuttle 118
28256#define XC_draft_large 44 #define XC_sizing 120
28257#define XC_draft_small 46 #define XC_spider 122
28258#define XC_draped_box 48 #define XC_spraycan 124
28259#define XC_exchange 50 #define XC_star 126
28260#define XC_fleur 52 #define XC_target 128
28261#define XC_gobbler 54 #define XC_tcross 130
28262#define XC_gumby 56 #define XC_top_left_arrow 132
28263#define XC_hand1 58 #define XC_top_left_corner 134
28264#define XC_hand2 60 #define XC_top_right_corner 13
282656
28266#define XC_heart 62 #define XC_top_side 138
28267#define XC_icon 64 #define XC_top_tee 140
28268#define XC_iron_cross 66 #define XC_trek 142
28269#define XC_left_ptr 68 #define XC_ul_angle 144
28270#define XC_left_side 70 #define XC_umbrella 146
28271#define XC_left_tee 72 #define XC_ur_angle 148
28272#define XC_leftbutton 74 #define XC_watch 150
28273 #define XC_xterm 152
28274
28275Appendix C. Extensions
28276
28277 Table of Contents
28278
28279 Basic Protocol Support Routines
28280 Hooking into Xlib
28281
28282 Hooks into the Library
28283 Hooks onto Xlib Data Structures
28284
28285 GC Caching
28286 Graphics Batching
28287 Writing Extension Stubs
28288
28289 Requests, Replies, and Xproto.h
28290 Request Format
28291 Starting to Write a Stub Procedure
28292 Locking Data Structures
28293 Sending the Protocol Request and Arguments
28294 Variable Length Arguments
28295 Replies
28296 Synchronous Calling
28297 Allocating and Deallocating Memory
28298 Portability Considerations
28299 Deriving the Correct Extension Opcode
28300
28301 Because X can evolve by extensions to the core protocol, it is
28302 important that extensions not be perceived as second-class
28303 citizens. At some point, your favorite extensions may be
28304 adopted as additional parts of the X Standard.
28305
28306 Therefore, there should be little to distinguish the use of an
28307 extension from that of the core protocol. To avoid having to
28308 initialize extensions explicitly in application programs, it is
28309 also important that extensions perform lazy evaluations,
28310 automatically initializing themselves when called for the first
28311 time.
28312
28313 This appendix describes techniques for writing extensions to
28314 Xlib that will run at essentially the same performance as the
28315 core protocol requests.
28316
28317Note
28318
28319 It is expected that a given extension to X consists of multiple
28320 requests. Defining 10 new features as 10 separate extensions is
28321 a bad practice. Rather, they should be packaged into a single
28322 extension and should use minor opcodes to distinguish the
28323 requests.
28324
28325 The symbols and macros used for writing stubs to Xlib are
28326 listed in <X11/Xlibint.h>.
28327
28328Basic Protocol Support Routines
28329
28330 The basic protocol requests for extensions are XQueryExtension
28331 and XListExtensions.
28332
28333 Bool XQueryExtension(Display *display, char *name, int
28334 *major_opcode_return, int *first_event_return, int
28335 *first_error_return);
28336
28337 display
28338
28339 Specifies the connection to the X server.
28340
28341 name
28342
28343 Specifies the extension name.
28344
28345 major_opcode_return
28346
28347 Returns the major opcode.
28348
28349 first_event_return
28350
28351 Returns the first event code, if any.
28352
28353 first_error_return
28354
28355 Returns the first error code, if any.
28356
28357 The XQueryExtension function determines if the named extension
28358 is present. If the extension is not present, XQueryExtension
28359 returns False; otherwise, it returns True. If the extension is
28360 present, XQueryExtension returns the major opcode for the
28361 extension to major_opcode_return; otherwise, it returns zero.
28362 Any minor opcode and the request formats are specific to the
28363 extension. If the extension involves additional event types,
28364 XQueryExtension returns the base event type code to
28365 first_event_return; otherwise, it returns zero. The format of
28366 the events is specific to the extension. If the extension
28367 involves additional error codes, XQueryExtension returns the
28368 base error code to first_error_return; otherwise, it returns
28369 zero. The format of additional data in the errors is specific
28370 to the extension.
28371
28372 If the extension name is not in the Host Portable Character
28373 Encoding the result is implementation-dependent. Uppercase and
28374 lowercase matter; the strings ``thing'', ``Thing'', and
28375 ``thinG'' are all considered different names.
28376
28377 char **XListExtensions(Display *display, int
28378 *nextensions_return);
28379
28380 display
28381
28382 Specifies the connection to the X server.
28383
28384 nextensions_return
28385
28386 Returns the number of extensions listed.
28387
28388 The XListExtensions function returns a list of all extensions
28389 supported by the server. If the data returned by the server is
28390 in the Latin Portable Character Encoding, then the returned
28391 strings are in the Host Portable Character Encoding. Otherwise,
28392 the result is implementation-dependent.
28393
28394 XFreeExtensionList(char **list);
28395
28396 list
28397
28398 Specifies the list of extension names.
28399
28400 The XFreeExtensionList function frees the memory allocated by
28401 XListExtensions.
28402
28403Hooking into Xlib
28404
28405 These functions allow you to hook into the library. They are
28406 not normally used by application programmers but are used by
28407 people who need to extend the core X protocol and the X library
28408 interface. The functions, which generate protocol requests for
28409 X, are typically called stubs.
28410
28411 In extensions, stubs first should check to see if they have
28412 initialized themselves on a connection. If they have not, they
28413 then should call XInitExtension to attempt to initialize
28414 themselves on the connection.
28415
28416 If the extension needs to be informed of GC/font allocation or
28417 deallocation or if the extension defines new event types, the
28418 functions described here allow the extension to be called when
28419 these events occur.
28420
28421 The XExtCodes structure returns the information from
28422 XInitExtension and is defined in <X11/Xlib.h>:
28423
28424typedef struct _XExtCodes { /* public to extension, cannot be change
28425d */
28426 int extension; /* extension number */
28427 int major_opcode; /* major op-code assigned by server */
28428 int first_event; /* first event number for the extension
28429*/
28430 int first_error; /* first error number for the extension
28431*/
28432} XExtCodes;
28433
28434 XExtCodes *XInitExtension(Display *display, char *name);
28435
28436 display
28437
28438 Specifies the connection to the X server.
28439
28440 name
28441
28442 Specifies the extension name.
28443
28444 The XInitExtension function determines if the named extension
28445 exists. Then, it allocates storage for maintaining the
28446 information about the extension on the connection, chains this
28447 onto the extension list for the connection, and returns the
28448 information the stub implementor will need to access the
28449 extension. If the extension does not exist, XInitExtension
28450 returns NULL.
28451
28452 If the extension name is not in the Host Portable Character
28453 Encoding, the result is implementation-dependent. Uppercase and
28454 lowercase matter; the strings ``thing'', ``Thing'', and
28455 ``thinG'' are all considered different names.
28456
28457 The extension number in the XExtCodes structure is needed in
28458 the other calls that follow. This extension number is unique
28459 only to a single connection.
28460
28461 XExtCodes *XAddExtension(Display *display);
28462
28463 display
28464
28465 Specifies the connection to the X server.
28466
28467 For local Xlib extensions, the XAddExtension function allocates
28468 the XExtCodes structure, bumps the extension number count, and
28469 chains the extension onto the extension list. (This permits
28470 extensions to Xlib without requiring server extensions.)
28471
28472Hooks into the Library
28473
28474 These functions allow you to define procedures that are to be
28475 called when various circumstances occur. The procedures include
28476 the creation of a new GC for a connection, the copying of a GC,
28477 the freeing of a GC, the creating and freeing of fonts, the
28478 conversion of events defined by extensions to and from wire
28479 format, and the handling of errors.
28480
28481 All of these functions return the previous procedure defined
28482 for this extension.
28483
28484 int XESetCloseDisplay(Display *display, int extension, int
28485 (*proc)());
28486
28487 display
28488
28489 Specifies the connection to the X server.
28490
28491 extension
28492
28493 Specifies the extension number.
28494
28495 proc
28496
28497 Specifies the procedure to call when the display is closed.
28498
28499 The XESetCloseDisplay function defines a procedure to be called
28500 whenever XCloseDisplay is called. It returns any previously
28501 defined procedure, usually NULL.
28502
28503 When XCloseDisplay is called, your procedure is called with
28504 these arguments:
28505
28506 int (*proc)(Display *display, XExtCodes *codes);
28507
28508 int *XESetCreateGC(Display *display, int extension, int
28509 (*proc)());
28510
28511 display
28512
28513 Specifies the connection to the X server.
28514
28515 extension
28516
28517 Specifies the extension number.
28518
28519 proc
28520
28521 Specifies the procedure to call when a GC is closed.
28522
28523 The XESetCreateGC function defines a procedure to be called
28524 whenever a new GC is created. It returns any previously defined
28525 procedure, usually NULL.
28526
28527 When a GC is created, your procedure is called with these
28528 arguments:
28529
28530 int (*proc)(Display *display, GC gc, XExtCodes *codes);
28531
28532 int *XESetCopyGC(Display *display, int extension, int
28533 (*proc)());
28534
28535 display
28536
28537 Specifies the connection to the X server.
28538
28539 extension
28540
28541 Specifies the extension number.
28542
28543 proc
28544
28545 Specifies the procedure to call when GC components are copied.
28546
28547 The XESetCopyGC function defines a procedure to be called
28548 whenever a GC is copied. It returns any previously defined
28549 procedure, usually NULL.
28550
28551 When a GC is copied, your procedure is called with these
28552 arguments:
28553
28554 int (*proc)(Display *display, GC gc, XExtCodes *codes);
28555
28556 int *XESetFreeGC(Display *display, int extension, int
28557 (*proc)());
28558
28559 display
28560
28561 Specifies the connection to the X server.
28562
28563 extension
28564
28565 Specifies the extension number.
28566
28567 proc
28568
28569 Specifies the procedure to call when a GC is freed.
28570
28571 The XESetFreeGC function defines a procedure to be called
28572 whenever a GC is freed. It returns any previously defined
28573 procedure, usually NULL.
28574
28575 When a GC is freed, your procedure is called with these
28576 arguments:
28577
28578 int (*proc)(Display *display, GC gc, XExtCodes *codes);
28579
28580 int *XESetCreateFont(Display *display, int extension, int
28581 (*proc)());
28582
28583 display
28584
28585 Specifies the connection to the X server.
28586
28587 extension
28588
28589 Specifies the extension number.
28590
28591 proc
28592
28593 Specifies the procedure to call when a font is created.
28594
28595 The XESetCreateFont function defines a procedure to be called
28596 whenever XLoadQueryFont and XQueryFont are called. It returns
28597 any previously defined procedure, usually NULL.
28598
28599 When XLoadQueryFont or XQueryFont is called, your procedure is
28600 called with these arguments:
28601
28602 int (*proc)(Display *display, XFontStruct *fs, XExtCodes
28603 *codes);
28604
28605 int *XESetFreeFont(Display *display, int extension, int
28606 (*proc)());
28607
28608 display
28609
28610 Specifies the connection to the X server.
28611
28612 extension
28613
28614 Specifies the extension number.
28615
28616 proc
28617
28618 Specifies the procedure to call when a font is freed.
28619
28620 The XESetFreeFont function defines a procedure to be called
28621 whenever XFreeFont is called. It returns any previously defined
28622 procedure, usually NULL.
28623
28624 When XFreeFont is called, your procedure is called with these
28625 arguments:
28626
28627 int (*proc)(Display *display, XFontStruct *fs, XExtCodes
28628 *codes);
28629
28630 The XESetWireToEvent and XESetEventToWire functions allow you
28631 to define new events to the library. An XEvent structure always
28632 has a type code (type int) as the first component. This
28633 uniquely identifies what kind of event it is. The second
28634 component is always the serial number (type unsigned long) of
28635 the last request processed by the server. The third component
28636 is always a Boolean (type Bool) indicating whether the event
28637 came from a SendEvent protocol request. The fourth component is
28638 always a pointer to the display the event was read from. The
28639 fifth component is always a resource ID of one kind or another,
28640 usually a window, carefully selected to be useful to toolkit
28641 dispatchers. The fifth component should always exist, even if
28642 the event does not have a natural destination; if there is no
28643 value from the protocol to put in this component, initialize it
28644 to zero. There is an implementation limit such that your host
28645 event structure size cannot be bigger than the size of the
28646 XEvent union of structures. There also is no way to guarantee
28647 that more than 24 elements or 96 characters in the structure
28648 will be fully portable between machines.
28649
28650 int *XESetWireToEvent(Display *display, int event_number,
28651 Status (*proc)());
28652
28653 display
28654
28655 Specifies the connection to the X server.
28656
28657 event_number
28658
28659 Specifies the event code.
28660
28661 proc
28662
28663 Specifies the procedure to call when converting an event.
28664
28665 The XESetWireToEvent function defines a procedure to be called
28666 when an event needs to be converted from wire format (xEvent)
28667 to host format (XEvent). The event number defines which
28668 protocol event number to install a conversion procedure for.
28669 XESetWireToEvent returns any previously defined procedure. You
28670 can replace a core event conversion function with one of your
28671 own, although this is not encouraged. It would, however, allow
28672 you to intercept a core event and modify it before being placed
28673 in the queue or otherwise examined. When Xlib needs to convert
28674 an event from wire format to host format, your procedure is
28675 called with these arguments:
28676
28677 int (*proc)(Display *display, XEvent *re, xEvent *event);
28678
28679 Your procedure must return status to indicate if the conversion
28680 succeeded. The re argument is a pointer to where the host
28681 format event should be stored, and the event argument is the
28682 32-byte wire event structure. In the XEvent structure you are
28683 creating, you must fill in the five required members of the
28684 event structure. You should fill in the type member with the
28685 type specified for the xEvent structure. You should copy all
28686 other members from the xEvent structure (wire format) to the
28687 XEvent structure (host format). Your conversion procedure
28688 should return True if the event should be placed in the queue
28689 or False if it should not be placed in the queue.
28690
28691 To initialize the serial number component of the event, call
28692 _XSetLastRequestRead with the event and use the return value.
28693
28694 unsigned long_XSetLastRequestRead(Display *display,
28695 xGenericReply *rep);
28696
28697 display
28698
28699 Specifies the connection to the X server.
28700
28701 rep
28702
28703 Specifies the wire event structure.
28704
28705 The _XSetLastRequestRead function computes and returns a
28706 complete serial number from the partial serial number in the
28707 event.
28708
28709 Status *XESetEventToWire(Display *display, int event_number,
28710 int (*proc)());
28711
28712 display
28713
28714 Specifies the connection to the X server.
28715
28716 event_number
28717
28718 Specifies the event code.
28719
28720 proc
28721
28722 Specifies the procedure to call when converting an event.
28723
28724 The XESetEventToWire function defines a procedure to be called
28725 when an event needs to be converted from host format (XEvent)
28726 to wire format (xEvent) form. The event number defines which
28727 protocol event number to install a conversion procedure for.
28728 XESetEventToWire returns any previously defined procedure. It
28729 returns zero if the conversion fails or nonzero otherwise. You
28730 can replace a core event conversion function with one of your
28731 own, although this is not encouraged. It would, however, allow
28732 you to intercept a core event and modify it before being sent
28733 to another client. When Xlib needs to convert an event from
28734 host format to wire format, your procedure is called with these
28735 arguments:
28736
28737 int (*proc)(Display *display, XEvent *re, xEvent *event);
28738
28739 The re argument is a pointer to the host format event, and the
28740 event argument is a pointer to where the 32-byte wire event
28741 structure should be stored. You should fill in the type with
28742 the type from the XEvent structure. All other members then
28743 should be copied from the host format to the xEvent structure.
28744
28745 Bool *XESetWireToError(Display *display, int error_number, Bool
28746 (*proc)());
28747
28748 display
28749
28750 Specifies the connection to the X server.
28751
28752 error_number
28753
28754 Specifies the error code.
28755
28756 proc
28757
28758 Specifies the procedure to call when an error is received.
28759
28760 The XESetWireToError function defines a procedure to be called
28761 when an extension error needs to be converted from wire format
28762 to host format. The error number defines which protocol error
28763 code to install the conversion procedure for. XESetWireToError
28764 returns any previously defined procedure.
28765
28766 Use this function for extension errors that contain additional
28767 error values beyond those in a core X error, when multiple wire
28768 errors must be combined into a single Xlib error, or when it is
28769 necessary to intercept an X error before it is otherwise
28770 examined.
28771
28772 When Xlib needs to convert an error from wire format to host
28773 format, the procedure is called with these arguments:
28774
28775 int (*proc)(Display *display, XErrorEvent *he, xError *we);
28776
28777 The he argument is a pointer to where the host format error
28778 should be stored. The structure pointed at by he is guaranteed
28779 to be as large as an XEvent structure and so can be cast to a
28780 type larger than an XErrorEvent to store additional values. If
28781 the error is to be completely ignored by Xlib (for example,
28782 several protocol error structures will be combined into one
28783 Xlib error), then the function should return False; otherwise,
28784 it should return True.
28785
28786 int *XESetError(Display *display, int extension, int
28787 (*proc)());
28788
28789 display
28790
28791 Specifies the connection to the X server.
28792
28793 extension
28794
28795 Specifies the extension number.
28796
28797 proc
28798
28799 Specifies the procedure to call when an error is received.
28800
28801 Inside Xlib, there are times that you may want to suppress the
28802 calling of the external error handling when an error occurs.
28803 This allows status to be returned on a call at the cost of the
28804 call being synchronous (though most such functions are query
28805 operations, in any case, and are typically programmed to be
28806 synchronous).
28807
28808 When Xlib detects a protocol error in _XReply, it calls your
28809 procedure with these arguments:
28810
28811 int (*proc)(Display *display, xError *err, XExtCodes *codes,
28812 int *ret_code);
28813
28814 The err argument is a pointer to the 32-byte wire format error.
28815 The codes argument is a pointer to the extension codes
28816 structure. The ret_code argument is the return code you may
28817 want _XReply returned to.
28818
28819 If your procedure returns a zero value, the error is not
28820 suppressed, and the client's error handler is called. (For
28821 further information, see section 11.8.2.) If your procedure
28822 returns nonzero, the error is suppressed, and _XReply returns
28823 the value of ret_code.
28824
28825 char *XESetErrorString(Display *display, int extension, char
28826 *(*proc)());
28827
28828 display
28829
28830 Specifies the connection to the X server.
28831
28832 extension
28833
28834 Specifies the extension number.
28835
28836 proc
28837
28838 Specifies the procedure to call to obtain an error string.
28839
28840 The XGetErrorText function returns a string to the user for an
28841 error. XESetErrorString allows you to define a procedure to be
28842 called that should return a pointer to the error message. The
28843 following is an example.
28844
28845 int (*proc)(Display *display, int code, XExtCodes *codes, char
28846 *buffer, int nbytes);
28847
28848 Your procedure is called with the error code for every error
28849 detected. You should copy nbytes of a null-terminated string
28850 containing the error message into buffer.
28851
28852 void *XESetPrintErrorValues(Display *display, int extension,
28853 void (*proc)());
28854
28855 display
28856
28857 Specifies the connection to the X server.
28858
28859 extension
28860
28861 Specifies the extension number.
28862
28863 proc
28864
28865 Specifies the procedure to call when an error is printed.
28866
28867 The XESetPrintErrorValues function defines a procedure to be
28868 called when an extension error is printed, to print the error
28869 values. Use this function for extension errors that contain
28870 additional error values beyond those in a core X error. It
28871 returns any previously defined procedure.
28872
28873 When Xlib needs to print an error, the procedure is called with
28874 these arguments:
28875
28876 void (*proc)(Display *display, XErrorEvent *ev, void *fp);
28877
28878 The structure pointed at by ev is guaranteed to be as large as
28879 an XEvent structure and so can be cast to a type larger than an
28880 XErrorEvent to obtain additional values set by using
28881 XESetWireToError. The underlying type of the fp argument is
28882 system dependent; on a POSIX-compliant system, fp should be
28883 cast to type FILE*.
28884
28885 int *XESetFlushGC(Display *display, int extension, int
28886 *(*proc)());
28887
28888 display
28889
28890 Specifies the connection to the X server.
28891
28892 extension
28893
28894 Specifies the extension number.
28895
28896 proc
28897
28898 Specifies the procedure to call when a GC is flushed.
28899
28900 The procedure set by the XESetFlushGC function has the same
28901 interface as the procedure set by the XESetCopyGC function, but
28902 is called when a GC cache needs to be updated in the server.
28903
28904 int *XESetCopyGC(Display *display, int extension, int
28905 *(*proc)());
28906
28907 display
28908
28909 Specifies the connection to the X server.
28910
28911 extension
28912
28913 Specifies the extension number.
28914
28915 proc
28916
28917 Specifies the procedure to call when a buffer is flushed.
28918
28919 The XESetBeforeFlush function defines a procedure to be called
28920 when data is about to be sent to the server. When data is about
28921 to be sent, your procedure is called one or more times with
28922 these arguments:
28923
28924 void (*proc)(Display *display, XExtCodes *codes, char *data,
28925 long len);
28926
28927 The data argument specifies a portion of the outgoing data
28928 buffer, and its length in bytes is specified by the len
28929 argument. Your procedure must not alter the contents of the
28930 data and must not do additional protocol requests to the same
28931 display.
28932
28933Hooks onto Xlib Data Structures
28934
28935 Various Xlib data structures have provisions for extension
28936 procedures to chain extension supplied data onto a list. These
28937 structures are GC, Visual, Screen, ScreenFormat, Display, and
28938 XFontStruct. Because the list pointer is always the first
28939 member in the structure, a single set of procedures can be used
28940 to manipulate the data on these lists.
28941
28942 The following structure is used in the functions in this
28943 section and is defined in <X11/Xlib.h>
28944
28945typedef struct _XExtData {
28946 int number; /* number returned by XInitExtension */
28947 struct _XExtData *next; /* next item on list of data for structu
28948re */
28949 int (*free_private)(); /* if defined, called to free private *
28950/
28951 XPointer private_data; /* data private to this extension. */
28952} XExtData;
28953
28954 When any of the data structures listed above are freed, the
28955 list is walked, and the structure's free procedure (if any) is
28956 called. If free is NULL, then the library frees both the data
28957 pointed to by the private_data member and the structure itself.
28958
28959union { Display *display;
28960 GC gc;
28961 Visual *visual;
28962 Screen *screen;
28963 ScreenFormat *pixmap_format;
28964 XFontStruct *font } XEDataObject;
28965
28966 XExtData **XEHeadOfExtensionList(XEDataObject object);
28967
28968 object
28969
28970 Specifies the object.
28971
28972 The XEHeadOfExtensionList function returns a pointer to the
28973 list of extension structures attached to the specified object.
28974 In concert with XAddToExtensionList, XEHeadOfExtensionList
28975 allows an extension to attach arbitrary data to any of the
28976 structures of types contained in XEDataObject.
28977
28978 XAddToExtensionList(XExtData **structure, XExtData *ext_data);
28979
28980 structure
28981
28982 Specifies the extension list.
28983
28984 ext_data
28985
28986 Specifies the extension data structure to add.
28987
28988 The structure argument is a pointer to one of the data
28989 structures enumerated above. You must initialize
28990 ext_data->number with the extension number before calling this
28991 function.
28992
28993 XExtData *XFindOnExtensionList(struct_XExtData **structure, int
28994 number);
28995
28996 structure
28997
28998 Specifies the extension list.
28999
29000 number
29001
29002 Specifies the extension number from XInitExtension.
29003
29004 The XFindOnExtensionList function returns the first extension
29005 data structure for the extension numbered number. It is
29006 expected that an extension will add at most one extension data
29007 structure to any single data structure's extension data list.
29008 There is no way to find additional structures.
29009
29010 The XAllocID macro, which allocates and returns a resource ID,
29011 is defined in <X11/Xlib.h>.
29012
29013 XAllocID(Display *display);
29014
29015 display
29016
29017 Specifies the connection to the X server.
29018
29019 This macro is a call through the Display structure to an
29020 internal resource ID allocator. It returns a resource ID that
29021 you can use when creating new resources.
29022
29023 The XAllocIDs macro allocates and returns an array of resource
29024 ID.
29025
29026 XAllocIDs(Display *display, XID *ids_return, int count);
29027
29028 display
29029
29030 Specifies the connection to the X server.
29031
29032 ids_return
29033
29034 Returns the resource IDs.
29035
29036 rep
29037
29038 Specifies the number of resource IDs requested.
29039
29040 This macro is a call through the Display structure to an
29041 internal resource ID allocator. It returns resource IDs to the
29042 array supplied by the caller. To correctly handle automatic
29043 reuse of resource IDs, you must call XAllocIDs when requesting
29044 multiple resource IDs. This call might generate protocol
29045 requests.
29046
29047GC Caching
29048
29049 GCs are cached by the library to allow merging of independent
29050 change requests to the same GC into single protocol requests.
29051 This is typically called a write-back cache. Any extension
29052 procedure whose behavior depends on the contents of a GC must
29053 flush the GC cache to make sure the server has up-to-date
29054 contents in its GC.
29055
29056 The FlushGC macro checks the dirty bits in the library's GC
29057 structure and calls _XFlushGCCache if any elements have
29058 changed. The FlushGC macro is defined as follows:
29059
29060 FlushGC(Display *display, GC gc);
29061
29062 display
29063
29064 Specifies the connection to the X server.
29065
29066 gc
29067
29068 Specifies the GC.
29069
29070 Note that if you extend the GC to add additional resource ID
29071 components, you should ensure that the library stub sends the
29072 change request immediately. This is because a client can free a
29073 resource immediately after using it, so if you only stored the
29074 value in the cache without forcing a protocol request, the
29075 resource might be destroyed before being set into the GC. You
29076 can use the _XFlushGCCache procedure to force the cache to be
29077 flushed. The _XFlushGCCache procedure is defined as follows:
29078
29079 _XFlushGCCache(Display *display, GC gc);
29080
29081 display
29082
29083 Specifies the connection to the X server.
29084
29085 gc
29086
29087 Specifies the GC.
29088
29089Graphics Batching
29090
29091 If you extend X to add more poly graphics primitives, you may
29092 be able to take advantage of facilities in the library to allow
29093 back-to-back single calls to be transformed into poly requests.
29094 This may dramatically improve performance of programs that are
29095 not written using poly requests. A pointer to an xReq, called
29096 last_req in the display structure, is the last request being
29097 processed. By checking that the last request type, drawable,
29098 gc, and other options are the same as the new one and that
29099 there is enough space left in the buffer, you may be able to
29100 just extend the previous graphics request by extending the
29101 length field of the request and appending the data to the
29102 buffer. This can improve performance by five times or more in
29103 naive programs. For example, here is the source for the
29104 XDrawPoint stub. (Writing extension stubs is discussed in the
29105 next section.)
29106#include <X11/Xlibint.h>
29107
29108/* precompute the maximum size of batching request allowed */
29109
29110static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);
29111
29112XDrawPoint(dpy, d, gc, x, y)
29113 register Display *dpy;
29114 Drawable d;
29115 GC gc;
29116 int x, y; /* INT16 */
29117{
29118 xPoint *point;
29119 LockDisplay(dpy);
29120 FlushGC(dpy, gc);
29121 {
29122 register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req;
29123 /* if same as previous request, with same drawable, batch requests *
29124/
29125 if (
29126 (req->reqType == X_PolyPoint)
29127 && (req->drawable == d)
29128 && (req->gc == gc->gid)
29129 && (req->coordMode == CoordModeOrigin)
29130 && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
29131 && (((char *)dpy->bufptr - (char *)req) < size) ) {
29132 point = (xPoint *) dpy->bufptr;
29133 req->length += sizeof (xPoint) >> 2;
29134 dpy->bufptr += sizeof (xPoint);
29135 }
29136
29137 else {
29138 GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
29139 req->drawable = d;
29140 req->gc = gc->gid;
29141 req->coordMode = CoordModeOrigin;
29142 point = (xPoint *) (req + 1);
29143 }
29144 point->x = x;
29145 point->y = y;
29146 }
29147 UnlockDisplay(dpy);
29148 SyncHandle();
29149}
29150
29151 To keep clients from generating very long requests that may
29152 monopolize the server, there is a symbol defined in
29153 <X11/Xlibint.h> of EPERBATCH on the number of requests batched.
29154 Most of the performance benefit occurs in the first few merged
29155 requests. Note that FlushGC is called before picking up the
29156 value of last_req, because it may modify this field.
29157
29158Writing Extension Stubs
29159
29160 All X requests always contain the length of the request,
29161 expressed as a 16-bit quantity of 32 bit words. This means that
29162 a single request can be no more than 256K bytes in length. Some
29163 servers may not support single requests of such a length. The
29164 value of dpy->max_request_size contains the maximum length as
29165 defined by the server implementation. For further information,
29166 see X Window System Protocol.
29167
29168Requests, Replies, and Xproto.h
29169
29170 The <X11/Xproto.h> file contains three sets of definitions that
29171 are of interest to the stub implementor: request names, request
29172 structures, and reply structures.
29173
29174 You need to generate a file equivalent to <X11/Xproto.h> for
29175 your extension and need to include it in your stub procedure.
29176 Each stub procedure also must include <X11/Xlibint.h>.
29177
29178 The identifiers are deliberately chosen in such a way that, if
29179 the request is called X_DoSomething, then its request structure
29180 is xDoSomethingReq, and its reply is xDoSomethingReply. The
29181 GetReq family of macros, defined in <X11/Xlibint.h>, takes
29182 advantage of this naming scheme.
29183
29184 For each X request, there is a definition in <X11/Xproto.h>
29185 that looks similar to this:
29186
29187#define X_DoSomething 42
29188
29189 In your extension header file, this will be a minor opcode,
29190 instead of a major opcode.
29191
29192Request Format
29193
29194 Every request contains an 8-bit major opcode and a 16-bit
29195 length field expressed in units of 4 bytes. Every request
29196 consists of 4 bytes of header (containing the major opcode, the
29197 length field, and a data byte) followed by zero or more
29198 additional bytes of data. The length field defines the total
29199 length of the request, including the header. The length field
29200 in a request must equal the minimum length required to contain
29201 the request. If the specified length is smaller or larger than
29202 the required length, the server should generate a BadLength
29203 error. Unused bytes in a request are not required to be zero.
29204 Extensions should be designed in such a way that long protocol
29205 requests can be split up into smaller requests, if it is
29206 possible to exceed the maximum request size of the server. The
29207 protocol guarantees the maximum request size to be no smaller
29208 than 4096 units (16384 bytes).
29209
29210 Major opcodes 128 through 255 are reserved for extensions.
29211 Extensions are intended to contain multiple requests, so
29212 extension requests typically have an additional minor opcode
29213 encoded in the second data byte in the request header, but the
29214 placement and interpretation of this minor opcode as well as
29215 all other fields in extension requests are not defined by the
29216 core protocol. Every request is implicitly assigned a sequence
29217 number (starting with one) used in replies, errors, and events.
29218
29219 Most protocol requests have a corresponding structure typedef
29220 in <X11/Xproto.h>, which looks like:
29221
29222typedef struct _DoSomethingReq {
29223 CARD8 reqType; /* X_DoSomething */
29224 CARD8 someDatum; /* used differently in different request
29225s */
29226 CARD16 length; /* total # of bytes in request, divided
29227by 4 */
29228 ...
29229 /* request-specific data */
29230 ...
29231} xDoSomethingReq;
29232
29233 If a core protocol request has a single 32-bit argument, you
29234 need not declare a request structure in your extension header
29235 file. Instead, such requests use the xResourceReq structure in
29236 <X11/Xproto.h>. This structure is used for any request whose
29237 single argument is a Window, Pixmap, Drawable, GContext, Font,
29238 Cursor, Colormap, Atom, or VisualID.
29239
29240typedef struct _ResourceReq {
29241 CARD8 reqType; /* the request type, e.g. X_DoSomething */
29242 BYTE pad; /* not used */
29243 CARD16 length; /* 2 (= total # of bytes in request, divided by
292444) */
29245 CARD32 id; /* the Window, Drawable, Font, GContext, etc. */
29246} xResourceReq;
29247
29248 If convenient, you can do something similar in your extension
29249 header file.
29250
29251 In both of these structures, the reqType field identifies the
29252 type of the request (for example, X_MapWindow or
29253 X_CreatePixmap). The length field tells how long the request is
29254 in units of 4-byte longwords. This length includes both the
29255 request structure itself and any variable-length data, such as
29256 strings or lists, that follow the request structure. Request
29257 structures come in different sizes, but all requests are padded
29258 to be multiples of four bytes long.
29259
29260 A few protocol requests take no arguments at all. Instead, they
29261 use the xReq structure in <X11/Xproto.h>, which contains only a
29262 reqType and a length (and a pad byte).
29263
29264 If the protocol request requires a reply, then <X11/Xproto.h>
29265 also contains a reply structure typedef:
29266
29267typedef struct _DoSomethingReply {
29268 BYTE type; /* always X_Reply */
29269 BYTE someDatum; /* used differently in different requests */
29270 CARD16 sequenceNumber; /* # of requests sent so far */
29271 CARD32 length; /* # of additional bytes, divided by 4 */
29272 ...
29273 /* request-specific data */
29274 ...
29275} xDoSomethingReply;
29276
29277 Most of these reply structures are 32 bytes long. If there are
29278 not that many reply values, then they contain a sufficient
29279 number of pad fields to bring them up to 32 bytes. The length
29280 field is the total number of bytes in the request minus 32,
29281 divided by 4. This length will be nonzero only if:
29282 * The reply structure is followed by variable-length data,
29283 such as a list or string.
29284 * The reply structure is longer than 32 bytes.
29285
29286 Only GetWindowAttributesl, QueryFont, QueryKeymap, and
29287 GetKeyboardControl have reply structures longer than 32 bytes
29288 in the core protocol.
29289
29290 A few protocol requests return replies that contain no data.
29291 <X11/Xproto.h> does not define reply structures for these.
29292 Instead, they use the xGenericReply structure, which contains
29293 only a type, length, and sequence number (and sufficient
29294 padding to make it 32 bytes long).
29295
29296Starting to Write a Stub Procedure
29297
29298 An Xlib stub procedure should start like this:
29299
29300#include "<X11/Xlibint.h>
29301
29302XDoSomething (arguments, ... )
29303/* argument declarations */
29304{
29305
29306register XDoSomethingReq *req;
29307...
29308
29309 If the protocol request has a reply, then the variable
29310 declarations should include the reply structure for the
29311 request. The following is an example:
29312
29313xDoSomethingReply rep;
29314
29315Locking Data Structures
29316
29317 To lock the display structure for systems that want to support
29318 multithreaded access to a single display connection, each stub
29319 will need to lock its critical section. Generally, this section
29320 is the point from just before the appropriate GetReq call until
29321 all arguments to the call have been stored into the buffer. The
29322 precise instructions needed for this locking depend upon the
29323 machine architecture. Two calls, which are generally
29324 implemented as macros, have been provided.
29325
29326 LockDisplay(Display *display);
29327
29328 UnlockDisplay(Display *display);
29329
29330 display
29331
29332 Specifies the connection to the X server.
29333
29334Sending the Protocol Request and Arguments
29335
29336 After the variable declarations, a stub procedure should call
29337 one of four macros defined in <X11/Xlibint.h>: GetReq,
29338 GetReqExtra, GetResReq, or GetEmptyReq. All of these macros
29339 take, as their first argument, the name of the protocol request
29340 as declared in <X11/Xproto.h> except with X_ removed. Each one
29341 declares a Display structure pointer, called dpy, and a pointer
29342 to a request structure, called req, which is of the appropriate
29343 type. The macro then appends the request structure to the
29344 output buffer, fills in its type and length field, and sets req
29345 to point to it.
29346
29347 If the protocol request has no arguments (for instance,
29348 X_GrabServer), then use GetEmptyReq.
29349
29350GetEmptyReq (DoSomething, req);
29351
29352 If the protocol request has a single 32-bit argument (such as a
29353 Pixmap, Window, Drawable, Atom, and so on), then use GetResReq.
29354 The second argument to the macro is the 32-bit object.
29355 X_MapWindow is a good example.
29356
29357GetResReq (DoSomething, rid, req);
29358
29359 The rid argument is the Pixmap, Window, or other resource ID.
29360
29361 If the protocol request takes any other argument list, then
29362 call GetReq. After the GetReq, you need to set all the other
29363 fields in the request structure, usually from arguments to the
29364 stub procedure.
29365
29366GetReq (DoSomething, req);
29367/* fill in arguments here */
29368req->arg1 = arg1;
29369req->arg2 = arg2;
29370...
29371
29372 A few stub procedures (such as XCreateGC and XCreatePixmap)
29373 return a resource ID to the caller but pass a resource ID as an
29374 argument to the protocol request. Such procedures use the macro
29375 XAllocID to allocate a resource ID from the range of IDs that
29376 were assigned to this client when it opened the connection.
29377
29378rid = req->rid = XAllocID();
29379...
29380return (rid);
29381
29382 Finally, some stub procedures transmit a fixed amount of
29383 variable-length data after the request. Typically, these
29384 procedures (such as XMoveWindow and XSetBackground) are special
29385 cases of more general functions like XMoveResizeWindow and
29386 XChangeGC. These procedures use GetReqExtra, which is the same
29387 as GetReq except that it takes an additional argument (the
29388 number of extra bytes to allocate in the output buffer after
29389 the request structure). This number should always be a multiple
29390 of four. Note that it is possible for req to be set to NULL as
29391 a defensive measure if the requested length exceeds the Xlib's
29392 buffer size (normally 16K).
29393
29394Variable Length Arguments
29395
29396 Some protocol requests take additional variable-length data
29397 that follow the xDoSomethingReq structure. The format of this
29398 data varies from request to request. Some requests require a
29399 sequence of 8-bit bytes, others a sequence of 16-bit or 32-bit
29400 entities, and still others a sequence of structures.
29401
29402 It is necessary to add the length of any variable-length data
29403 to the length field of the request structure. That length field
29404 is in units of 32-bit longwords. If the data is a string or
29405 other sequence of 8-bit bytes, then you must round the length
29406 up and shift it before adding:
29407
29408req->length += (nbytes+3)>>2;
29409
29410 To transmit variable-length data, use the Data macros. If the
29411 data fits into the output buffer, then this macro copies it to
29412 the buffer. If it does not fit, however, the Data macro calls
29413 _XSend, which transmits first the contents of the buffer and
29414 then your data. The Data macros take three arguments: the
29415 display, a pointer to the beginning of the data, and the number
29416 of bytes to be sent.
29417
29418 Data(display, (char *) data, nbytes);
29419
29420 Data16(display, (short *) data, nbytes);
29421
29422 Data32(display, (long *) data, nbytes);
29423
29424 Data, Data16, and Data32 are macros that may use their last
29425 argument more than once, so that argument should be a variable
29426 rather than an expression such as ``nitems*sizeof(item)''. You
29427 should do that kind of computation in a separate statement
29428 before calling them. Use the appropriate macro when sending
29429 byte, short, or long data.
29430
29431 If the protocol request requires a reply, then call the
29432 procedure _XSend instead of the Data macro. _XSend takes the
29433 same arguments, but because it sends your data immediately
29434 instead of copying it into the output buffer (which would later
29435 be flushed anyway by the following call on _XReply), it is
29436 faster.
29437
29438Replies
29439
29440 If the protocol request has a reply, then call _XReply after
29441 you have finished dealing with all the fixed-length and
29442 variable-length arguments. _XReply flushes the output buffer
29443 and waits for an xReply packet to arrive. If any events arrive
29444 in the meantime, _XReply places them in the queue for later
29445 use.
29446
29447 Status _XReply(Display *display, xReply *rep, int extra, Bool
29448 discard);
29449
29450 display
29451
29452 Specifies the connection to the X server.
29453
29454 rep
29455
29456 Specifies the reply structure.
29457
29458 extra
29459
29460 Specifies the number of 32-bit words expected after the replay.
29461
29462 discard
29463
29464 Specifies if any data beyond that specified in the extra
29465 argument should be discarded.
29466
29467 The _XReply function waits for a reply packet and copies its
29468 contents into the specified rep. _XReply handles error and
29469 event packets that occur before the reply is received. _XReply
29470 takes four arguments:
29471 * A Display * structure
29472 * A pointer to a reply structure (which must be cast to an
29473 xReply *)
29474 * The number of additional 32-bit words (beyond sizeof(
29475 xReply) = 32 bytes) in the reply structure
29476 * A Boolean that indicates whether _XReply is to discard any
29477 additional bytes beyond those it was told to read
29478
29479 Because most reply structures are 32 bytes long, the third
29480 argument is usually 0. The only core protocol exceptions are
29481 the replies to GetWindowAttributesl, QueryFont, QueryKeymap,
29482 and GetKeyboardControl, which have longer replies.
29483
29484 The last argument should be False if the reply structure is
29485 followed by additional variable-length data (such as a list or
29486 string). It should be True if there is not any variable-length
29487 data. This last argument is provided for upward-compatibility
29488 reasons to allow a client to communicate properly with a
29489 hypothetical later version of the server that sends more data
29490 than the client expected. For example, some later version of
29491 GetWindowAttributesl might use a larger, but compatible,
29492 xGetWindowAttributesReply that contains additional attribute
29493 data at the end. _XReply returns True if it received a reply
29494 successfully or False if it received any sort of error.
29495
29496 For a request with a reply that is not followed by
29497 variable-length data, you write something like:
29498
29499_XReply(display, (xReply *)&rep, 0, True);
29500*ret1 = rep.ret1;
29501*ret2 = rep.ret2;
29502*ret3 = rep.ret3;
29503...
29504UnlockDisplay(dpy);
29505SyncHandle();
29506return (rep.ret4);
29507}
29508
29509 If there is variable-length data after the reply, change the
29510 True to False, and use the appropriate _XRead function to read
29511 the variable-length data.
29512
29513 _XRead(Display *display, char *data_return, long nbytes);
29514
29515 display
29516
29517 Specifies the connection to the X server.
29518
29519 data_return
29520
29521 Specifies the buffer.
29522
29523 nbytes
29524
29525 Specifies the number of bytes required.
29526
29527 The _XRead function reads the specified number of bytes into
29528 data_return.
29529
29530 _XRead16(Display *display, short *data_return, long nbytes);
29531
29532 display
29533
29534 Specifies the connection to the X server.
29535
29536 data_return
29537
29538 Specifies the buffer.
29539
29540 nbytes
29541
29542 Specifies the number of bytes required.
29543
29544 The _XRead16 function reads the specified number of bytes,
29545 unpacking them as 16-bit quantities, into the specified array
29546 as shorts.
29547
29548 _XRead32(Display *display, long *data_return, long nbytes);
29549
29550 display
29551
29552 Specifies the connection to the X server.
29553
29554 data_return
29555
29556 Specifies the buffer.
29557
29558 nbytes
29559
29560 Specifies the number of bytes required.
29561
29562 The _XRead32 function reads the specified number of bytes,
29563 unpacking them as 32-bit quantities, into the specified array
29564 as longs.
29565
29566 _XRead16Pad(Display *display, short *data_return, long nbytes);
29567
29568 display
29569
29570 Specifies the connection to the X server.
29571
29572 data_return
29573
29574 Specifies the buffer.
29575
29576 nbytes
29577
29578 Specifies the number of bytes required.
29579
29580 The _XRead16Pad function reads the specified number of bytes,
29581 unpacking them as 16-bit quantities, into the specified array
29582 as shorts. If the number of bytes is not a multiple of four,
29583 _XRead16Pad reads and discards up to two additional pad bytes.
29584
29585 _XReadPad(Display *display, char *data_return, long nbytes);
29586
29587 display
29588
29589 Specifies the connection to the X server.
29590
29591 data_return
29592
29593 Specifies the buffer.
29594
29595 nbytes
29596
29597 Specifies the number of bytes required.
29598
29599 The _XReadPad function reads the specified number of bytes into
29600 data_return. If the number of bytes is not a multiple of four,
29601 _XReadPad reads and discards up to three additional pad bytes.
29602
29603 Each protocol request is a little different. For further
29604 information, see the Xlib sources for examples.
29605
29606Synchronous Calling
29607
29608 Each procedure should have a call, just before returning to the
29609 user, to a macro called SyncHandle. If synchronous mode is
29610 enabled (see XSynchronize), the request is sent immediately.
29611 The library, however, waits until any error the procedure could
29612 generate at the server has been handled.
29613
29614Allocating and Deallocating Memory
29615
29616 To support the possible reentry of these procedures, you must
29617 observe several conventions when allocating and deallocating
29618 memory, most often done when returning data to the user from
29619 the window system of a size the caller could not know in
29620 advance (for example, a list of fonts or a list of extensions).
29621 The standard C library functions on many systems are not
29622 protected against signals or other multithreaded uses. The
29623 following analogies to standard I/O library functions have been
29624 defined:
29625
29626 These should be used in place of any calls you would make to
29627 the normal C library functions.
29628
29629 If you need a single scratch buffer inside a critical section
29630 (for example, to pack and unpack data to and from the wire
29631 protocol), the general memory allocators may be too expensive
29632 to use (particularly in output functions, which are performance
29633 critical). The following function returns a scratch buffer for
29634 use within a critical section:
29635
29636 char *_XAllocScratch(Display *display, unsigned long nbytes);
29637
29638 display
29639
29640 Specifies the connection to the X server.
29641
29642 nbytes
29643
29644 Specifies the number of bytes required.
29645
29646 This storage must only be used inside of a critical section of
29647 your stub. The returned pointer cannot be assumed valid after
29648 any call that might permit another thread to execute inside
29649 Xlib. For example, the pointer cannot be assumed valid after
29650 any use of the GetReq or Data families of macros, after any use
29651 of _XReply, or after any use of the _XSend or _XRead families
29652 of functions.
29653
29654 The following function returns a scratch buffer for use across
29655 critical sections:
29656
29657 char *_XAllocTemp(Display *display, unsigned long nbytes);
29658
29659 display
29660
29661 Specifies the connection to the X server.
29662
29663 nbytes
29664
29665 Specifies the number of bytes required.
29666
29667 This storage can be used across calls that might permit another
29668 thread to execute inside Xlib. The storage must be explicitly
29669 returned to Xlib. The following function returns the storage:
29670
29671 void _XFreeTemp(Display *display, char *buf, unsigned long
29672 nbytes);
29673
29674 display
29675
29676 Specifies the connection to the X server.
29677
29678 buf
29679
29680 Specifies the buffer to return.
29681
29682 nbytes
29683
29684 Specifies the size of the buffer.
29685
29686 You must pass back the same pointer and size that were returned
29687 by _XAllocTemp.
29688
29689Portability Considerations
29690
29691 Many machine architectures do not correctly or efficiently
29692 access data at unaligned locations; their compilers pad out
29693 structures to preserve this characteristic. Many other machines
29694 capable of unaligned references pad inside of structures as
29695 well to preserve alignment, because accessing aligned data is
29696 usually much faster. Because the library and the server use
29697 structures to access data at arbitrary points in a byte stream,
29698 all data in request and reply packets must be naturally
29699 aligned; that is, 16-bit data starts on 16-bit boundaries in
29700 the request and 32-bit data on 32-bit boundaries. All requests
29701 must be a multiple of 32 bits in length to preserve the natural
29702 alignment in the data stream. You must pad structures out to
29703 32-bit boundaries. Pad information does not have to be zeroed
29704 unless you want to preserve such fields for future use in your
29705 protocol requests, but it is recommended to zero it to avoid
29706 inadvertant data leakage and improve compressability. Floating
29707 point varies radically between machines and should be avoided
29708 completely if at all possible.
29709
29710 This code may run on machines with 16-bit ints. So, if any
29711 integer argument, variable, or return value either can take
29712 only nonnegative values or is declared as a CARD16 in the
29713 protocol, be sure to declare it as unsigned int and not as int.
29714 (This, of course, does not apply to Booleans or enumerations.)
29715
29716 Similarly, if any integer argument or return value is declared
29717 CARD32 in the protocol, declare it as an unsigned long and not
29718 as int or long. This also goes for any internal variables that
29719 may take on values larger than the maximum 16-bit unsigned int.
29720
29721 The library has always assumed that a char is 8 bits, a short
29722 is 16 bits, an int is 16 or 32 bits, and a long is 32 bits.
29723 Unfortunately, this assumption remains on machines where a long
29724 can hold 64-bits, and many functions and structures require
29725 unnecessarily large fields to avoid breaking compatibility with
29726 existing code. Special care must be taken with arrays of values
29727 that are transmitted in the protocol as CARD32 or INT32 but
29728 have to be converted to arrays of 64-bit long when passed to or
29729 from client applications.
29730
29731 The PackData macro is a half-hearted attempt to deal with the
29732 possibility of 32 bit shorts. However, much more work is needed
29733 to make this work properly.
29734
29735Deriving the Correct Extension Opcode
29736
29737 The remaining problem a writer of an extension stub procedure
29738 faces that the core protocol does not face is to map from the
29739 call to the proper major and minor opcodes. While there are a
29740 number of strategies, the simplest and fastest is outlined
29741 below.
29742 * Declare an array of pointers, _NFILE long (this is normally
29743 found in <stdio.h> and is the number of file descriptors
29744 supported on the system) of type XExtCodes. Make sure these
29745 are all initialized to NULL.
29746 * When your stub is entered, your initialization test is just
29747 to use the display pointer passed in to access the file
29748 descriptor and an index into the array. If the entry is
29749 NULL, then this is the first time you are entering the
29750 procedure for this display. Call your initialization
29751 procedure and pass to it the display pointer.
29752 * Once in your initialization procedure, call XInitExtension;
29753 if it succeeds, store the pointer returned into this array.
29754 Make sure to establish a close display handler to allow you
29755 to zero the entry. Do whatever other initialization your
29756 extension requires. (For example, install event handlers
29757 and so on.) Your initialization procedure would normally
29758 return a pointer to the XExtCodes structure for this
29759 extension, which is what would normally be found in your
29760 array of pointers.
29761 * After returning from your initialization procedure, the
29762 stub can now continue normally, because it has its major
29763 opcode safely in its hand in the XExtCodes structure.
29764
29765Appendix D. Compatibility Functions
29766
29767 Table of Contents
29768
29769 X Version 11 Compatibility Functions
29770
29771 Setting Standard Properties
29772 Setting and Getting Window Sizing Hints
29773 Getting and Setting an XStandardColormap Structure
29774 Parsing Window Geometry
29775 Getting the X Environment Defaults
29776
29777 X Version 10 Compatibility Functions
29778
29779 Drawing and Filling Polygons and Curves
29780 Associating User Data with a Value
29781
29782 The X Version 11 and X Version 10 functions discussed in this
29783 appendix are obsolete, have been superseded by newer X Version
29784 11 functions, and are maintained for compatibility reasons
29785 only.
29786
29787X Version 11 Compatibility Functions
29788
29789 You can use the X Version 11 compatibility functions to:
29790 * Set standard properties
29791 * Set and get window sizing hints
29792 * Set and get an XStandardColormap structure
29793 * Parse window geometry
29794 * Get X environment defaults
29795
29796Setting Standard Properties
29797
29798 To specify a minimum set of properties describing the simplest
29799 application, use XSetStandardProperties. This function has been
29800 superseded by XSetWMProperties and sets all or portions of the
29801 WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, and
29802 WM_NORMAL_HINTS properties.
29803
29804 XSetStandardProperties(Display *display, Window w, char
29805 *window_name, char *icon_name, Pixmap icon_pixmap, char **argv,
29806 int argc, XSizeHints *hints);
29807
29808 display
29809
29810 Specifies the connection to the X server.
29811
29812 w
29813
29814 Specifies the window.
29815
29816 window_name
29817
29818 Specifies the window name, which should be a null-terminated
29819 string.
29820
29821 icon_name
29822
29823 Specifies the icon name, which should be a null-terminated
29824 string.
29825
29826 icon_pixmap
29827
29828 Specifies the bitmap that is to be used for the icon or None.
29829
29830 argv
29831
29832 Specifies the application's argument list.
29833
29834 argc
29835
29836 Specifies the number of arguments.
29837
29838 hints
29839
29840 Specifies a pointer to the size hints for the window in its
29841 normal state.
29842
29843 The XSetStandardProperties function provides a means by which
29844 simple applications set the most essential properties with a
29845 single call. XSetStandardProperties should be used to give a
29846 window manager some information about your program's
29847 preferences. It should not be used by applications that need to
29848 communicate more information than is possible with
29849 XSetStandardProperties. (Typically, argv is the argv array of
29850 your main program.) If the strings are not in the Host Portable
29851 Character Encoding, the result is implementation-dependent.
29852
29853 XSetStandardProperties can generate BadAlloc and BadWindow
29854 errors.
29855
29856Setting and Getting Window Sizing Hints
29857
29858 Xlib provides functions that you can use to set or get window
29859 sizing hints. The functions discussed in this section use the
29860 flags and the XSizeHints structure, as defined in the
29861 <X11/Xutil.h> header file and use the WM_NORMAL_HINTS property.
29862
29863 To set the size hints for a given window in its normal state,
29864 use XSetNormalHints. This function has been superseded by
29865 XSetWMNormalHints.
29866
29867 XSetNormalHints(Display *display, Window w, XSizeHints *hints);
29868
29869 display
29870
29871 Specifies the connection to the X server.
29872
29873 w
29874
29875 Specifies the window.
29876
29877 hints
29878
29879 Specifies a pointer to the size hints for the window in its
29880 normal state.
29881
29882 The XSetNormalHints function sets the size hints structure for
29883 the specified window. Applications use XSetNormalHints to
29884 inform the window manager of the size or position desirable for
29885 that window. In addition, an application that wants to move or
29886 resize itself should call XSetNormalHints and specify its new
29887 desired location and size as well as making direct Xlib calls
29888 to move or resize. This is because window managers may ignore
29889 redirected configure requests, but they pay attention to
29890 property changes.
29891
29892 To set size hints, an application not only must assign values
29893 to the appropriate members in the hints structure but also must
29894 set the flags member of the structure to indicate which
29895 information is present and where it came from. A call to
29896 XSetNormalHints is meaningless, unless the flags member is set
29897 to indicate which members of the structure have been assigned
29898 values.
29899
29900 XSetNormalHints can generate BadAlloc and BadWindow errors.
29901
29902 To return the size hints for a window in its normal state, use
29903 XGetNormalHints. This function has been superseded by
29904 XGetWMNormalHints.
29905
29906 Status XGetNormalHints(Display *display, Window w, XSizeHints
29907 *hints_return);
29908
29909 display
29910
29911 Specifies the connection to the X server.
29912
29913 w
29914
29915 Specifies the window.
29916
29917 hints_return
29918
29919 Returns the size hints for the window in its normal state.
29920
29921 The XGetNormalHints function returns the size hints for a
29922 window in its normal state. It returns a nonzero status if it
29923 succeeds or zero if the application specified no normal size
29924 hints for this window.
29925
29926 XGetNormalHints can generate a BadWindow error.
29927
29928 The next two functions set and read the WM_ZOOM_HINTS property.
29929
29930 To set the zoom hints for a window, use XSetZoomHints. This
29931 function is no longer supported by the Inter-Client
29932 Communication Conventions Manual.
29933
29934 XSetZoomHints(Display *display, Window w, XSizeHints *zhints);
29935
29936 display
29937
29938 Specifies the connection to the X server.
29939
29940 w
29941
29942 Specifies the window.
29943
29944 zhints
29945
29946 Specifies a pointer to the zoom hints.
29947
29948 Many window managers think of windows in one of three states:
29949 iconic, normal, or zoomed. The XSetZoomHints function provides
29950 the window manager with information for the window in the
29951 zoomed state.
29952
29953 XSetZoomHints can generate BadAlloc and BadWindow errors.
29954
29955 To read the zoom hints for a window, use XGetZoomHints. This
29956 function is no longer supported by the Inter-Client
29957 Communication Conventions Manual.
29958
29959 Status XGetZoomHints(Display *display, Window w, XSizeHints
29960 *zhints_return);
29961
29962 display
29963
29964 Specifies the connection to the X server.
29965
29966 w
29967
29968 Specifies the window.
29969
29970 zhints_return
29971
29972 Returns the zoom hints.
29973
29974 The XGetZoomHints function returns the size hints for a window
29975 in its zoomed state. It returns a nonzero status if it succeeds
29976 or zero if the application specified no zoom size hints for
29977 this window.
29978
29979 XGetZoomHints can generate a BadWindow error.
29980
29981 To set the value of any property of type WM_SIZE_HINTS, use
29982 XSetSizeHints. This function has been superseded by
29983 XSetWMSizeHints.
29984
29985 XSetSizeHints(Display *display, Window w, XSizeHints *hints,
29986 Atom property);
29987
29988 display
29989
29990 Specifies the connection to the X server.
29991
29992 w
29993
29994 Specifies the window.
29995
29996 hints
29997
29998 Specifies a pointer to the size hints.
29999
30000 property
30001
30002 Specifies the property name.
30003
30004 The XSetSizeHints function sets the XSizeHints structure for
30005 the named property and the specified window. This is used by
30006 XSetNormalHints and XSetZoomHints and can be used to set the
30007 value of any property of type WM_SIZE_HINTS. Thus, it may be
30008 useful if other properties of that type get defined.
30009
30010 XSetSizeHints can generate BadAlloc, BadAtom, and BadWindow
30011 errors.
30012
30013 To read the value of any property of type WM_SIZE_HINTS, use
30014 XGetSizeHints. This function has been superseded by
30015 XGetWMSizeHints.
30016
30017 Status XGetSizeHints(Display *display, Window w, XSizeHints
30018 *hints_return, Atom property);
30019
30020 display
30021
30022 Specifies the connection to the X server.
30023
30024 w
30025
30026 Specifies the window.
30027
30028 hints_return
30029
30030 Returns the size hints.
30031
30032 property
30033
30034 Specifies the property name.
30035
30036 The XGetSizeHints function returns the XSizeHints structure for
30037 the named property and the specified window. This is used by
30038 XGetNormalHints and XGetZoomHints. It also can be used to
30039 retrieve the value of any property of type WM_SIZE_HINTS. Thus,
30040 it may be useful if other properties of that type get defined.
30041 XGetSizeHints returns a nonzero status if a size hint was
30042 defined or zero otherwise.
30043
30044 XGetSizeHints can generate BadAtom and BadWindow errors.
30045
30046Getting and Setting an XStandardColormap Structure
30047
30048 To get the XStandardColormap structure associated with one of
30049 the described atoms, use XGetStandardColormap. This function
30050 has been superseded by XGetRGBColormaps.
30051
30052 Status XGetStandardColormap(Display *display, Window w,
30053 XStandardColormap *colormap_return, Atom property);
30054
30055 display
30056
30057 Specifies the connection to the X server.
30058
30059 w
30060
30061 Specifies the window.
30062
30063 colormap_return
30064
30065 Returns the colormap associated with the specified atom.
30066
30067 property
30068
30069 Specifies the property name.
30070
30071 The XGetStandardColormap function returns the colormap
30072 definition associated with the atom supplied as the property
30073 argument. XGetStandardColormap returns a nonzero status if
30074 successful and zero otherwise. For example, to fetch the
30075 standard GrayScale colormap for a display, you use
30076 XGetStandardColormap with the following syntax:
30077XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP
30078);
30079
30080 See section 14.3 for the semantics of standard colormaps.
30081
30082 XGetStandardColormap can generate BadAtom and BadWindow errors.
30083
30084 To set a standard colormap, use XSetStandardColormap. This
30085 function has been superseded by XSetRGBColormaps.
30086
30087 XSetStandardColormap(Display *display, Window w,
30088 XStandardColormap *colormap, Atom property);
30089
30090 display
30091
30092 Specifies the connection to the X server.
30093
30094 w
30095
30096 Specifies the window.
30097
30098 colormap
30099
30100 Specifies the colormap.
30101
30102 property
30103
30104 Specifies the property name.
30105
30106 The XSetStandardColormap function usually is only used by
30107 window or session managers.
30108
30109 XSetStandardColormap can generate BadAlloc, BadAtom,
30110 BadDrawable, and BadWindow errors.
30111
30112Parsing Window Geometry
30113
30114 To parse window geometry given a user-specified position and a
30115 default position, use XGeometry. This function has been
30116 superseded by XWMGeometry.
30117
30118 int XGeometry(Display *display, int screen, char *position,
30119 char *default_position, unsigned int bwidth, unsigned int
30120 fwidth, unsigned int fheight, int xadder, int yadder, int
30121 *x_return, int *y_return, int *width_return, int
30122 *height_return);
30123
30124 display
30125
30126 Specifies the connection to the X server.
30127
30128 screen
30129
30130 Specifies the screen.
30131
30132 position
30133
30134 default_position
30135
30136 Specify the geometry specifications.
30137
30138 bwidth
30139
30140 Specifies the border width.
30141
30142 fheight
30143
30144 fwidth
30145
30146 Specify the font height and width in pixels (increment size).
30147
30148 xadder
30149
30150 yadder
30151
30152 Specify additional interior padding needed in the window.
30153
30154 x_return
30155
30156 y_return
30157
30158 Return the x and y offsets.
30159
30160 width_return
30161
30162 height_return
30163
30164 Return the width and height determined.
30165
30166 You pass in the border width (bwidth), size of the increments
30167 fwidth and fheight (typically font width and height), and any
30168 additional interior space (xadder and yadder) to make it easy
30169 to compute the resulting size. The XGeometry function returns
30170 the position the window should be placed given a position and a
30171 default position. XGeometry determines the placement of a
30172 window using a geometry specification as specified by
30173 XParseGeometry and the additional information about the window.
30174 Given a fully qualified default geometry specification and an
30175 incomplete geometry specification, XParseGeometry returns a
30176 bitmask value as defined above in the XParseGeometry call, by
30177 using the position argument.
30178
30179 The returned width and height will be the width and height
30180 specified by default_position as overridden by any
30181 user-specified position. They are not affected by fwidth,
30182 fheight, xadder, or yadder. The x and y coordinates are
30183 computed by using the border width, the screen width and
30184 height, padding as specified by xadder and yadder, and the
30185 fheight and fwidth times the width and height from the geometry
30186 specifications.
30187
30188Getting the X Environment Defaults
30189
30190 The XGetDefault function provides a primitive interface to the
30191 resource manager facilities discussed in chapter 15. It is only
30192 useful in very simple applications.
30193
30194 char *XGetDefault(Display *display, char *program, char
30195 *option);
30196
30197 display
30198
30199 Specifies the connection to the X server.
30200
30201 program
30202
30203 Specifies the program name for the Xlib defaults (usually
30204 argv[0] of the main program).
30205
30206 option
30207
30208 Specifies the option name.
30209
30210 The XGetDefault function returns the value of the resource
30211 prog.option, where prog is the program argument with the
30212 directory prefix removed and option must be a single component.
30213 Note that multilevel resources cannot be used with XGetDefault.
30214 The class "Program.Name" is always used for the resource
30215 lookup. If the specified option name does not exist for this
30216 program, XGetDefault returns NULL. The strings returned by
30217 XGetDefault are owned by Xlib and should not be modified or
30218 freed by the client.
30219
30220 If a database has been set with XrmSetDatabase, that database
30221 is used for the lookup. Otherwise, a database is created and is
30222 set in the display (as if by calling XrmSetDatabase). The
30223 database is created in the current locale. To create a
30224 database, XGetDefault uses resources from the RESOURCE_MANAGER
30225 property on the root window of screen zero. If no such property
30226 exists, a resource file in the user's home directory is used.
30227 On a POSIX-conformant system, this file is "$HOME/.Xdefaults".
30228 After loading these defaults, XGetDefault merges additional
30229 defaults specified by the XENVIRONMENT environment variable. If
30230 XENVIRONMENT is defined, it contains a full path name for the
30231 additional resource file. If XENVIRONMENT is not defined,
30232 XGetDefault looks for "$HOME/.Xdefaults-name" , where name
30233 specifies the name of the machine on which the application is
30234 running.
30235
30236X Version 10 Compatibility Functions
30237
30238 You can use the X Version 10 compatibility functions to:
30239 * Draw and fill polygons and curves
30240 * Associate user data with a value
30241
30242Drawing and Filling Polygons and Curves
30243
30244 Xlib provides functions that you can use to draw or fill
30245 arbitrary polygons or curves. These functions are provided
30246 mainly for compatibility with X Version 10 and have no server
30247 support. That is, they call other Xlib functions, not the
30248 server directly. Thus, if you just have straight lines to draw,
30249 using XDrawLines or XDrawSegments is much faster.
30250
30251 The functions discussed here provide all the functionality of
30252 the X Version 10 functions XDraw, XDrawFilled, XDrawPatterned,
30253 XDrawDashed, and XDrawTiled. They are as compatible as possible
30254 given X Version 11's new line-drawing functions. One thing to
30255 note, however, is that VertexDrawLastPoint is no longer
30256 supported. Also, the error status returned is the opposite of
30257 what it was under X Version 10 (this is the X Version 11
30258 standard error status). XAppendVertex and XClearVertexFlag from
30259 X Version 10 also are not supported.
30260
30261 Just how the graphics context you use is set up actually
30262 determines whether you get dashes or not, and so on. Lines are
30263 properly joined if they connect and include the closing of a
30264 closed figure (see XDrawLines). The functions discussed here
30265 fail (return zero) only if they run out of memory or are passed
30266 a Vertex list that has a Vertex with VertexStartClosed set that
30267 is not followed by a Vertex with VertexEndClosed set.
30268
30269 To achieve the effects of the X Version 10 XDraw, XDrawDashed,
30270 and XDrawPatterned, use XDraw.
30271
30272 #include <X11/X10.h>
30273
30274 Status XDraw(Display *display, Drawable d, GC gc, Vertex
30275 *vlist, int vcount);
30276
30277 display
30278
30279 Specifies the connection to the X server.
30280
30281 d
30282
30283 Specifies the drawable.
30284
30285 gc
30286
30287 Specifies the GC.
30288
30289 vlist
30290
30291 Specifies a pointer to the list of vertices that indicate what
30292 to draw.
30293
30294 vcount
30295
30296 Specifies how many vertices are in vlist.
30297
30298 The XDraw function draws an arbitrary polygon or curve. The
30299 figure drawn is defined by the specified list of vertices
30300 (vlist). The points are connected by lines as specified in the
30301 flags in the vertex structure.
30302
30303 Each Vertex, as defined in <X11/X10.h>, is a structure with the
30304 following members:
30305typedef struct _Vertex {
30306 short x,y;
30307 unsigned short flags;
30308} Vertex;
30309
30310 The x and y members are the coordinates of the vertex that are
30311 relative to either the upper left inside corner of the drawable
30312 (if VertexRelative is zero) or the previous vertex (if
30313 VertexRelative is one).
30314
30315 The flags, as defined in <X11/X10.h>, are as follows:
30316VertexRelative 0x0001 /* else absolute */
30317VertexDontDraw 0x0002 /* else draw */
30318VertexCurved 0x0004 /* else straight */
30319VertexStartClosed 0x0008 /* else not */
30320VertexEndClosed 0x0010 /* else not */
30321
30322 * If VertexRelative is not set, the coordinates are absolute
30323 (that is, relative to the drawable's origin). The first
30324 vertex must be an absolute vertex.
30325 * If VertexDontDraw is one, no line or curve is drawn from
30326 the previous vertex to this one. This is analogous to
30327 picking up the pen and moving to another place before
30328 drawing another line.
30329 * If VertexCurved is one, a spline algorithm is used to draw
30330 a smooth curve from the previous vertex through this one to
30331 the next vertex. Otherwise, a straight line is drawn from
30332 the previous vertex to this one. It makes sense to set
30333 VertexCurved to one only if a previous and next vertex are
30334 both defined (either explicitly in the array or through the
30335 definition of a closed curve).
30336 * It is permissible for VertexDontDraw bits and VertexCurved
30337 bits both to be one. This is useful if you want to define
30338 the previous point for the smooth curve but do not want an
30339 actual curve drawing to start until this point.
30340 * If VertexStartClosed is one, then this point marks the
30341 beginning of a closed curve. This vertex must be followed
30342 later in the array by another vertex whose effective
30343 coordinates are identical and that has a VertexEndClosed
30344 bit of one. The points in between form a cycle to determine
30345 predecessor and successor vertices for the spline
30346 algorithm.
30347
30348 This function uses these GC components: function, plane-mask,
30349 line-width, line-style, cap-style, join-style, fill-style,
30350 subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It
30351 also uses these GC mode-dependent components: foreground,
30352 background, tile, stipple, tile-stipple-x-origin,
30353 tile-stipple-y-origin, dash-offset, and dash-list.
30354
30355 To achieve the effects of the X Version 10 XDrawTiled and
30356 XDrawFilled, use XDrawFilled.
30357
30358 #include <X11/X10.h>
30359
30360 Status XDrawFilled(Display *display, Drawable d, GC gc, Vertex
30361 *vlist, int vcount);
30362
30363 display
30364
30365 Specifies the connection to the X server.
30366
30367 d
30368
30369 Specifies the drawable.
30370
30371 gc
30372
30373 Specifies the GC.
30374
30375 vlist
30376
30377 Specifies a pointer to the list of vertices that indicate what
30378 to draw.
30379
30380 vcount
30381
30382 Specifies how many vertices are in vlist.
30383
30384 The XDrawFilled function draws arbitrary polygons or curves and
30385 then fills them.
30386
30387 This function uses these GC components: function, plane-mask,
30388 line-width, line-style, cap-style, join-style, fill-style,
30389 subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It
30390 also uses these GC mode-dependent components: foreground,
30391 background, tile, stipple, tile-stipple-x-origin,
30392 tile-stipple-y-origin, dash-offset, dash-list, fill-style, and
30393 fill-rule.
30394
30395Associating User Data with a Value
30396
30397 These functions have been superseded by the context management
30398 functions (see section 16.10). It is often necessary to
30399 associate arbitrary information with resource IDs. Xlib
30400 provides the XAssocTable functions that you can use to make
30401 such an association. Application programs often need to be able
30402 to easily refer to their own data structures when an event
30403 arrives. The XAssocTable system provides users of the X library
30404 with a method for associating their own data structures with X
30405 resources (Pixmaps, Fonts, Windows, and so on).
30406
30407 An XAssocTable can be used to type X resources. For example,
30408 the user may want to have three or four types of windows, each
30409 with different properties. This can be accomplished by
30410 associating each X window ID with a pointer to a window
30411 property data structure defined by the user. A generic type has
30412 been defined in the X library for resource IDs. It is called an
30413 XID.
30414
30415 There are a few guidelines that should be observed when using
30416 an XAssocTable :
30417 * All XIDs are relative to the specified display.
30418 * Because of the hashing scheme used by the association
30419 mechanism, the following rules for determining the size of
30420 a XAssocTable should be followed. Associations will be made
30421 and looked up more efficiently if the table size (number of
30422 buckets in the hashing system) is a power of two and if
30423 there are not more than 8 XIDs per bucket.
30424
30425 To return a pointer to a new XAssocTable, use
30426 XCreateAssocTable.
30427
30428 XAssocTable *XCreateAssocTable(int size);
30429
30430 size
30431
30432 Specifies the number of buckets in the hash system of
30433 XAssocTable.
30434
30435 The size argument specifies the number of buckets in the hash
30436 system of XAssocTable. For reasons of efficiency the number of
30437 buckets should be a power of two. Some size suggestions might
30438 be: use 32 buckets per 100 objects, and a reasonable maximum
30439 number of objects per buckets is 8. If an error allocating
30440 memory for the XAssocTable occurs, a NULL pointer is returned.
30441
30442 To create an entry in a given XAssocTable, use XMakeAssoc.
30443
30444 XMakeAssoc(Display *display, XAssocTable *table, XID x_id, char
30445 *data);
30446
30447 display
30448
30449 Specifies the connection to the X server.
30450
30451 table
30452
30453 Specifies the assoc table.
30454
30455 x_id
30456
30457 Specifies the X resource ID.
30458
30459 data
30460
30461 Specifies the data to be associated with the X resource ID.
30462
30463 The XMakeAssoc function inserts data into an XAssocTable keyed
30464 on an XID. Data is inserted into the table only once. Redundant
30465 inserts are ignored. The queue in each association bucket is
30466 sorted from the lowest XID to the highest XID.
30467
30468 To obtain data from a given XAssocTable, use XLookUpAssoc.
30469
30470 char *XLookUpAssoc(Display *display, XAssocTable *table, XID
30471 x_id);
30472
30473 display
30474
30475 Specifies the connection to the X server.
30476
30477 table
30478
30479 Specifies the assoc table.
30480
30481 x_id
30482
30483 Specifies the X resource ID.
30484
30485 The XLookUpAssoc function retrieves the data stored in an
30486 XAssocTable by its XID. If an appropriately matching XID can be
30487 found in the table, XLookUpAssoc returns the data associated
30488 with it. If the x_id cannot be found in the table, it returns
30489 NULL.
30490
30491 To delete an entry from a given XAssocTable, use XDeleteAssoc.
30492
30493 XDeleteAssoc(Display *display, XAssocTable *table, XID x_id);
30494
30495 display
30496
30497 Specifies the connection to the X server.
30498
30499 table
30500
30501 Specifies the assoc table.
30502
30503 x_id
30504
30505 Specifies the X resource ID.
30506
30507 The XDeleteAssoc function deletes an association in an
30508 XAssocTable keyed on its XID. Redundant deletes (and deletes of
30509 nonexistent XIDs) are ignored. Deleting associations in no way
30510 impairs the performance of an XAssocTable.
30511
30512 To free the memory associated with a given XAssocTable, use
30513 XDestroyAssocTable.
30514
30515 XDestroyAssocTable(XAssocTable *table);
30516
30517 table
30518
30519 Specifies the assoc table.
30520
30521Glossary
30522
30523 Access control list
30524 X maintains a list of hosts from which client programs
30525 can be run. By default, only programs on the local host
30526 and hosts specified in an initial list read by the
30527 server can use the display. This access control list can
30528 be changed by clients on the local host. Some server
30529 implementations can also implement other authorization
30530 mechanisms in addition to or in place of this mechanism.
30531 The action of this mechanism can be conditional based on
30532 the authorization protocol name and data received by the
30533 server at connection setup.
30534
30535 Active grab
30536 A grab is active when the pointer or keyboard is
30537 actually owned by the single grabbing client.
30538
30539 Ancestors
30540 If W is an inferior of A, then A is an ancestor of W.
30541
30542 Atom
30543 An atom is a unique ID corresponding to a string name.
30544 Atoms are used to identify properties, types, and
30545 selections.
30546
30547 Background
30548 An InputOutput window can have a background, which is
30549 defined as a pixmap. When regions of the window have
30550 their contents lost or invalidated, the server
30551 automatically tiles those regions with the background.
30552
30553 Backing store
30554 When a server maintains the contents of a window, the
30555 pixels saved off-screen are known as a backing store.
30556
30557 Base font name
30558 A font name used to select a family of fonts whose
30559 members may be encoded in various charsets. The
30560 CharSetRegistry and CharSetEncoding fields of an XLFD
30561 name identify the charset of the font. A base font name
30562 may be a full XLFD name, with all fourteen '-'
30563 delimiters, or an abbreviated XLFD name containing only
30564 the first 12 fields of an XLFD name, up to but not
30565 including CharSetRegistry, with or without the
30566 thirteenth '-', or a non-XLFD name. Any XLFD fields may
30567 contain wild cards.
30568
30569 When creating an XFontSet, Xlib accepts from the client
30570 a list of one or more base font names which select one
30571 or more font families. They are combined with charset
30572 names obtained from the encoding of the locale to load
30573 the fonts required to render text.
30574
30575 Bit gravity
30576 When a window is resized, the contents of the window are
30577 not necessarily discarded. It is possible to request
30578 that the server relocate the previous contents to some
30579 region of the window (though no guarantees are made).
30580 This attraction of window contents for some location of
30581 a window is known as bit gravity.
30582
30583 Bit plane
30584 When a pixmap or window is thought of as a stack of
30585 bitmaps, each bitmap is called a bit plane or plane.
30586
30587 Bitmap
30588 A bitmap is a pixmap of depth one.
30589
30590 Border
30591 An InputOutput window can have a border of equal
30592 thickness on all four sides of the window. The contents
30593 of the border are defined by a pixmap, and the server
30594 automatically maintains the contents of the border.
30595 Exposure events are never generated for border regions.
30596
30597 Button grabbing
30598 Buttons on the pointer can be passively grabbed by a
30599 client. When the button is pressed, the pointer is then
30600 actively grabbed by the client.
30601
30602 Byte order
30603 For image (pixmap/bitmap) data, the server defines the
30604 byte order, and clients with different native byte
30605 ordering must swap bytes as necessary. For all other
30606 parts of the protocol, the client defines the byte
30607 order, and the server swaps bytes as necessary.
30608
30609 Character
30610 A member of a set of elements used for the organization,
30611 control, or representation of text (ISO2022, as adapted
30612 by XPG3). Note that in ISO2022 terms, a character is not
30613 bound to a coded value until it is identified as part of
30614 a coded character set.
30615
30616 Character glyph
30617 The abstract graphical symbol for a character. Character
30618 glyphs may or may not map one-to-one to font glyphs, and
30619 may be context-dependent, varying with the adjacent
30620 characters. Multiple characters may map to a single
30621 character glyph.
30622
30623 Character set
30624 A collection of characters.
30625
30626 Charset
30627 An encoding with a uniform, state-independent mapping
30628 from characters to codepoints. A coded character set.
30629
30630 For display in X, there can be a direct mapping from a
30631 charset to one font, if the width of all characters in
30632 the charset is either one or two bytes. A text string
30633 encoded in an encoding such as Shift-JIS cannot be
30634 passed directly to the X server, because the text
30635 imaging requests accept only single-width charsets
30636 (either 8 or 16 bits). Charsets which meet these
30637 restrictions can serve as ``font charsets''. Font
30638 charsets strictly speaking map font indices to font
30639 glyphs, not characters to character glyphs.
30640
30641 Note that a single font charset is sometimes used as the
30642 encoding of a locale, for example, ISO8859-1.
30643
30644 Children
30645 The children of a window are its first-level subwindows.
30646
30647 Class
30648 Windows can be of different classes or types. See the
30649 entries for InputOnly and InputOutput windows for
30650 further information about valid window types.
30651
30652 Client
30653 An application program connects to the window system
30654 server by some interprocess communication (IPC) path,
30655 such as a TCP connection or a shared memory buffer. This
30656 program is referred to as a client of the window system
30657 server. More precisely, the client is the IPC path
30658 itself. A program with multiple paths open to the server
30659 is viewed as multiple clients by the protocol. Resource
30660 lifetimes are controlled by connection lifetimes, not by
30661 program lifetimes.
30662
30663 Clipping region
30664 In a graphics context, a bitmap or list of rectangles
30665 can be specified to restrict output to a particular
30666 region of the window. The image defined by the bitmap or
30667 rectangles is called a clipping region.
30668
30669 Coded character
30670 A character bound to a codepoint.
30671
30672 Coded character set
30673 A set of unambiguous rules that establishes a character
30674 set and the one-to-one relationship between each
30675 character of the set and its bit representation.
30676 (ISO2022, as adapted by XPG3) A definition of a
30677 one-to-one mapping of a set of characters to a set of
30678 codepoints.
30679
30680 Codepoint
30681 The coded representation of a single character in a
30682 coded character set.
30683
30684 Colormap
30685 A colormap consists of a set of entries defining color
30686 values. The colormap associated with a window is used to
30687 display the contents of the window; each pixel value
30688 indexes the colormap to produce an RGB value that drives
30689 the guns of a monitor. Depending on hardware
30690 limitations, one or more colormaps can be installed at
30691 one time so that windows associated with those maps
30692 display with true colors.
30693
30694 Connection
30695 The IPC path between the server and client program is
30696 known as a connection. A client program typically (but
30697 not necessarily) has one connection to the server over
30698 which requests and events are sent.
30699
30700 Containment
30701 A window contains the pointer if the window is viewable
30702 and the hotspot of the cursor is within a visible region
30703 of the window or a visible region of one of its
30704 inferiors. The border of the window is included as part
30705 of the window for containment. The pointer is in a
30706 window if the window contains the pointer but no
30707 inferior contains the pointer.
30708
30709 Coordinate system
30710 The coordinate system has X horizontal and Y vertical,
30711 with the origin [0, 0] at the upper left. Coordinates
30712 are integral and coincide with pixel centers. Each
30713 window and pixmap has its own coordinate system. For a
30714 window, the origin is inside the border at the inside
30715 upper-left corner.
30716
30717 Cursor
30718 A cursor is the visible shape of the pointer on a
30719 screen. It consists of a hotspot, a source bitmap, a
30720 shape bitmap, and a pair of colors. The cursor defined
30721 for a window controls the visible appearance when the
30722 pointer is in that window.
30723
30724 Depth
30725 The depth of a window or pixmap is the number of bits
30726 per pixel it has. The depth of a graphics context is the
30727 depth of the drawables it can be used in conjunction
30728 with graphics output.
30729
30730 Device
30731 Keyboards, mice, tablets, track-balls, button boxes, and
30732 so on are all collectively known as input devices.
30733 Pointers can have one or more buttons (the most common
30734 number is three). The core protocol only deals with two
30735 devices: the keyboard and the pointer.
30736
30737 DirectColor
30738 DirectColor is a class of colormap in which a pixel
30739 value is decomposed into three separate subfields for
30740 indexing. The first subfield indexes an array to produce
30741 red intensity values. The second subfield indexes a
30742 second array to produce blue intensity values. The third
30743 subfield indexes a third array to produce green
30744 intensity values. The RGB (red, green, and blue) values
30745 in the colormap entry can be changed dynamically.
30746
30747 Display
30748 A server, together with its screens and input devices,
30749 is called a display. The Xlib Display structure contains
30750 all information about the particular display and its
30751 screens as well as the state that Xlib needs to
30752 communicate with the display over a particular
30753 connection.
30754
30755 Drawable
30756 Both windows and pixmaps can be used as sources and
30757 destinations in graphics operations. These windows and
30758 pixmaps are collectively known as drawables. However, an
30759 InputOnly window cannot be used as a source or
30760 destination in a graphics operation.
30761
30762 Encoding
30763 A set of unambiguous rules that establishes a character
30764 set and a relationship between the characters and their
30765 representations. The character set does not have to be
30766 fixed to a finite pre-defined set of characters. The
30767 representations do not have to be of uniform length.
30768 Examples are an ISO2022 graphic set, a state-independent
30769 or state-dependent combination of graphic sets, possibly
30770 including control sets, and the X Compound Text
30771 encoding.
30772
30773 In X, encodings are identified by a string which appears
30774 as: the CharSetRegistry and CharSetEncoding components
30775 of an XLFD name; the name of a charset of the locale for
30776 which a font could not be found; or an atom which
30777 identifies the encoding of a text property or which
30778 names an encoding for a text selection target type.
30779 Encoding names should be composed of characters from the
30780 X Portable Character Set.
30781
30782 Escapement
30783 The escapement of a string is the distance in pixels in
30784 the primary draw direction from the drawing origin to
30785 the origin of the next character (that is, the one
30786 following the given string) to be drawn.
30787
30788 Event
30789 Clients are informed of information asynchronously by
30790 means of events. These events can be either
30791 asynchronously generated from devices or generated as
30792 side effects of client requests. Events are grouped into
30793 types. The server never sends an event to a client
30794 unless the client has specifically asked to be informed
30795 of that type of event. However, clients can force events
30796 to be sent to other clients. Events are typically
30797 reported relative to a window.
30798
30799 Event mask
30800 Events are requested relative to a window. The set of
30801 event types a client requests relative to a window is
30802 described by using an event mask.
30803
30804 Event propagation
30805 Device-related events propagate from the source window
30806 to ancestor windows until some client has expressed
30807 interest in handling that type of event or until the
30808 event is discarded explicitly.
30809
30810 Event source
30811 The deepest viewable window that the pointer is in is
30812 called the source of a device-related event.
30813
30814 Event synchronization
30815 There are certain race conditions possible when
30816 demultiplexing device events to clients (in particular,
30817 deciding where pointer and keyboard events should be
30818 sent when in the middle of window management
30819 operations). The event synchronization mechanism allows
30820 synchronous processing of device events.
30821
30822 Exposure event
30823 Servers do not guarantee to preserve the contents of
30824 windows when windows are obscured or reconfigured.
30825 Exposure events are sent to clients to inform them when
30826 contents of regions of windows have been lost.
30827
30828 Extension
30829 Named extensions to the core protocol can be defined to
30830 extend the system. Extensions to output requests,
30831 resources, and event types are all possible and
30832 expected.
30833
30834 Font
30835 A font is an array of glyphs (typically characters). The
30836 protocol does no translation or interpretation of
30837 character sets. The client simply indicates values used
30838 to index the glyph array. A font contains additional
30839 metric information to determine interglyph and interline
30840 spacing.
30841
30842 Font glyph
30843 The abstract graphical symbol for an index into a font.
30844
30845 Frozen events
30846 Clients can freeze event processing during keyboard and
30847 pointer grabs.
30848
30849 GC
30850 GC is an abbreviation for graphics context. See Graphics
30851 context.
30852
30853 Glyph
30854 An identified abstract graphical symbol independent of
30855 any actual image. (ISO/IEC/DIS 9541-1) An abstract
30856 visual representation of a graphic character, not bound
30857 to a codepoint.
30858
30859 Glyph image
30860 An image of a glyph, as obtained from a glyph
30861 representation displayed on a presentation surface.
30862 (ISO/IEC/DIS 9541-1)
30863
30864 Grab
30865 Keyboard keys, the keyboard, pointer buttons, the
30866 pointer, and the server can be grabbed for exclusive use
30867 by a client. In general, these facilities are not
30868 intended to be used by normal applications but are
30869 intended for various input and window managers to
30870 implement various styles of user interfaces.
30871
30872 Graphics context
30873 Various information for graphics output is stored in a
30874 graphics context (GC), such as foreground pixel,
30875 background pixel, line width, clipping region, and so
30876 on. A graphics context can only be used with drawables
30877 that have the same root and the same depth as the
30878 graphics context.
30879
30880 Gravity
30881 The contents of windows and windows themselves have a
30882 gravity, which determines how the contents move when a
30883 window is resized. See Bit gravity and Window gravity.
30884
30885 GrayScale
30886 GrayScale can be viewed as a degenerate case of
30887 PseudoColor, in which the red, green, and blue values in
30888 any given colormap entry are equal and thus, produce
30889 shades of gray. The gray values can be changed
30890 dynamically.
30891
30892 Host Portable Character Encoding
30893 The encoding of the X Portable Character Set on the
30894 host. The encoding itself is not defined by this
30895 standard, but the encoding must be the same in all
30896 locales supported by Xlib on the host. If a string is
30897 said to be in the Host Portable Character Encoding, then
30898 it only contains characters from the X Portable
30899 Character Set, in the host encoding.
30900
30901 Hotspot
30902 A cursor has an associated hotspot, which defines the
30903 point in the cursor corresponding to the coordinates
30904 reported for the pointer.
30905
30906 Identifier
30907 An identifier is a unique value associated with a
30908 resource that clients use to name that resource. The
30909 identifier can be used over any connection to name the
30910 resource.
30911
30912 Inferiors
30913 The inferiors of a window are all of the subwindows
30914 nested below it: the children, the children's children,
30915 and so on.
30916
30917 Input focus
30918 The input focus is usually a window defining the scope
30919 for processing of keyboard input. If a generated
30920 keyboard event usually would be reported to this window
30921 or one of its inferiors, the event is reported as usual.
30922 Otherwise, the event is reported with respect to the
30923 focus window. The input focus also can be set such that
30924 all keyboard events are discarded and such that the
30925 focus window is dynamically taken to be the root window
30926 of whatever screen the pointer is on at each keyboard
30927 event.
30928
30929 Input manager
30930 Control over keyboard input is typically provided by an
30931 input manager client, which usually is part of a window
30932 manager.
30933
30934 InputOnly window
30935 An InputOnly window is a window that cannot be used for
30936 graphics requests. InputOnly windows are invisible and
30937 are used to control such things as cursors, input event
30938 generation, and grabbing. InputOnly windows cannot have
30939 InputOutput windows as inferiors.
30940
30941 InputOutput window
30942 An InputOutput window is the normal kind of window that
30943 is used for both input and output. InputOutput windows
30944 can have both InputOutput and InputOnly windows as
30945 inferiors.
30946
30947 Internationalization
30948 The process of making software adaptable to the
30949 requirements of different native languages, local
30950 customs, and character string encodings. Making a
30951 computer program adaptable to different locales without
30952 program source modifications or recompilation.
30953
30954 ISO2022
30955 ISO standard for code extension techniques for 7-bit and
30956 8-bit coded character sets.
30957
30958 Key grabbing
30959 Keys on the keyboard can be passively grabbed by a
30960 client. When the key is pressed, the keyboard is then
30961 actively grabbed by the client.
30962
30963 Keyboard grabbing
30964 A client can actively grab control of the keyboard, and
30965 key events will be sent to that client rather than the
30966 client the events would normally have been sent to.
30967
30968 Keysym
30969 An encoding of a symbol on a keycap on a keyboard.
30970
30971 Latin-1
30972 The coded character set defined by the ISO8859-1
30973 standard.
30974
30975 Latin Portable Character Encoding
30976 The encoding of the X Portable Character Set using the
30977 Latin-1 codepoints plus ASCII control characters. If a
30978 string is said to be in the Latin Portable Character
30979 Encoding, then it only contains characters from the X
30980 Portable Character Set, not all of Latin-1.
30981
30982 Locale
30983 The international environment of a computer program
30984 defining the ``localized'' behavior of that program at
30985 run-time. This information can be established from one
30986 or more sets of localization data. ANSI C defines
30987 locale-specific processing by C system library calls.
30988 See ANSI C and the X/Open Portability Guide
30989 specifications for more details. In this specification,
30990 on implementations that conform to the ANSI C library,
30991 the ``current locale'' is the current setting of the
30992 LC_CTYPE setlocale category. Associated with each locale
30993 is a text encoding. When text is processed in the
30994 context of a locale, the text must be in the encoding of
30995 the locale. The current locale affects Xlib in its:
30996
30997 + Encoding and processing of input method text
30998 + Encoding of resource files and values
30999 + Encoding and imaging of text strings
31000 + Encoding and decoding for inter-client text
31001 communication
31002
31003 Locale name
31004 The identifier used to select the desired locale for the
31005 host C library and X library functions. On ANSI C
31006 library compliant systems, the locale argument to the
31007 setlocale function.
31008
31009 Localization
31010 The process of establishing information within a
31011 computer system specific to the operation of particular
31012 native languages, local customs and coded character
31013 sets. (XPG3)
31014
31015 Mapped
31016 A window is said to be mapped if a map call has been
31017 performed on it. Unmapped windows and their inferiors
31018 are never viewable or visible.
31019
31020 Modifier keys
31021 Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple,
31022 CapsLock, ShiftLock, and similar keys are called
31023 modifier keys.
31024
31025 Monochrome
31026 Monochrome is a special case of StaticGray in which
31027 there are only two colormap entries.
31028
31029 Multibyte
31030 A character whose codepoint is stored in more than one
31031 byte; any encoding which can contain multibyte
31032 characters; text in a multibyte encoding. The ``char *''
31033 null-terminated string datatype in ANSI C. Note that
31034 references in this document to multibyte strings imply
31035 only that the strings may contain multibyte characters.
31036
31037 Obscure
31038 A window is obscured if some other window obscures it. A
31039 window can be partially obscured and so still have
31040 visible regions. Window A obscures window B if both are
31041 viewable InputOutput windows, if A is higher in the
31042 global stacking order, and if the rectangle defined by
31043 the outside edges of A intersects the rectangle defined
31044 by the outside edges of B. Note the distinction between
31045 obscures and occludes. Also note that window borders are
31046 included in the calculation.
31047
31048 Occlude
31049 A window is occluded if some other window occludes it.
31050 Window A occludes window B if both are mapped, if A is
31051 higher in the global stacking order, and if the
31052 rectangle defined by the outside edges of A intersects
31053 the rectangle defined by the outside edges of B. Note
31054 the distinction between occludes and obscures. Also note
31055 that window borders are included in the calculation and
31056 that InputOnly windows never obscure other windows but
31057 can occlude other windows.
31058
31059 Padding
31060 Some padding bytes are inserted in the data stream to
31061 maintain alignment of the protocol requests on natural
31062 boundaries. This increases ease of portability to some
31063 machine architectures.
31064
31065 Parent window
31066 If C is a child of P, then P is the parent of C.
31067
31068 Passive grab
31069 Grabbing a key or button is a passive grab. The grab
31070 activates when the key or button is actually pressed.
31071
31072 Pixel value
31073 A pixel is an N-bit value, where N is the number of bit
31074 planes used in a particular window or pixmap (that is,
31075 is the depth of the window or pixmap). A pixel in a
31076 window indexes a colormap to derive an actual color to
31077 be displayed.
31078
31079 Pixmap
31080 A pixmap is a three-dimensional array of bits. A pixmap
31081 is normally thought of as a two-dimensional array of
31082 pixels, where each pixel can be a value from 0 to 2^N-1,
31083 and where N is the depth (z axis) of the pixmap. A
31084 pixmap can also be thought of as a stack of N bitmaps. A
31085 pixmap can only be used on the screen that it was
31086 created in.
31087
31088 Plane
31089 When a pixmap or window is thought of as a stack of
31090 bitmaps, each bitmap is called a plane or bit plane.
31091
31092 Plane mask
31093 Graphics operations can be restricted to only affect a
31094 subset of bit planes of a destination. A plane mask is a
31095 bit mask describing which planes are to be modified. The
31096 plane mask is stored in a graphics context.
31097
31098 Pointer
31099 The pointer is the pointing device currently attached to
31100 the cursor and tracked on the screens.
31101
31102 Pointer grabbing
31103 A client can actively grab control of the pointer. Then
31104 button and motion events will be sent to that client
31105 rather than the client the events would normally have
31106 been sent to.
31107
31108 Pointing device
31109 A pointing device is typically a mouse, tablet, or some
31110 other device with effective dimensional motion. The core
31111 protocol defines only one visible cursor, which tracks
31112 whatever pointing device is attached as the pointer.
31113
31114 POSIX
31115 Portable Operating System Interface, ISO/IEC 9945-1
31116 (IEEE Std 1003.1).
31117
31118 POSIX Portable Filename Character Set
31119 The set of 65 characters which can be used in naming
31120 files on a POSIX-compliant host that are correctly
31121 processed in all locales. The set is:
31122
31123 a..z A..Z 0..9 ._-
31124
31125 Property
31126 Windows can have associated properties that consist of a
31127 name, a type, a data format, and some data. The protocol
31128 places no interpretation on properties. They are
31129 intended as a general-purpose naming mechanism for
31130 clients. For example, clients might use properties to
31131 share information such as resize hints, program names,
31132 and icon formats with a window manager.
31133
31134 Property list
31135 The property list of a window is the list of properties
31136 that have been defined for the window.
31137
31138 PseudoColor
31139 PseudoColor is a class of colormap in which a pixel
31140 value indexes the colormap entry to produce an
31141 independent RGB value; that is, the colormap is viewed
31142 as an array of triples (RGB values). The RGB values can
31143 be changed dynamically.
31144
31145 Rectangle
31146 A rectangle specified by [x,y,w,h] has an infinitely
31147 thin outline path with corners at [x,y], [x+w,y],
31148 [x+w,y+h], and [x, y+h]. When a rectangle is filled, the
31149 lower-right edges are not drawn. For example, if w=h=0,
31150 nothing would be drawn. For w=h=1, a single pixel would
31151 be drawn.
31152
31153 Redirecting control
31154 Window managers (or client programs) may enforce window
31155 layout policy in various ways. When a client attempts to
31156 change the size or position of a window, the operation
31157 may be redirected to a specified client rather than the
31158 operation actually being performed.
31159
31160 Reply
31161 Information requested by a client program using the X
31162 protocol is sent back to the client with a reply. Both
31163 events and replies are multiplexed on the same
31164 connection. Most requests do not generate replies, but
31165 some requests generate multiple replies.
31166
31167 Request
31168 A command to the server is called a request. It is a
31169 single block of data sent over a connection.
31170
31171 Resource
31172 Windows, pixmaps, cursors, fonts, graphics contexts, and
31173 colormaps are known as resources. They all have unique
31174 identifiers associated with them for naming purposes.
31175 The lifetime of a resource usually is bounded by the
31176 lifetime of the connection over which the resource was
31177 created.
31178
31179 RGB values
31180 RGB values are the red, green, and blue intensity values
31181 that are used to define a color. These values are always
31182 represented as 16-bit, unsigned numbers, with 0 the
31183 minimum intensity and 65535 the maximum intensity. The X
31184 server scales these values to match the display
31185 hardware.
31186
31187 Root
31188 The root of a pixmap or graphics context is the same as
31189 the root of whatever drawable was used when the pixmap
31190 or GC was created. The root of a window is the root
31191 window under which the window was created.
31192
31193 Root window
31194 Each screen has a root window covering it. The root
31195 window cannot be reconfigured or unmapped, but otherwise
31196 it acts as a full-fledged window. A root window has no
31197 parent.
31198
31199 Save set
31200 The save set of a client is a list of other clients'
31201 windows that, if they are inferiors of one of the
31202 client's windows at connection close, should not be
31203 destroyed and that should be remapped if currently
31204 unmapped. Save sets are typically used by window
31205 managers to avoid lost windows if the manager should
31206 terminate abnormally.
31207
31208 Scanline
31209 A scanline is a list of pixel or bit values viewed as a
31210 horizontal row (all values having the same y coordinate)
31211 of an image, with the values ordered by increasing the x
31212 coordinate.
31213
31214 Scanline order
31215 An image represented in scanline order contains
31216 scanlines ordered by increasing the y coordinate.
31217
31218 Screen
31219 A server can provide several independent screens, which
31220 typically have physically independent monitors. This
31221 would be the expected configuration when there is only a
31222 single keyboard and pointer shared among the screens. A
31223 Screen structure contains the information about that
31224 screen and is linked to the Display structure.
31225
31226 Selection
31227 A selection can be thought of as an indirect property
31228 with dynamic type. That is, rather than having the
31229 property stored in the X server, it is maintained by
31230 some client (the owner). A selection is global and is
31231 thought of as belonging to the user and being maintained
31232 by clients, rather than being private to a particular
31233 window subhierarchy or a particular set of clients. When
31234 a client asks for the contents of a selection, it
31235 specifies a selection target type, which can be used to
31236 control the transmitted representation of the contents.
31237 For example, if the selection is ``the last thing the
31238 user clicked on,'' and that is currently an image, then
31239 the target type might specify whether the contents of
31240 the image should be sent in XY format or Z format.
31241
31242 The target type can also be used to control the class of
31243 contents transmitted; for example, asking for the
31244 ``looks'' (fonts, line spacing, indentation, and so
31245 forth) of a paragraph selection, rather than the text of
31246 the paragraph. The target type can also be used for
31247 other purposes. The protocol does not constrain the
31248 semantics.
31249
31250 Server
31251 The server, which is also referred to as the X server,
31252 provides the basic windowing mechanism. It handles IPC
31253 connections from clients, multiplexes graphics requests
31254 onto the screens, and demultiplexes input back to the
31255 appropriate clients.
31256
31257 Server grabbing
31258 The server can be grabbed by a single client for
31259 exclusive use. This prevents processing of any requests
31260 from other client connections until the grab is
31261 completed. This is typically only a transient state for
31262 such things as rubber-banding, pop-up menus, or
31263 executing requests indivisibly.
31264
31265 Shift sequence
31266 ISO2022 defines control characters and escape sequences
31267 which temporarily (single shift) or permanently (locking
31268 shift) cause a different character set to be in effect
31269 (``invoking'' a character set).
31270
31271 Sibling
31272 Children of the same parent window are known as sibling
31273 windows.
31274
31275 Stacking order
31276 Sibling windows, similar to sheets of paper on a desk,
31277 can stack on top of each other. Windows above both
31278 obscure and occlude lower windows. The relationship
31279 between sibling windows is known as the stacking order.
31280
31281 State-dependent encoding
31282 An encoding in which an invocation of a charset can
31283 apply to multiple characters in sequence. A
31284 state-dependent encoding begins in an ``initial state''
31285 and enters other ``shift states'' when specific ``shift
31286 sequences'' are encountered in the byte sequence. In
31287 ISO2022 terms, this means use of locking shifts, not
31288 single shifts.
31289
31290 State-independent encoding
31291 Any encoding in which the invocations of the charsets
31292 are fixed, or span only a single character. In ISO2022
31293 terms, this means use of at most single shifts, not
31294 locking shifts.
31295
31296 StaticColor
31297 StaticColor can be viewed as a degenerate case of
31298 PseudoColor in which the RGB values are predefined and
31299 read-only.
31300
31301 StaticGray
31302 StaticGray can be viewed as a degenerate case of
31303 GrayScale in which the gray values are predefined and
31304 read-only. The values are typically linear or
31305 near-linear increasing ramps.
31306
31307 Status
31308 Many Xlib functions return a success status. If the
31309 function does not succeed, however, its arguments are
31310 not disturbed.
31311
31312 Stipple
31313 A stipple pattern is a bitmap that is used to tile a
31314 region to serve as an additional clip mask for a fill
31315 operation with the foreground color.
31316
31317 STRING encoding
31318 Latin-1, plus tab and newline.
31319
31320 String Equivalence
31321 Two ISO Latin-1 STRING8 values are considered equal if
31322 they are the same length and if corresponding bytes are
31323 either equal or are equivalent as follows: decimal
31324 values 65 to 90 inclusive (characters ``A'' to ``Z'')
31325 are pairwise equivalent to decimal values 97 to 122
31326 inclusive (characters ``a'' to ``z''), decimal values
31327 192 to 214 inclusive (characters ``A grave'' to ``O
31328 diaeresis'') are pairwise equivalent to decimal values
31329 224 to 246 inclusive (characters ``a grave'' to ``o
31330 diaeresis''), and decimal values 216 to 222 inclusive
31331 (characters ``O oblique'' to ``THORN'') are pairwise
31332 equivalent to decimal values 246 to 254 inclusive
31333 (characters ``o oblique'' to ``thorn'').
31334
31335 Tile
31336 A pixmap can be replicated in two dimensions to tile a
31337 region. The pixmap itself is also known as a tile.
31338
31339 Timestamp
31340 A timestamp is a time value expressed in milliseconds.
31341 It is typically the time since the last server reset.
31342 Timestamp values wrap around (after about 49.7 days).
31343 The server, given its current time is represented by
31344 timestamp T, always interprets timestamps from clients
31345 by treating half of the timestamp space as being earlier
31346 in time than T and half of the timestamp space as being
31347 later in time than T. One timestamp value, represented
31348 by the constant CurrentTime, is never generated by the
31349 server. This value is reserved for use in requests to
31350 represent the current server time.
31351
31352 TrueColor
31353 TrueColor can be viewed as a degenerate case of
31354 DirectColor in which the subfields in the pixel value
31355 directly encode the corresponding RGB values. That is,
31356 the colormap has predefined read-only RGB values. The
31357 values are typically linear or near-linear increasing
31358 ramps.
31359
31360 Type
31361 A type is an arbitrary atom used to identify the
31362 interpretation of property data. Types are completely
31363 uninterpreted by the server. They are solely for the
31364 benefit of clients. X predefines type atoms for many
31365 frequently used types, and clients also can define new
31366 types.
31367
31368 Viewable
31369 A window is viewable if it and all of its ancestors are
31370 mapped. This does not imply that any portion of the
31371 window is actually visible. Graphics requests can be
31372 performed on a window when it is not viewable, but
31373 output will not be retained unless the server is
31374 maintaining backing store.
31375
31376 Visible
31377 A region of a window is visible if someone looking at
31378 the screen can actually see it; that is, the window is
31379 viewable and the region is not occluded by any other
31380 window.
31381
31382 Whitespace
31383 Any spacing character. On implementations that conform
31384 to the ANSI C library, whitespace is any character for
31385 which isspace returns true.
31386
31387 Window gravity
31388 When windows are resized, subwindows may be repositioned
31389 automatically relative to some position in the window.
31390 This attraction of a subwindow to some part of its
31391 parent is known as window gravity.
31392
31393 Window manager
31394 Manipulation of windows on the screen and much of the
31395 user interface (policy) is typically provided by a
31396 window manager client.
31397
31398 X Portable Character Set
31399 A basic set of 97 characters which are assumed to exist
31400 in all locales supported by Xlib. This set contains the
31401 following characters:
31402
31403 a..z A..Z 0..9
31404 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
31405 <space>, <tab>, and <newline>
31406
31407
31408 This is the left/lower half (also called the G0 set) of
31409 the graphic character set of ISO8859-1 plus <space>,
31410 <tab>, and <newline>. It is also the set of graphic
31411 characters in 7-bit ASCII plus the same three control
31412 characters. The actual encoding of these characters on
31413 the host is system dependent; see the Host Portable
31414 Character Encoding.
31415
31416 XLFD
31417 The X Logical Font Description Conventions that define a
31418 standard syntax for structured font names.
31419
31420 XY format
31421 The data for a pixmap is said to be in XY format if it
31422 is organized as a set of bitmaps representing individual
31423 bit planes with the planes appearing from
31424 most-significant to least-significant bit order.
31425
31426 Z format
31427 The data for a pixmap is said to be in Z format if it is
31428 organized as a set of pixel values in scanline order.
31429
31430Index
31431
31432Symbols
31433
31434 _XAllocScratch, Allocating and Deallocating Memory
31435 _XAllocTemp, Allocating and Deallocating Memory
31436 _Xdebug, Enabling or Disabling Synchronization
31437 _XFlushGCCache, GC Caching
31438 _XFreeTemp, Allocating and Deallocating Memory
31439 _XReply, Replies
31440 _XSetLastRequestRead, Hooks into the Library
31441
31442A
31443
31444 Access control list, Controlling Host Access, Glossary
31445 Active grab, Pointer Grabbing, Glossary
31446 Allocation, Allocating and Freeing Color Cells, Allocating and
31447 Freeing Color Cells, Allocating and Freeing Color Cells,
31448 Allocating and Freeing Color Cells, Allocating and
31449 Freeing Color Cells, Allocating and Freeing Color Cells,
31450 Allocating and Freeing Color Cells
31451
31452 colormap, Allocating and Freeing Color Cells
31453 read-only colormap cells, Allocating and Freeing Color
31454 Cells, Allocating and Freeing Color Cells,
31455 Allocating and Freeing Color Cells, Allocating and
31456 Freeing Color Cells
31457
31458 read/write colormap cells, Allocating and Freeing Color
31459 Cells
31460
31461 read/write colormap planes, Allocating and Freeing Color
31462 Cells
31463
31464 AllPlanes, Display Macros
31465 Ancestors, Glossary
31466 Arcs, Drawing Single and Multiple Arcs, Filling Single and
31467 Multiple Arcs
31468
31469 drawing, Drawing Single and Multiple Arcs
31470 filling, Filling Single and Multiple Arcs
31471
31472 Areas, Clearing Areas, Copying Areas
31473
31474 clearing, Clearing Areas
31475 copying, Copying Areas
31476
31477 Atom, Properties and Atoms, Properties and Atoms, Properties
31478 and Atoms, Properties and Atoms, Properties and Atoms,
31479 Properties and Atoms, Properties and Atoms, Glossary
31480
31481 getting name, Properties and Atoms, Properties and Atoms
31482 interning, Properties and Atoms, Properties and Atoms
31483 predefined, Properties and Atoms
31484
31485 Authentication, Controlling Host Access
31486
31487B
31488
31489 Background, Glossary
31490 Backing store, Glossary
31491 BadAccess, Using the Default Error Handlers
31492 BadAlloc, Using the Default Error Handlers
31493 BadAtom, Using the Default Error Handlers
31494 BadColor, Using the Default Error Handlers
31495 BadCursor, Using the Default Error Handlers
31496 BadDrawable, Using the Default Error Handlers
31497 BadFont, Using the Default Error Handlers
31498 BadGC, Using the Default Error Handlers
31499 BadIDChoice, Using the Default Error Handlers
31500 BadImplementation, Using the Default Error Handlers
31501 BadLength, Using the Default Error Handlers
31502 BadMatch, Using the Default Error Handlers
31503 BadName, Using the Default Error Handlers
31504 BadPixmap, Using the Default Error Handlers
31505 BadRequest, Using the Default Error Handlers
31506 BadValue, Using the Default Error Handlers
31507 BadWindow, Using the Default Error Handlers
31508 Base font name, Glossary
31509 Bit, Glossary, Glossary
31510
31511 gravity, Glossary
31512 plane, Glossary
31513
31514 Bitmap, Overview of the X Window System, Glossary
31515 BitmapBitOrder, Image Format Functions and Macros
31516 BitmapPad, Image Format Functions and Macros
31517 BitmapUnit, Image Format Functions and Macros
31518 BlackPixel, Display Macros
31519 BlackPixelOfScreen, Screen Information Macros
31520 Bool, Generic Values and Types
31521 Border, Glossary
31522 Button, Pointer Grabbing, Pointer Grabbing, Glossary
31523
31524 grabbing, Pointer Grabbing, Glossary
31525 ungrabbing, Pointer Grabbing
31526
31527 ButtonPress, Keyboard and Pointer Events
31528 ButtonRelease, Keyboard and Pointer Events
31529 Byte, Glossary
31530
31531 order, Glossary
31532
31533C
31534
31535 CallbackPrototype, Input Method Callback Semantics
31536 CCC, Color Conversion Contexts and Gamut Mapping, Color
31537 Conversion Contexts and Gamut Mapping, Color Conversion
31538 Contexts and Gamut Mapping, Color Conversion Context
31539 Functions, Color Conversion Context Functions, Getting
31540 and Setting the Color Conversion Context of a Colormap,
31541 Getting and Setting the Color Conversion Context of a
31542 Colormap, Obtaining the Default Color Conversion
31543 Context, Obtaining the Default Color Conversion Context,
31544 Creating and Freeing a Color Conversion Context,
31545 Creating and Freeing a Color Conversion Context
31546
31547 creation, Creating and Freeing a Color Conversion Context
31548 default, Color Conversion Contexts and Gamut Mapping,
31549 Color Conversion Context Functions, Obtaining the
31550 Default Color Conversion Context, Obtaining the
31551 Default Color Conversion Context
31552
31553 freeing, Creating and Freeing a Color Conversion Context
31554 of colormap, Color Conversion Contexts and Gamut Mapping,
31555 Color Conversion Context Functions, Getting and
31556 Setting the Color Conversion Context of a
31557 Colormap, Getting and Setting the Color Conversion
31558 Context of a Colormap
31559
31560 CellsOfScreen, Screen Information Macros
31561 Changing, Pointer Grabbing
31562
31563 pointer grab, Pointer Grabbing
31564
31565 Character, Glossary
31566 Character glyph, Glossary
31567 Character set, Glossary
31568 Charset, Glossary
31569 Child window, Overview of the X Window System
31570 Child Window, Obtaining Window Information
31571 Children, Glossary
31572 Chroma, TekHVC Queries, TekHVC Queries, TekHVC Queries, TekHVC
31573 Queries, TekHVC Queries, TekHVC Queries
31574
31575 maximum, TekHVC Queries, TekHVC Queries, TekHVC Queries
31576
31577 CIE metric lightness, CIELab Queries, CIELab Queries, CIELab
31578 Queries, CIELab Queries, CIELab Queries, CIELab Queries,
31579 CIELab Queries, CIELuv Queries, CIELuv Queries, CIELuv
31580 Queries, CIELuv Queries, CIELuv Queries, CIELuv Queries,
31581 CIELuv Queries
31582
31583 maximum, CIELab Queries, CIELab Queries, CIELuv Queries,
31584 CIELuv Queries
31585
31586 minimum, CIELab Queries, CIELuv Queries
31587
31588 CirculateNotify, CirculateNotify Events
31589 CirculateRequest, CirculateRequest Events
31590 Class, Glossary
31591 Clearing, Clearing Areas, Clearing Areas
31592
31593 areas, Clearing Areas
31594 windows, Clearing Areas
31595
31596 Client, Glossary
31597 Client White Point, Color Conversion Contexts and Gamut
31598 Mapping, Modifying Attributes of a Color Conversion
31599 Context
31600
31601 of Color Conversion Context, Modifying Attributes of a
31602 Color Conversion Context
31603
31604 ClientMessage, ClientMessage Events
31605 ClientWhitePointOfCCC, Color Conversion Context Macros
31606 Clipping region, Glossary
31607 Coded character, Glossary
31608 Coded character set, Glossary
31609 Codepoint, Glossary
31610 Color, Color Structures, Mapping Color Names to Values, Mapping
31611 Color Names to Values, Mapping Color Names to Values,
31612 Allocating and Freeing Color Cells, Allocating and
31613 Freeing Color Cells, Allocating and Freeing Color Cells,
31614 Allocating and Freeing Color Cells, Allocating and
31615 Freeing Color Cells, Allocating and Freeing Color Cells,
31616 Allocating and Freeing Color Cells, Allocating and
31617 Freeing Color Cells, Allocating and Freeing Color Cells,
31618 Allocating and Freeing Color Cells, Modifying and
31619 Querying Colormap Cells, Modifying and Querying Colormap
31620 Cells, Modifying and Querying Colormap Cells, Modifying
31621 and Querying Colormap Cells, Modifying and Querying
31622 Colormap Cells, Modifying and Querying Colormap Cells,
31623 Modifying and Querying Colormap Cells, Modifying and
31624 Querying Colormap Cells, Modifying and Querying Colormap
31625 Cells, Modifying and Querying Colormap Cells, Converting
31626 between Color Spaces
31627
31628 allocation, Allocating and Freeing Color Cells, Allocating
31629 and Freeing Color Cells, Allocating and Freeing
31630 Color Cells, Allocating and Freeing Color Cells,
31631 Allocating and Freeing Color Cells, Allocating and
31632 Freeing Color Cells, Allocating and Freeing Color
31633 Cells
31634
31635 conversion, Converting between Color Spaces
31636 deallocation, Allocating and Freeing Color Cells
31637 naming, Mapping Color Names to Values, Mapping Color Names
31638 to Values, Mapping Color Names to Values,
31639 Allocating and Freeing Color Cells, Allocating and
31640 Freeing Color Cells, Modifying and Querying
31641 Colormap Cells
31642
31643 querying, Modifying and Querying Colormap Cells, Modifying
31644 and Querying Colormap Cells, Modifying and
31645 Querying Colormap Cells, Modifying and Querying
31646 Colormap Cells
31647
31648 storing, Modifying and Querying Colormap Cells, Modifying
31649 and Querying Colormap Cells, Modifying and
31650 Querying Colormap Cells, Modifying and Querying
31651 Colormap Cells, Modifying and Querying Colormap
31652 Cells
31653
31654 Color Characterization Data, Creating Additional Function Sets
31655 Color conversion, Converting between Color Spaces
31656 Color Conversion Context, Color Conversion Contexts and Gamut
31657 Mapping, Color Conversion Contexts and Gamut Mapping,
31658 Color Conversion Contexts and Gamut Mapping, Color
31659 Conversion Contexts and Gamut Mapping, Color Conversion
31660 Context Functions, Color Conversion Context Functions,
31661 Color Conversion Context Functions, Getting and Setting
31662 the Color Conversion Context of a Colormap, Getting and
31663 Setting the Color Conversion Context of a Colormap,
31664 Obtaining the Default Color Conversion Context,
31665 Obtaining the Default Color Conversion Context, Creating
31666 and Freeing a Color Conversion Context, Creating and
31667 Freeing a Color Conversion Context
31668
31669 creation, Color Conversion Contexts and Gamut Mapping,
31670 Color Conversion Context Functions, Creating and
31671 Freeing a Color Conversion Context
31672
31673 default, Color Conversion Contexts and Gamut Mapping,
31674 Color Conversion Context Functions, Obtaining the
31675 Default Color Conversion Context, Obtaining the
31676 Default Color Conversion Context
31677
31678 freeing, Creating and Freeing a Color Conversion Context
31679 of colormap, Color Conversion Contexts and Gamut Mapping,
31680 Color Conversion Context Functions, Getting and
31681 Setting the Color Conversion Context of a
31682 Colormap, Getting and Setting the Color Conversion
31683 Context of a Colormap
31684
31685 Color map, Color Management Functions, Allocating and Freeing
31686 Color Cells
31687
31688 Colormap, Getting and Setting the Color Conversion Context of a
31689 Colormap, Getting and Setting the Color Conversion
31690 Context of a Colormap, Glossary
31691
31692 CCC of, Getting and Setting the Color Conversion Context
31693 of a Colormap, Getting and Setting the Color
31694 Conversion Context of a Colormap
31695
31696 ColormapNotify, Colormap State Change Events
31697 Colormaps, Standard Colormap Properties and Atoms
31698
31699 standard, Standard Colormap Properties and Atoms
31700
31701 ConfigureNotify, ConfigureNotify Events
31702 ConfigureRequest, ConfigureRequest Events
31703 Connection, Glossary
31704 ConnectionNumber, Display Macros
31705 Containment, Glossary
31706 Coordinate system, Glossary
31707 Copying, Copying Areas, Copying Areas
31708
31709 areas, Copying Areas
31710 planes, Copying Areas
31711
31712 CreateNotify, CreateNotify Events
31713 CurrentTime, Event Processing Overview, Pointer Grabbing
31714 Cursor, Creating Windows, Creating, Recoloring, and Freeing
31715 Cursors, Glossary
31716
31717 Initial State, Creating Windows
31718 limitations, Creating, Recoloring, and Freeing Cursors
31719
31720 Cut Buffers, Using Cut Buffers
31721
31722D
31723
31724 Debugging, Enabling or Disabling Synchronization, Using the
31725 Default Error Handlers, Using the Default Error
31726 Handlers, Using the Default Error Handlers, Using the
31727 Default Error Handlers
31728
31729 error event, Using the Default Error Handlers
31730 error handlers, Using the Default Error Handlers
31731 error message strings, Using the Default Error Handlers
31732 error numbers, Using the Default Error Handlers
31733 synchronous mode, Enabling or Disabling Synchronization
31734
31735 Default Protection, Controlling Host Access
31736 DefaultColormap, Display Macros
31737 DefaultColormapOfScreen, Screen Information Macros
31738 DefaultDepth, Display Macros
31739 DefaultDepthOfScreen, Screen Information Macros
31740 DefaultGC, Display Macros
31741 DefaultGCOfScreen, Screen Information Macros
31742 DefaultRootWindow, Display Macros
31743 DefaultScreen, Display Macros
31744 DefaultScreenOfDisplay, Display Macros
31745 DefaultVisual, Display Macros
31746 DefaultVisualOfScreen, Screen Information Macros
31747 Depth, Glossary
31748 Destination, Manipulating Graphics Context/State
31749 DestroyCallback, Destroy Callback, Destroy Callback
31750 DestroyNotify, DestroyNotify Events
31751 Device, Glossary
31752 Device Color Characterization, Function Sets
31753 Device profile, Color Conversion Contexts and Gamut Mapping,
31754 Creating Additional Function Sets
31755
31756 DirectColor, Glossary
31757 Display, Opening the Display, Obtaining Information about the
31758 Display, Image Formats, or Screens, Glossary, Glossary,
31759 Glossary
31760
31761 data structure, Obtaining Information about the Display,
31762 Image Formats, or Screens
31763
31764 structure, Glossary, Glossary
31765
31766 Display Functions, Manipulating Graphics Context/State
31767 DisplayCells, Display Macros
31768 DisplayHeight, Image Format Functions and Macros
31769 DisplayHeightMM, Image Format Functions and Macros
31770 DisplayOfCCC, Color Conversion Context Macros
31771 DisplayOfScreen, Screen Information Macros
31772 DisplayPlanes, Display Macros
31773 DisplayString, Display Macros
31774 DisplayWidth, Image Format Functions and Macros
31775 DisplayWidthMM, Image Format Functions and Macros
31776 DoesBackingStore, Screen Information Macros
31777 DoesSaveUnders, Screen Information Macros
31778 Drawable, Overview of the X Window System, Glossary
31779 Drawing, Drawing Single and Multiple Points, Drawing Single and
31780 Multiple Lines, Drawing Single and Multiple Lines,
31781 Drawing Single and Multiple Rectangles, Drawing Single
31782 and Multiple Arcs, Drawing Complex Text, Drawing Text
31783 Characters, Drawing Image Text Characters
31784
31785 arcs, Drawing Single and Multiple Arcs
31786 image text, Drawing Image Text Characters
31787 lines, Drawing Single and Multiple Lines
31788 points, Drawing Single and Multiple Points
31789 polygons, Drawing Single and Multiple Lines
31790 rectangles, Drawing Single and Multiple Rectangles
31791 strings, Drawing Text Characters
31792 text items, Drawing Complex Text
31793
31794E
31795
31796 Encoding, Glossary
31797 EnterNotify, Window Entry/Exit Events
31798 Environment, Opening the Display
31799
31800 DISPLAY, Opening the Display
31801
31802 Error, Errors, Using the Default Error Handlers, Using the
31803 Default Error Handlers
31804
31805 codes, Using the Default Error Handlers
31806 handlers, Using the Default Error Handlers
31807 handling, Errors
31808
31809 Escapement, Glossary
31810 Event, Overview of the X Window System, Event Types, Event
31811 Types, Event Types, Selecting Events, Glossary,
31812 Glossary, Glossary, Glossary, Glossary, Glossary
31813
31814 categories, Event Types
31815 Exposure, Glossary
31816 mask, Glossary
31817 propagation, Selecting Events, Glossary
31818 source, Glossary
31819 synchronization, Glossary
31820 types, Event Types
31821
31822 Event mask, Event Masks
31823 EventMaskOfScreen, Screen Information Macros
31824 Events, Keyboard and Pointer Events, Keyboard and Pointer
31825 Events, Keyboard and Pointer Events, Keyboard and
31826 Pointer Events, Keyboard and Pointer Events, Window
31827 Entry/Exit Events, Window Entry/Exit Events, Input Focus
31828 Events, Input Focus Events, Key Map State Notification
31829 Events, Expose Events, GraphicsExpose and NoExpose
31830 Events, GraphicsExpose and NoExpose Events,
31831 CirculateNotify Events, ConfigureNotify Events,
31832 CreateNotify Events, DestroyNotify Events, GravityNotify
31833 Events, MapNotify Events, MappingNotify Events,
31834 ReparentNotify Events, UnmapNotify Events,
31835 VisibilityNotify Events, CirculateRequest Events,
31836 ConfigureRequest Events, MapRequest Events,
31837 ResizeRequest Events, Colormap State Change Events,
31838 ClientMessage Events, PropertyNotify Events,
31839 SelectionClear Events, SelectionRequest Events,
31840 SelectionNotify Events
31841
31842 ButtonPress, Keyboard and Pointer Events
31843 ButtonRelease, Keyboard and Pointer Events
31844 CirculateNotify, CirculateNotify Events
31845 CirculateRequest, CirculateRequest Events
31846 ClientMessage, ClientMessage Events
31847 ColormapNotify, Colormap State Change Events
31848 ConfigureNotify, ConfigureNotify Events
31849 ConfigureRequest, ConfigureRequest Events
31850 CreateNotify, CreateNotify Events
31851 DestroyNotify, DestroyNotify Events
31852 EnterNotify, Window Entry/Exit Events
31853 Expose, Expose Events
31854 FocusIn, Input Focus Events
31855 FocusOut, Input Focus Events
31856 GraphicsExpose, GraphicsExpose and NoExpose Events
31857 GravityNotify, GravityNotify Events
31858 KeymapNotify, Key Map State Notification Events
31859 KeyPress, Keyboard and Pointer Events
31860 KeyRelease, Keyboard and Pointer Events
31861 LeaveNotify, Window Entry/Exit Events
31862 MapNotify, MapNotify Events
31863 MappingNotify, MappingNotify Events
31864 MapRequest, MapRequest Events
31865 MotionNotify, Keyboard and Pointer Events
31866 NoExpose, GraphicsExpose and NoExpose Events
31867 PropertyNotify, PropertyNotify Events
31868 ReparentNotify, ReparentNotify Events
31869 ResizeRequest, ResizeRequest Events
31870 SelectionClear, SelectionClear Events
31871 SelectionNotify, SelectionNotify Events
31872 SelectionRequest, SelectionRequest Events
31873 UnmapNotify, UnmapNotify Events
31874 VisibilityNotify, VisibilityNotify Events
31875
31876 Expose, Expose Events
31877 Extension, Glossary
31878
31879F
31880
31881 False, Generic Values and Types
31882 Files, Overview of the X Window System, Standard Header Files,
31883 Standard Header Files, Standard Header Files, Standard
31884 Header Files, Standard Header Files, Standard Header
31885 Files, Standard Header Files, Standard Header Files,
31886 Standard Header Files, Standard Header Files, Standard
31887 Header Files, Standard Header Files, Standard Header
31888 Files, Opening the Display, Properties and Atoms, Color
31889 Management Functions, Color Management Functions,
31890 Manipulating Graphics Context/State, Loading and Freeing
31891 Fonts, Controlling Host Access, Event Types, Event
31892 Structures, Event Masks, GraphicsExpose and NoExpose
31893 Events, Manipulating the Keyboard Encoding, Manipulating
31894 the Keyboard Encoding, Setting and Reading the WM_HINTS
31895 Property, Setting and Reading the WM_NORMAL_HINTS
31896 Property, Setting and Reading the WM_CLASS Property,
31897 Setting and Reading the WM_ICON_SIZE Property, Standard
31898 Colormap Properties and Atoms, Resource Manager
31899 Functions, Using Keyboard Utility Functions, Parsing the
31900 Window Geometry, Manipulating Regions, Determining the
31901 Appropriate Visual Type, Manipulating Images,
31902 Manipulating Images, Using the Context Manager, Setting
31903 and Getting Window Sizing Hints, Getting the X
31904 Environment Defaults, Drawing and Filling Polygons and
31905 Curves, Drawing and Filling Polygons and Curves
31906
31907 $HOME/.Xdefaults, Getting the X Environment Defaults
31908 /etc/X?.hosts, Controlling Host Access
31909 <X11/cursorfont.h>, Standard Header Files
31910 <X11/keysym.h>, Standard Header Files, Manipulating the
31911 Keyboard Encoding
31912
31913 <X11/keysymdef.h>, Standard Header Files, Manipulating the
31914 Keyboard Encoding, Using Keyboard Utility
31915 Functions
31916
31917 <X11/X.h>, Overview of the X Window System, Standard
31918 Header Files, Manipulating Graphics Context/State,
31919 Event Types, Event Masks
31920
31921 <X11/X10.h>, Standard Header Files, Drawing and Filling
31922 Polygons and Curves, Drawing and Filling Polygons
31923 and Curves
31924
31925 <X11/Xatom.h>, Standard Header Files, Properties and
31926 Atoms, Loading and Freeing Fonts, Standard
31927 Colormap Properties and Atoms
31928
31929 <X11/Xcms.h>, Standard Header Files, Color Management
31930 Functions
31931
31932 <X11/Xlib.h>, Standard Header Files, Opening the Display,
31933 Color Management Functions, Event Structures,
31934 Manipulating Images
31935
31936 <X11/Xlibint.h>, Standard Header Files
31937 <X11/Xproto.h>, Standard Header Files, GraphicsExpose and
31938 NoExpose Events
31939
31940 <X11/Xprotostr.h>, Standard Header Files
31941 <X11/Xresource.h>, Standard Header Files, Resource Manager
31942 Functions
31943
31944 <X11/Xutil.h>, Standard Header Files, Setting and Reading
31945 the WM_HINTS Property, Setting and Reading the
31946 WM_NORMAL_HINTS Property, Setting and Reading the
31947 WM_CLASS Property, Setting and Reading the
31948 WM_ICON_SIZE Property, Parsing the Window
31949 Geometry, Manipulating Regions, Determining the
31950 Appropriate Visual Type, Manipulating Images,
31951 Using the Context Manager, Setting and Getting
31952 Window Sizing Hints
31953
31954 Filling, Filling Single and Multiple Rectangles, Filling a
31955 Single Polygon, Filling Single and Multiple Arcs
31956
31957 arcs, Filling Single and Multiple Arcs
31958 polygon, Filling a Single Polygon
31959 rectangles, Filling Single and Multiple Rectangles
31960
31961 FlushGC, GC Caching
31962 FocusIn, Input Focus Events
31963 FocusOut, Input Focus Events
31964 Font, Font Metrics, Glossary
31965 Font glyph, Glossary
31966 Fonts, Loading and Freeing Fonts, Loading and Freeing Fonts,
31967 Loading and Freeing Fonts
31968
31969 freeing font information, Loading and Freeing Fonts
31970 getting information, Loading and Freeing Fonts
31971 unloading, Loading and Freeing Fonts
31972
31973 Freeing, Window Attributes, Changing Window Attributes,
31974 Changing Window Attributes, Allocating and Freeing Color
31975 Cells
31976
31977 colors, Allocating and Freeing Color Cells
31978 resources, Window Attributes, Changing Window Attributes,
31979 Changing Window Attributes
31980
31981 Frozen events, Glossary
31982 Function set, Function Sets, Function Sets
31983
31984 LINEAR_RGB, Function Sets
31985
31986G
31987
31988 Gamut compression, Color Conversion Contexts and Gamut Mapping,
31989 Modifying Attributes of a Color Conversion Context,
31990 Modifying Attributes of a Color Conversion Context,
31991 Modifying Attributes of a Color Conversion Context
31992
31993 client data, Modifying Attributes of a Color Conversion
31994 Context
31995
31996 procedure, Modifying Attributes of a Color Conversion
31997 Context
31998
31999 setting in Color Conversion Context, Modifying Attributes
32000 of a Color Conversion Context
32001
32002 Gamut handling, Color Conversion Contexts and Gamut Mapping
32003 Gamut querying, Gamut Querying Functions
32004 GC, Glossary
32005 GeometryCallback, Geometry Callback
32006 Glyph, Glossary
32007 Glyph image, Glossary
32008 Grab, Glossary
32009 Grabbing, Grabbing the Server, Pointer Grabbing, Pointer
32010 Grabbing, Keyboard Grabbing, Keyboard Grabbing
32011
32012 buttons, Pointer Grabbing
32013 keyboard, Keyboard Grabbing
32014 keys, Keyboard Grabbing
32015 pointer, Pointer Grabbing
32016 server, Grabbing the Server
32017
32018 Graphics context, Manipulating Graphics Context/State, Glossary
32019
32020 initializing, Manipulating Graphics Context/State
32021
32022 GraphicsExpose, GraphicsExpose and NoExpose Events
32023 Gravity, Glossary
32024 GravityNotify, GravityNotify Events
32025 GrayScale, Glossary
32026
32027H
32028
32029 Hash Lookup, Associating User Data with a Value
32030 Headers, Overview of the X Window System, Standard Header
32031 Files, Standard Header Files, Standard Header Files,
32032 Standard Header Files, Standard Header Files, Standard
32033 Header Files, Standard Header Files, Standard Header
32034 Files, Standard Header Files, Standard Header Files,
32035 Standard Header Files, Standard Header Files, Standard
32036 Header Files, Standard Header Files, Opening the
32037 Display, Properties and Atoms, Color Management
32038 Functions, Color Management Functions, Manipulating
32039 Graphics Context/State, Loading and Freeing Fonts, Event
32040 Types, Event Structures, Event Masks, GraphicsExpose and
32041 NoExpose Events, Manipulating the Keyboard Encoding,
32042 Manipulating the Keyboard Encoding, Setting and Reading
32043 the WM_HINTS Property, Setting and Reading the
32044 WM_NORMAL_HINTS Property, Setting and Reading the
32045 WM_CLASS Property, Setting and Reading the WM_ICON_SIZE
32046 Property, Standard Colormap Properties and Atoms,
32047 Resource Manager Functions, Using Keyboard Utility
32048 Functions, Parsing the Window Geometry, Manipulating
32049 Regions, Determining the Appropriate Visual Type,
32050 Manipulating Images, Manipulating Images, Using the
32051 Context Manager, Setting and Getting Window Sizing
32052 Hints, Drawing and Filling Polygons and Curves, Drawing
32053 and Filling Polygons and Curves
32054
32055 <X11/cursorfont.h>, Standard Header Files
32056 <X11/keysym.h>, Standard Header Files, Manipulating the
32057 Keyboard Encoding
32058
32059 <X11/keysymdef.h>, Standard Header Files, Manipulating the
32060 Keyboard Encoding, Using Keyboard Utility
32061 Functions
32062
32063 <X11/X.h>, Overview of the X Window System, Standard
32064 Header Files, Manipulating Graphics Context/State,
32065 Event Types, Event Masks
32066
32067 <X11/X10.h>, Standard Header Files, Drawing and Filling
32068 Polygons and Curves, Drawing and Filling Polygons
32069 and Curves
32070
32071 <X11/Xatom.h>, Standard Header Files, Properties and
32072 Atoms, Loading and Freeing Fonts, Standard
32073 Colormap Properties and Atoms
32074
32075 <X11/Xcms.h>, Standard Header Files, Color Management
32076 Functions
32077
32078 <X11/Xlib.h>, Standard Header Files, Opening the Display,
32079 Color Management Functions, Event Structures,
32080 Manipulating Images
32081
32082 <X11/Xlibint.h>, Standard Header Files
32083 <X11/Xproto.h>, Standard Header Files, GraphicsExpose and
32084 NoExpose Events
32085
32086 <X11/Xprotostr.h>, Standard Header Files
32087 <X11/Xresource.h>, Standard Header Files, Resource Manager
32088 Functions
32089
32090 <X11/Xutil.h>, Standard Header Files, Setting and Reading
32091 the WM_HINTS Property, Setting and Reading the
32092 WM_NORMAL_HINTS Property, Setting and Reading the
32093 WM_CLASS Property, Setting and Reading the
32094 WM_ICON_SIZE Property, Parsing the Window
32095 Geometry, Manipulating Regions, Determining the
32096 Appropriate Visual Type, Manipulating Images,
32097 Using the Context Manager, Setting and Getting
32098 Window Sizing Hints
32099
32100 HeightMMOfScreen, Screen Information Macros
32101 HeightOfScreen, Screen Information Macros
32102 Host Portable Character Encoding, Glossary
32103 Hotspot, Glossary
32104
32105I
32106
32107 Identifier, Glossary
32108 Image text, Drawing Image Text Characters
32109
32110 drawing, Drawing Image Text Characters
32111
32112 ImageByteOrder, Image Format Functions and Macros
32113 IMInstantiateCallback, Input Method Functions
32114 Inferiors, Glossary
32115 Input, Glossary, Glossary
32116
32117 focus, Glossary
32118 manager, Glossary
32119
32120 Input Control, Event Types
32121 Internationalization, Glossary
32122 IsCursorKey, KeySym Classification Macros
32123 IsFunctionKey, KeySym Classification Macros
32124 IsKeypadKey, KeySym Classification Macros
32125 IsMiscFunctionKey, KeySym Classification Macros
32126 IsModifierKey, KeySym Classification Macros
32127 ISO2022, Glossary
32128 IsPFKey, KeySym Classification Macros
32129 IsPrivateKeypadKey, KeySym Classification Macros
32130
32131K
32132
32133 Key, Keyboard Grabbing, Keyboard Grabbing, Glossary
32134
32135 grabbing, Keyboard Grabbing, Glossary
32136 ungrabbing, Keyboard Grabbing
32137
32138 Keyboard, Keyboard Grabbing, Keyboard Grabbing, Manipulating
32139 the Keyboard and Pointer Settings, Manipulating the
32140 Keyboard and Pointer Settings, Manipulating the Keyboard
32141 and Pointer Settings, Glossary
32142
32143 bell volume, Manipulating the Keyboard and Pointer
32144 Settings
32145
32146 bit vector, Manipulating the Keyboard and Pointer Settings
32147 grabbing, Keyboard Grabbing, Glossary
32148 keyclick volume, Manipulating the Keyboard and Pointer
32149 Settings
32150
32151 ungrabbing, Keyboard Grabbing
32152
32153 KeymapNotify, Key Map State Notification Events
32154 KeyPress, Keyboard and Pointer Events
32155 KeyRelease, Keyboard and Pointer Events
32156 Keysym, Glossary
32157
32158L
32159
32160 LastKnownRequestProcessed, Display Macros
32161 Latin Portable Character Encoding, Glossary
32162 Latin-1, Glossary
32163 LeaveNotify, Window Entry/Exit Events
32164 Lines, Drawing Single and Multiple Lines
32165
32166 drawing, Drawing Single and Multiple Lines
32167
32168 Locale, Glossary
32169 Locale name, Glossary
32170 Localization, Glossary
32171 LockDisplay, Locking Data Structures
32172
32173M
32174
32175 MapNotify, MapNotify Events
32176 Mapped window, Glossary
32177 MappingNotify, MappingNotify Events
32178 MapRequest, MapRequest Events
32179 MaxCmapsOfScreen, Screen Information Macros
32180 Menus, Grabbing the Server
32181 MinCmapsOfScreen, Screen Information Macros
32182 Modifier keys, Glossary
32183 Monochrome, Glossary
32184 MotionNotify, Keyboard and Pointer Events
32185 Mouse, Manipulating the Keyboard and Pointer Settings
32186
32187 programming, Manipulating the Keyboard and Pointer
32188 Settings
32189
32190 Multibyte, Glossary
32191
32192N
32193
32194 NextRequest, Display Macros
32195 NoExpose, GraphicsExpose and NoExpose Events
32196 None, Generic Values and Types
32197
32198O
32199
32200 Obscure, Glossary
32201 Occlude, Glossary
32202 Output Control, Event Types
32203
32204P
32205
32206 Padding, Glossary
32207 Parent Window, Overview of the X Window System, Obtaining
32208 Window Information
32209
32210 Passive grab, Pointer Grabbing, Glossary
32211 Pixel value, Manipulating Graphics Context/State, Glossary
32212 Pixmap, Overview of the X Window System, Glossary
32213 Plane, Manipulating Graphics Context/State, Copying Areas,
32214 Glossary, Glossary
32215
32216 copying, Copying Areas
32217 mask, Manipulating Graphics Context/State, Glossary
32218
32219 PlanesOfScreen, Screen Information Macros
32220 Pointer, Pointer Grabbing, Pointer Grabbing, Pointer Grabbing,
32221 Glossary, Glossary
32222
32223 grabbing, Pointer Grabbing, Pointer Grabbing, Glossary
32224 ungrabbing, Pointer Grabbing
32225
32226 Pointing device, Glossary
32227 Points, Drawing Single and Multiple Points
32228
32229 drawing, Drawing Single and Multiple Points
32230
32231 Polygons, Drawing Single and Multiple Lines, Filling a Single
32232 Polygon
32233
32234 drawing, Drawing Single and Multiple Lines
32235 filling, Filling a Single Polygon
32236
32237 POSIX, Glossary
32238 POSIX Portable Filename Character Set, Glossary
32239 POSIX System Call, Display Macros
32240
32241 fork, Display Macros
32242
32243 PreeditCaretCallback, Preedit Caret Callback
32244 PreeditDoneCallback, Preedit State Callbacks
32245 PreeditDrawCallback, Preedit Draw Callback
32246 PreeditStartCallback, Preedit State Callbacks
32247 PreeditStateNotifyCallback, Preedit State Notify Callback
32248 Property, Obtaining and Changing Window Properties, Obtaining
32249 and Changing Window Properties, Obtaining and Changing
32250 Window Properties, Obtaining and Changing Window
32251 Properties, Obtaining and Changing Window Properties,
32252 Obtaining and Changing Window Properties, Obtaining and
32253 Changing Window Properties, Obtaining and Changing
32254 Window Properties, Obtaining and Changing Window
32255 Properties, Glossary
32256
32257 appending, Obtaining and Changing Window Properties
32258 changing, Obtaining and Changing Window Properties
32259 deleting, Obtaining and Changing Window Properties
32260 format, Obtaining and Changing Window Properties
32261 getting, Obtaining and Changing Window Properties
32262 listing, Obtaining and Changing Window Properties
32263 prepending, Obtaining and Changing Window Properties
32264 replacing, Obtaining and Changing Window Properties
32265 type, Obtaining and Changing Window Properties
32266
32267 Property list, Glossary
32268 PropertyNotify, PropertyNotify Events
32269 Protocol, Opening the Display, Opening the Display
32270
32271 DECnet, Opening the Display
32272 TCP, Opening the Display
32273
32274 ProtocolRevision, Display Macros
32275 ProtocolVersion, Display Macros
32276 PseudoColor, Glossary
32277 Psychometric Chroma, CIELab Queries, CIELab Queries, CIELab
32278 Queries, CIELab Queries, CIELuv Queries, CIELuv Queries,
32279 CIELuv Queries, CIELuv Queries
32280
32281 maximum, CIELab Queries, CIELab Queries, CIELuv Queries,
32282 CIELuv Queries
32283
32284 Psychometric Hue Angle, CIELab Queries, CIELab Queries, CIELab
32285 Queries, CIELab Queries, CIELuv Queries, CIELuv Queries,
32286 CIELuv Queries, CIELuv Queries
32287
32288Q
32289
32290 QLength, Display Macros
32291
32292R
32293
32294 Read-only colormap cells, Allocating and Freeing Color Cells,
32295 Allocating and Freeing Color Cells, Allocating and
32296 Freeing Color Cells, Allocating and Freeing Color Cells,
32297 Allocating and Freeing Color Cells
32298
32299 allocating, Allocating and Freeing Color Cells, Allocating
32300 and Freeing Color Cells, Allocating and Freeing
32301 Color Cells, Allocating and Freeing Color Cells
32302
32303 read-only colormap cells, Allocating and Freeing Color Cells
32304 Read/write colormap cells, Allocating and Freeing Color Cells,
32305 Allocating and Freeing Color Cells
32306
32307 allocating, Allocating and Freeing Color Cells
32308
32309 Read/write colormap planes, Allocating and Freeing Color Cells
32310
32311 allocating, Allocating and Freeing Color Cells
32312
32313 Rectangle, Filling Single and Multiple Rectangles, Glossary
32314
32315 filling, Filling Single and Multiple Rectangles
32316
32317 Rectangles, Drawing Single and Multiple Rectangles
32318
32319 drawing, Drawing Single and Multiple Rectangles
32320
32321 Redirecting control, Glossary
32322 ReparentNotify, ReparentNotify Events
32323 Reply, Glossary
32324 Request, Glossary
32325 ResizeRequest, ResizeRequest Events
32326 Resource, Glossary
32327 Resource IDs, Overview of the X Window System, Overview of the
32328 X Window System, Overview of the X Window System,
32329 Overview of the X Window System, Overview of the X
32330 Window System, Overview of the X Window System, Overview
32331 of the X Window System, Closing the Display, Window
32332 Attributes, Changing Window Attributes, Changing Window
32333 Attributes, Associating User Data with a Value
32334
32335 Colormap, Overview of the X Window System
32336 Cursor, Overview of the X Window System
32337 Font, Overview of the X Window System
32338 freeing, Window Attributes, Changing Window Attributes,
32339 Changing Window Attributes
32340
32341 GContext, Overview of the X Window System
32342 Pixmap, Overview of the X Window System
32343 Window, Overview of the X Window System
32344
32345 RGB values, Glossary
32346 Root, Glossary
32347 RootWindow, Display Macros
32348 RootWindowOfScreen, Screen Information Macros
32349
32350S
32351
32352 Save set, Glossary
32353 Save Unders, Save Under Flag
32354 Scanline, Glossary, Glossary
32355
32356 order, Glossary
32357
32358 Screen, Overview of the X Window System, Opening the Display,
32359 Glossary, Glossary
32360
32361 structure, Glossary
32362
32363 Screen White Point, Gamut Querying Functions
32364 ScreenCount, Display Macros
32365 ScreenNumberOfCCC, Color Conversion Context Macros
32366 ScreenOfDisplay, Display Macros
32367 ScreenWhitePointOfCCC, Color Conversion Context Macros
32368 Selection, Selections, Selections, Selections, Selections,
32369 Glossary
32370
32371 converting, Selections
32372 getting the owner, Selections
32373 setting the owner, Selections
32374
32375 SelectionClear, SelectionClear Events
32376 SelectionNotify, SelectionNotify Events
32377 SelectionRequest, SelectionRequest Events
32378 Serial Number, Using the Default Error Handlers
32379 Server, Grabbing the Server, Glossary, Glossary
32380
32381 grabbing, Grabbing the Server, Glossary
32382
32383 ServerVendor, Display Macros
32384 Shift sequence, Glossary
32385 Sibling, Glossary
32386 Source, Manipulating Graphics Context/State
32387 Stacking order, Overview of the X Window System, Glossary
32388 Standard Colormaps, Standard Colormap Properties and Atoms
32389 State-dependent encoding, Glossary
32390 State-independent encoding, Glossary
32391 StaticColor, Glossary
32392 StaticGray, Glossary
32393 Status, Errors, Glossary
32394 StatusDoneCallback, Status Callbacks
32395 StatusDrawCallback, Status Callbacks
32396 StatusStartCallback, Status Callbacks
32397 Stipple, Glossary
32398 String Equivalence, Glossary
32399 StringConversionCallback, String Conversion Callback
32400 Strings, Drawing Text Characters
32401
32402 drawing, Drawing Text Characters
32403
32404T
32405
32406 Text, Drawing Complex Text
32407
32408 drawing, Drawing Complex Text
32409
32410 Tile, Overview of the X Window System, Window Attributes,
32411 Window Attributes, Glossary
32412
32413 mode, Window Attributes
32414 pixmaps, Window Attributes
32415
32416 Time, Pointer Grabbing
32417 Timestamp, Glossary
32418 True, Generic Values and Types
32419 TrueColor, Glossary
32420 Type, Glossary
32421
32422U
32423
32424 Ungrabbing, Pointer Grabbing, Pointer Grabbing, Keyboard
32425 Grabbing, Keyboard Grabbing
32426
32427 buttons, Pointer Grabbing
32428 keyboard, Keyboard Grabbing
32429 keys, Keyboard Grabbing
32430 pointer, Pointer Grabbing
32431
32432 UnlockDisplay, Locking Data Structures
32433 UnmapNotify, UnmapNotify Events
32434 UnmapNotify Event, Unmapping Windows, Unmapping Windows
32435
32436V
32437
32438 Value, TekHVC Queries, TekHVC Queries, TekHVC Queries, TekHVC
32439 Queries, TekHVC Queries, TekHVC Queries, TekHVC Queries,
32440 TekHVC Queries
32441
32442 maximum, TekHVC Queries, TekHVC Queries, TekHVC Queries
32443 minimum, TekHVC Queries
32444
32445 VendorRelease, Display Macros
32446 Vertex, Drawing and Filling Polygons and Curves
32447 VertexCurved, Drawing and Filling Polygons and Curves
32448 VertexDontDraw, Drawing and Filling Polygons and Curves
32449 VertexEndClosed, Drawing and Filling Polygons and Curves
32450 VertexRelative, Drawing and Filling Polygons and Curves
32451 VertexStartClosed, Drawing and Filling Polygons and Curves
32452 Viewable, Glossary
32453 VisibilityNotify, VisibilityNotify Events
32454 Visible, Glossary
32455 Visual, Visual Types
32456 Visual Classes, Visual Types, Visual Types, Visual Types,
32457 Visual Types, Visual Types, Visual Types
32458
32459 GrayScale, Visual Types
32460 PseudoColor, Visual Types
32461 StaticColor, Visual Types, Visual Types
32462 StaticGray, Visual Types
32463 TrueColor, Visual Types
32464
32465 Visual Type, Visual Types
32466 VisualOfCCC, Color Conversion Context Macros
32467
32468W
32469
32470 White point, Color Conversion Contexts and Gamut Mapping
32471 White point adjustment, Color Conversion Contexts and Gamut
32472 Mapping, Modifying Attributes of a Color Conversion
32473 Context, Modifying Attributes of a Color Conversion
32474 Context, Modifying Attributes of a Color Conversion
32475 Context
32476
32477 client data, Modifying Attributes of a Color Conversion
32478 Context
32479
32480 procedure, Modifying Attributes of a Color Conversion
32481 Context
32482
32483 setting in Color Conversion Context, Modifying Attributes
32484 of a Color Conversion Context
32485
32486 WhitePixel, Display Macros
32487 WhitePixelOfScreen, Screen Information Macros
32488 Whitespace, Glossary
32489 WidthMMOfScreen, Screen Information Macros
32490 WidthOfScreen, Screen Information Macros
32491 Window, Overview of the X Window System, Display Macros,
32492 Display Macros, Window Attributes, Window Attributes,
32493 Window Attributes, Creating Windows, Changing Window
32494 Attributes, Changing Window Attributes, Changing Window
32495 Attributes, Clearing Areas, Grabbing the Server, Setting
32496 and Reading the WM_NAME Property, Setting and Reading
32497 the WM_ICON_NAME Property, Parsing the Window Geometry,
32498 Parsing Window Geometry, Associating User Data with a
32499 Value, Glossary, Glossary, Glossary, Glossary, Glossary,
32500 Glossary
32501
32502 attributes, Window Attributes
32503 background, Changing Window Attributes
32504 clearing, Clearing Areas
32505 defining the cursor, Changing Window Attributes
32506 determining location, Parsing the Window Geometry, Parsing
32507 Window Geometry
32508
32509 gravity, Glossary
32510 icon name, Setting and Reading the WM_ICON_NAME Property
32511 IDs, Associating User Data with a Value
32512 InputOnly, Creating Windows, Glossary
32513 InputOutput, Glossary
32514 manager, Glossary
32515 managers, Grabbing the Server
32516 mapping, Window Attributes
32517 name, Setting and Reading the WM_NAME Property
32518 parent, Glossary
32519 root, Glossary
32520 RootWindow, Display Macros
32521 undefining the cursor, Changing Window Attributes
32522 XRootWindow, Display Macros
32523
32524X
32525
32526 X Portable Character Set, Glossary
32527 X10 compatibility, Drawing and Filling Polygons and Curves,
32528 Drawing and Filling Polygons and Curves, Drawing and
32529 Filling Polygons and Curves, Drawing and Filling
32530 Polygons and Curves, Drawing and Filling Polygons and
32531 Curves, Drawing and Filling Polygons and Curves, Drawing
32532 and Filling Polygons and Curves, Drawing and Filling
32533 Polygons and Curves, Drawing and Filling Polygons and
32534 Curves, Drawing and Filling Polygons and Curves
32535
32536 XDraw, Drawing and Filling Polygons and Curves, Drawing
32537 and Filling Polygons and Curves
32538
32539 XDrawDashed, Drawing and Filling Polygons and Curves,
32540 Drawing and Filling Polygons and Curves
32541
32542 XDrawFilled, Drawing and Filling Polygons and Curves,
32543 Drawing and Filling Polygons and Curves
32544
32545 XDrawPatterned, Drawing and Filling Polygons and Curves,
32546 Drawing and Filling Polygons and Curves
32547
32548 XDrawTiled, Drawing and Filling Polygons and Curves,
32549 Drawing and Filling Polygons and Curves
32550
32551 X11/cursorfont.h, Standard Header Files
32552 X11/keysym.h, Standard Header Files, Manipulating the Keyboard
32553 Encoding
32554
32555 X11/keysymdef.h, Standard Header Files, Manipulating the
32556 Keyboard Encoding, Using Keyboard Utility Functions
32557
32558 X11/X.h, Overview of the X Window System, Standard Header
32559 Files, Manipulating Graphics Context/State, Event Types,
32560 Event Masks
32561
32562 X11/X10.h, Standard Header Files, Drawing and Filling Polygons
32563 and Curves, Drawing and Filling Polygons and Curves
32564
32565 X11/Xatom.h, Standard Header Files, Properties and Atoms,
32566 Loading and Freeing Fonts, Standard Colormap Properties
32567 and Atoms
32568
32569 X11/Xcms.h, Standard Header Files, Color Management Functions
32570 X11/Xlib.h, Standard Header Files, Opening the Display, Color
32571 Management Functions, Event Structures, Manipulating
32572 Images
32573
32574 X11/Xlibint.h, Standard Header Files
32575 X11/Xproto.h, Standard Header Files, GraphicsExpose and
32576 NoExpose Events
32577
32578 X11/Xprotostr.h, Standard Header Files
32579 X11/Xresource.h, Standard Header Files, Resource Manager
32580 Functions
32581
32582 X11/Xutil.h, Standard Header Files, Setting and Reading the
32583 WM_HINTS Property, Setting and Reading the
32584 WM_NORMAL_HINTS Property, Setting and Reading the
32585 WM_CLASS Property, Setting and Reading the WM_ICON_SIZE
32586 Property, Parsing the Window Geometry, Manipulating
32587 Regions, Determining the Appropriate Visual Type,
32588 Manipulating Images, Using the Context Manager, Setting
32589 and Getting Window Sizing Hints
32590
32591 XActivateScreenSaver, Controlling the Screen Saver
32592 XAddExtension, Hooking into Xlib
32593 XAddHost, Adding, Getting, or Removing Hosts
32594 XAddHosts, Adding, Getting, or Removing Hosts
32595 XAddPixel, Manipulating Images
32596 XAddToExtensionList, Hooks onto Xlib Data Structures
32597 XAddToSaveSet, Controlling the Lifetime of a Window
32598 XAllocClassHint, Setting and Reading the WM_CLASS Property
32599 XAllocColor, Allocating and Freeing Color Cells, Allocating and
32600 Freeing Color Cells
32601
32602 XAllocColorCells, Allocating and Freeing Color Cells,
32603 Allocating and Freeing Color Cells
32604
32605 XAllocColorPlanes, Allocating and Freeing Color Cells,
32606 Allocating and Freeing Color Cells
32607
32608 XAllocID, Hooks onto Xlib Data Structures
32609 XAllocIDs, Hooks onto Xlib Data Structures
32610 XAllocNamedColor, Allocating and Freeing Color Cells,
32611 Allocating and Freeing Color Cells
32612
32613 XAllowEvents, Resuming Event Processing
32614 XAllPlanes, Display Macros
32615 XAnyEvent, Event Structures
32616 XArc, Drawing Points, Lines, Rectangles, and Arcs
32617 XAutoRepeatOff, Manipulating the Keyboard and Pointer Settings
32618 XAutoRepeatOn, Manipulating the Keyboard and Pointer Settings
32619 XBaseFontNameListOfFontSet, Creating and Freeing a Font Set
32620 XBell, Manipulating the Keyboard and Pointer Settings
32621 XBitmapBitOrder, Image Format Functions and Macros
32622 XBitmapPad, Image Format Functions and Macros
32623 XBitmapUnit, Image Format Functions and Macros
32624 XBlackPixel, Display Macros
32625 XBlackPixelOfScreen, Screen Information Macros
32626 XCellsOfScreen, Screen Information Macros
32627 XChangeActivePointerGrab, Pointer Grabbing
32628 XChangeGC, Manipulating Graphics Context/State
32629 XChangeKeyboardControl, Manipulating the Keyboard and Pointer
32630 Settings
32631
32632 XChangeKeyboardMapping, Manipulating the Keyboard Encoding
32633 XChangePointerControl, Manipulating the Keyboard and Pointer
32634 Settings
32635
32636 XChangeProperty, Obtaining and Changing Window Properties
32637 XChangeSaveSet, Controlling the Lifetime of a Window
32638 XChangeWindowAttributes, Changing Window Attributes
32639 XChar2b, Font Metrics
32640 XCharStruct, Font Metrics
32641 XCheckIfEvent, Selecting Events Using a Predicate Procedure
32642 XCheckMaskEvent, Selecting Events Using a Window or Event Mask
32643 XCheckTypedEvent, Selecting Events Using a Window or Event Mask
32644 XCheckTypedWindowEvent, Selecting Events Using a Window or
32645 Event Mask
32646
32647 XCheckWindowEvent, Selecting Events Using a Window or Event
32648 Mask, Selecting Events Using a Window or Event Mask
32649
32650 XCirculateEvent, CirculateNotify Events
32651 XCirculateRequestEvent, CirculateRequest Events
32652 XCirculateSubwindows, Changing Window Stacking Order
32653 XCirculateSubwindowsDown, Changing Window Stacking Order
32654 XCirculateSubwindowsUp, Changing Window Stacking Order
32655 XClassHint, Setting and Reading the WM_CLASS Property
32656 XClearArea, Clearing Areas
32657 XClearWindow, Clearing Areas
32658 XClientMessageEvent, ClientMessage Events
32659 XClipBox, Computing with Regions
32660 XCloseDisplay, Closing the Display, Closing the Display
32661 XCloseIM, Input Method Functions
32662 XCloseOM, Output Method Functions
32663 XcmsAddColorSpace, Adding Device-Independent Color Spaces
32664 XcmsAddFunctionSet, Adding Function Sets
32665 XcmsAllocColor, Allocating and Freeing Color Cells
32666 XcmsAllocNamedColor, Allocating and Freeing Color Cells
32667 XcmsCCCOfColormap, Getting and Setting the Color Conversion
32668 Context of a Colormap
32669
32670 XcmsCIELab, Color Structures
32671 XcmsCIELabQueryMaxC, CIELab Queries
32672 XcmsCIELabQueryMaxL, CIELab Queries
32673 XcmsCIELabQueryMaxLC, CIELab Queries
32674 XcmsCIELabQueryMinL, CIELab Queries
32675 XcmsCIELuv, Color Structures
32676 XcmsCIELuvQueryMaxC, CIELuv Queries
32677 XcmsCIELuvQueryMaxL, CIELuv Queries
32678 XcmsCIELuvQueryMaxLC, CIELuv Queries
32679 XcmsCIELuvQueryMinL, CIELuv Queries
32680 XcmsCIEuvY, Color Structures
32681 XcmsCIExyY, Color Structures
32682 XcmsCIEXYZ, Color Structures
32683 XcmsClientWhitePointOfCCC, Color Conversion Context Macros
32684 XcmsColor, Color Structures
32685 XcmsCompressionProc, Prototype Gamut Compression Procedure
32686 XcmsConvertColors, Converting between Color Spaces
32687 XcmsCreateCCC, Creating and Freeing a Color Conversion Context
32688 XcmsDefaultCCC, Obtaining the Default Color Conversion Context
32689 XcmsDisplayOfCCC, Color Conversion Context Macros
32690 XcmsFormatOfPrefix, Querying Color Space Format and Prefix
32691 XcmsFreeCCC, Creating and Freeing a Color Conversion Context
32692 XcmsLookupColor, Mapping Color Names to Values
32693 XcmsPad, Color Structures
32694 XcmsParseStringProc, Parse String Callback
32695 XcmsPrefixOfFormat, Querying Color Space Format and Prefix
32696 XcmsQueryBlack, Red, Green, and Blue Queries
32697 XcmsQueryBlue, Red, Green, and Blue Queries
32698 XcmsQueryColor, Modifying and Querying Colormap Cells
32699 XcmsQueryColors, Modifying and Querying Colormap Cells
32700 XcmsQueryGreen, Red, Green, and Blue Queries
32701 XcmsQueryRed, Red, Green, and Blue Queries
32702 XcmsQueryWhite, Red, Green, and Blue Queries
32703 XcmsRGB, Color Structures
32704 XcmsRGBi, Color Structures
32705 XcmsScreenInitProc, Creating Additional Function Sets
32706 XcmsScreenNumberOfCCC, Color Conversion Context Macros
32707 XcmsScreenWhitePointOfCCC, Color Conversion Context Macros
32708 XcmsSetCCCOfColormap, Getting and Setting the Color Conversion
32709 Context of a Colormap
32710
32711 XcmsSetCompressionProc, Modifying Attributes of a Color
32712 Conversion Context
32713
32714 XcmsSetWhiteAdjustProc, Modifying Attributes of a Color
32715 Conversion Context
32716
32717 XcmsSetWhitePoint, Modifying Attributes of a Color Conversion
32718 Context
32719
32720 XcmsStoreColor, Modifying and Querying Colormap Cells
32721 XcmsStoreColors, Modifying and Querying Colormap Cells
32722 XcmsTekHVC, Color Structures
32723 XcmsTekHVCQueryMaxC, TekHVC Queries
32724 XcmsTekHVCQueryMaxV, TekHVC Queries
32725 XcmsTekHVCQueryMaxVC, TekHVC Queries
32726 XcmsTekHVCQueryMaxVSamples, TekHVC Queries
32727 XcmsTekHVCQueryMinV, TekHVC Queries
32728 XcmsVisualOfCCC, Color Conversion Context Macros
32729 XcmsWhiteAdjustProc, Prototype White Point Adjustment Procedure
32730 XColor, Color Structures
32731 XColormapEvent, Colormap State Change Events
32732 XConfigureEvent, ConfigureNotify Events
32733 XConfigureRequestEvent, ConfigureRequest Events
32734 XConfigureWindow, Configuring Windows
32735 XConnectionNumber, Display Macros
32736 XContextDependentDrawing, Obtaining Font Set Metrics
32737 XContextualDrawing, Obtaining Font Set Metrics
32738 XConvertCase, Using Keyboard Utility Functions
32739 XConvertSelection, Selections
32740 XCopyArea, Copying Areas
32741 XCopyColormapAndFree, Creating, Copying, and Destroying
32742 Colormaps
32743
32744 XCopyGC, Manipulating Graphics Context/State
32745 XCopyPlane, Copying Areas
32746 XCreateAssocTable, Associating User Data with a Value
32747 XCreateBitmapFromData, Manipulating Bitmaps
32748 XCreateColormap, Creating, Copying, and Destroying Colormaps
32749 XCreateFontCursor, Creating, Recoloring, and Freeing Cursors
32750 XCreateFontSet, Creating and Freeing a Font Set
32751 XCreateGC, Manipulating Graphics Context/State
32752 XCreateGlyphCursor, Creating, Recoloring, and Freeing Cursors
32753 XCreateIC, Input Context Functions
32754 XCreateImage, Manipulating Images
32755 XCreateOC, Output Context Functions
32756 XCreatePixmap, Creating and Freeing Pixmaps
32757 XCreatePixmapCursor, Creating, Recoloring, and Freeing Cursors
32758 XCreatePixmapFromBitmapData, Manipulating Bitmaps
32759 XCreateSimpleWindow, Creating Windows
32760 XCreateWindow, Creating Windows
32761 XCreateWindowEvent, CreateNotify Events
32762 XCrossingEvent, Window Entry/Exit Events
32763 XDefaultColormap, Display Macros
32764 XDefaultColormapOfScreen, Screen Information Macros
32765 XDefaultDepth, Display Macros
32766 XDefaultDepthOfScreen, Screen Information Macros
32767 XDefaultGC, Display Macros
32768 XDefaultGCOfScreen, Screen Information Macros
32769 XDefaultRootWindow, Display Macros
32770 XDefaultScreen, Display Macros
32771 XDefaultScreenOfDisplay, Display Macros
32772 XDefaultVisual, Display Macros
32773 XDefaultVisualOfScreen, Screen Information Macros
32774 XDefineCursor, Creating Windows, Changing Window Attributes
32775 XDeleteAssoc, Associating User Data with a Value
32776 XDeleteContext, Using the Context Manager
32777 XDeleteModifiermapEntry, Manipulating the Keyboard Encoding
32778 XDeleteProperty, Obtaining and Changing Window Properties
32779 XDestroyAssocTable, Associating User Data with a Value
32780 XDestroyIC, Input Context Functions
32781 XDestroyImage, Manipulating Images
32782 XDestroyOC, Output Context Functions
32783 XDestroyRegion, Creating, Copying, or Destroying Regions
32784 XDestroySubwindows, Destroying Windows
32785 XDestroyWindow, Destroying Windows
32786 XDestroyWindowEvent, DestroyNotify Events
32787 XDirectionalDependentDrawing, Obtaining Font Set Metrics
32788 XDisableAccessControl, Changing, Enabling, or Disabling Access
32789 Control
32790
32791 XDisplayCells, Display Macros
32792 XDisplayHeight, Image Format Functions and Macros
32793 XDisplayHeightMM, Image Format Functions and Macros
32794 XDisplayKeycodes, Manipulating the Keyboard Encoding
32795 XDisplayMotionBufferSize, Getting Pointer Motion History
32796 XDisplayName, Using the Default Error Handlers
32797 XDisplayOfIM, Input Method Functions
32798 XDisplayOfOM, Output Method Functions
32799 XDisplayOfScreen, Screen Information Macros
32800 XDisplayPlanes, Display Macros
32801 XDisplayString, Display Macros
32802 XDisplayWidth, Image Format Functions and Macros
32803 XDisplayWidthMM, Image Format Functions and Macros
32804 XDoesBackingStore, Screen Information Macros
32805 XDoesSaveUnders, Screen Information Macros
32806 xDoSomethingReply, Request Format
32807 xDoSomethingReq, Request Format
32808 XDrawArc, Drawing Single and Multiple Arcs, Drawing Single and
32809 Multiple Arcs
32810
32811 XDrawArcs, Drawing Single and Multiple Arcs, Drawing Single and
32812 Multiple Arcs
32813
32814 XDrawImageString, Drawing Image Text Characters, Drawing Image
32815 Text Characters
32816
32817 XDrawImageString16, Drawing Image Text Characters, Drawing
32818 Image Text Characters
32819
32820 XDrawLine, Drawing Single and Multiple Lines, Drawing Single
32821 and Multiple Lines
32822
32823 XDrawLines, Drawing Single and Multiple Lines, Drawing Single
32824 and Multiple Lines, Drawing and Filling Polygons and
32825 Curves
32826
32827 XDrawPoint, Drawing Single and Multiple Points, Drawing Single
32828 and Multiple Points
32829
32830 XDrawPoints, Drawing Single and Multiple Points, Drawing Single
32831 and Multiple Points
32832
32833 XDrawRectangle, Drawing Single and Multiple Rectangles, Drawing
32834 Single and Multiple Rectangles
32835
32836 XDrawRectangles, Drawing Single and Multiple Rectangles,
32837 Drawing Single and Multiple Rectangles
32838
32839 XDrawSegments, Drawing Single and Multiple Lines, Drawing
32840 Single and Multiple Lines, Drawing and Filling Polygons
32841 and Curves
32842
32843 XDrawString, Drawing Text Characters
32844 XDrawString16, Drawing Text Characters
32845 XDrawText, Drawing Complex Text
32846 XDrawText16, Drawing Complex Text
32847 XEHeadOfExtensionList, Hooks onto Xlib Data Structures
32848 XEmptyRegion, Determining if Regions Are Empty or Equal
32849 XEnableAccessControl, Changing, Enabling, or Disabling Access
32850 Control
32851
32852 XEnterWindowEvent, Window Entry/Exit Events
32853 XEqualRegion, Determining if Regions Are Empty or Equal
32854 XErrorEvent, Using the Default Error Handlers
32855 XESetBeforeFlush, Hooks into the Library
32856 XESetCloseDisplay, Hooks into the Library
32857 XESetCopyGC, Hooks into the Library
32858 XESetCreateFont, Hooks into the Library
32859 XESetCreateGC, Hooks into the Library
32860 XESetError, Hooks into the Library
32861 XESetErrorString, Hooks into the Library
32862 XESetEventToWire, Hooks into the Library
32863 XESetFlushGC, Hooks into the Library
32864 XESetFreeFont, Hooks into the Library
32865 XESetPrintErrorValues, Hooks into the Library
32866 XESetWireToError, Hooks into the Library
32867 XESetWireToEvent, Hooks into the Library
32868 XEvent, Event Structures
32869 XEventMaskOfScreen, Screen Information Macros
32870 XEventsQueued, Event Queue Management
32871 XExposeEvent, Expose Events
32872 XExtCodes, Hooking into Xlib
32873 XExtData, Hooks onto Xlib Data Structures
32874 XExtendedMaxRequestSize, Display Macros
32875 XExtentsOfFontSet, Obtaining Font Set Metrics
32876 XFetchBuffer, Using Cut Buffers
32877 XFetchBytes, Using Cut Buffers
32878 XFetchName, Setting and Reading the WM_NAME Property
32879 XFillArc, Filling Single and Multiple Arcs, Filling Single and
32880 Multiple Arcs
32881
32882 XFillArcs, Filling Single and Multiple Arcs
32883 XFillPolygon, Filling a Single Polygon
32884 XFillRectangle, Filling Single and Multiple Rectangles, Filling
32885 Single and Multiple Rectangles
32886
32887 XFillRectangles, Filling Single and Multiple Rectangles,
32888 Filling Single and Multiple Rectangles
32889
32890 XFilterEvent, Event Filtering
32891 XFindContext, Using the Context Manager
32892 XFindOnExtensionList, Hooks onto Xlib Data Structures
32893 XFlush, Handling the Output Buffer
32894 XFlushGC, Manipulating Graphics Context/State
32895 XFocusChangeEvent, Input Focus Events
32896 XFocusInEvent, Input Focus Events
32897 XFocusOutEvent, Input Focus Events
32898 XFontProp, Font Metrics
32899 XFontSetExtents, Obtaining Font Set Metrics
32900 XFontsOfFontSet, Creating and Freeing a Font Set
32901 XFontStruct, Font Metrics
32902 XForceScreenSaver, Controlling the Screen Saver
32903 XFree, Freeing Client-Created Data
32904 XFreeColormap, Creating, Copying, and Destroying Colormaps
32905 XFreeColors, Allocating and Freeing Color Cells
32906 XFreeCursor, Creating, Recoloring, and Freeing Cursors
32907 XFreeExtensionList, Basic Protocol Support Routines
32908 XFreeFont, Loading and Freeing Fonts
32909 XFreeFontInfo, Obtaining and Freeing Font Names and Information
32910 XFreeFontNames, Obtaining and Freeing Font Names and
32911 Information
32912
32913 XFreeFontPath, Setting and Retrieving the Font Search Path
32914 XFreeFontSet, Creating and Freeing a Font Set
32915 XFreeGC, Manipulating Graphics Context/State
32916 XFreeModifiermap, Manipulating the Keyboard Encoding
32917 XFreePixmap, Creating and Freeing Pixmaps
32918 XFreeStringList, Converting String Lists
32919 XGContextFromGC, Manipulating Graphics Context/State
32920 XGeometry, Parsing Window Geometry
32921 XGetAtomName, Properties and Atoms
32922 XGetAtomNames, Properties and Atoms
32923 XGetClassHint, Setting and Reading the WM_CLASS Property
32924 XGetCommand, Setting and Reading the WM_COMMAND Property
32925 XGetDefault, Getting the X Environment Defaults
32926 XGetErrorDatabaseText, Using the Default Error Handlers
32927 XGetErrorText, Using the Default Error Handlers
32928 XGetFontPath, Setting and Retrieving the Font Search Path
32929 XGetFontProperty, Loading and Freeing Fonts
32930 XGetGCValues, Manipulating Graphics Context/State
32931 XGetGeometry, Obtaining Window Information
32932 XGetIconName, Setting and Reading the WM_ICON_NAME Property
32933 XGetIconSizes, Setting and Reading the WM_ICON_SIZE Property
32934 XGetICValues, Input Context Functions
32935 XGetImage, Transferring Images between Client and Server
32936 XGetIMValues, Input Method Functions
32937 XGetInputFocus, Controlling Input Focus
32938 XGetKeyboardControl, Manipulating the Keyboard and Pointer
32939 Settings, Manipulating the Keyboard and Pointer Settings
32940
32941 XGetKeyboardMapping, Manipulating the Keyboard Encoding
32942 XGetModifierMapping, Manipulating the Keyboard Encoding
32943 XGetMotionEvents, Getting Pointer Motion History
32944 XGetNormalHints, Setting and Getting Window Sizing Hints
32945 XGetOCValues, Output Context Functions
32946 XGetOMValues, Output Method Functions
32947 XGetPixel, Manipulating Images
32948 XGetPointerControl, Manipulating the Keyboard and Pointer
32949 Settings
32950
32951 XGetPointerMapping, Manipulating the Keyboard and Pointer
32952 Settings
32953
32954 XGetRGBColormaps, Setting and Obtaining Standard Colormaps
32955 XGetScreenSaver, Controlling the Screen Saver
32956 XGetSelectionOwner, Selections
32957 XGetSizeHints, Setting and Getting Window Sizing Hints
32958 XGetStandardColormap, Getting and Setting an XStandardColormap
32959 Structure
32960
32961 XGetSubImage, Transferring Images between Client and Server
32962 XGetTextProperty, Setting and Reading Text Properties
32963 XGetTransientForHint, Setting and Reading the WM_TRANSIENT_FOR
32964 Property
32965
32966 XGetVisualInfo, Determining the Appropriate Visual Type
32967 XGetWindowAttributes, Obtaining Window Information
32968 XGetWindowProperty, Obtaining and Changing Window Properties
32969 XGetWMClientMachine, Setting and Reading the WM_CLIENT_MACHINE
32970 Property
32971
32972 XGetWMColormapWindows, Setting and Reading the
32973 WM_COLORMAP_WINDOWS Property
32974
32975 XGetWMHints, Setting and Reading the WM_HINTS Property
32976 XGetWMIconName, Setting and Reading the WM_ICON_NAME Property
32977 XGetWMName, Setting and Reading the WM_NAME Property
32978 XGetWMNormalHints, Setting and Reading the WM_NORMAL_HINTS
32979 Property
32980
32981 XGetWMProtocols, Setting and Reading the WM_PROTOCOLS Property
32982 XGetWMSizeHints, Setting and Reading the WM_NORMAL_HINTS
32983 Property
32984
32985 XGetZoomHints, Setting and Getting Window Sizing Hints
32986 XGrabButton, Pointer Grabbing
32987 XGrabKey, Keyboard Grabbing
32988 XGrabKeyboard, Keyboard Grabbing
32989 XGrabPointer, Pointer Grabbing
32990 XGrabServer, Grabbing the Server
32991 XGraphicsExposeEvent, GraphicsExpose and NoExpose Events
32992 XGravityEvent, GravityNotify Events
32993 XHeightMMOfScreen, Screen Information Macros
32994 XHeightOfScreen, Screen Information Macros
32995 XHostAddress, Adding, Getting, or Removing Hosts
32996 XIconifyWindow, Manipulating Top-Level Windows
32997 XIconSize, Setting and Reading the WM_ICON_SIZE Property,
32998 Setting and Reading the WM_ICON_SIZE Property
32999
33000 XID, Generic Values and Types
33001 XIfEvent, Selecting Events Using a Predicate Procedure
33002 XIMAbsolutePosition, Preedit Caret Callback
33003 XImage, Transferring Images between Client and Server
33004 XImageByteOrder, Image Format Functions and Macros
33005 XIMBackwardChar, Preedit Caret Callback
33006 XIMBackwardWord, Preedit Caret Callback
33007 XIMCallback, Preedit and Status Callbacks
33008 XIMCaretDirection, Preedit Caret Callback
33009 XIMCaretDown, Preedit Caret Callback
33010 XIMCaretStyle, Preedit Caret Callback
33011 XIMCaretUp, Preedit Caret Callback
33012 XIMDontChange, Preedit Caret Callback
33013 XIMForwardChar, Preedit Caret Callback
33014 XIMForwardWord, Preedit Caret Callback
33015 XIMHighlight, Preedit Draw Callback
33016 XIMInitialState, Reset State
33017 XIMLineEnd, Preedit Caret Callback
33018 XIMLineStart, Preedit Caret Callback
33019 XIMNextLine, Preedit Caret Callback
33020 XIMOfIC, Input Context Functions
33021 XIMPreeditArea, Query Input Style, Query Input Style
33022 XIMPreeditCallbacks, Query Input Style, Query Input Style
33023 XIMPreeditCaretCallbackStruct, Preedit Caret Callback
33024 XIMPreeditDisable, Preedit State
33025 XIMPreeditDrawCallbackStruct, Preedit Draw Callback
33026 XIMPreeditEnable, Preedit State
33027 XIMPreeditNone, Query Input Style, Query Input Style
33028 XIMPreeditNothing, Query Input Style, Query Input Style
33029 XIMPreeditPosition, Query Input Style, Query Input Style
33030 XIMPreeditStateNotifyCallbackStruct, Preedit State Notify
33031 Callback
33032
33033 XIMPreeditUnknown, Preedit State
33034 XIMPreviousLine, Preedit Caret Callback
33035 XIMPrimary, Preedit Draw Callback
33036 XIMProc, Preedit and Status Callbacks
33037 XIMReverse, Preedit Draw Callback
33038 XIMSecondary, Preedit Draw Callback
33039 XIMStatusArea, Query Input Style, Query Input Style
33040 XIMStatusCallbacks, Query Input Style, Query Input Style
33041 XIMStatusDataType, Status Callbacks
33042 XIMStatusDrawCallbackStruct, Status Callbacks
33043 XIMStatusNone, Query Input Style, Query Input Style
33044 XIMStatusNothing, Query Input Style, Query Input Style
33045 XIMStringConversionCallbackStruct, String Conversion Callback
33046 XIMStyle, Query Input Style
33047 XIMStyles, Query Input Style
33048 XIMTertiary, Preedit Draw Callback
33049 XIMText, Preedit Draw Callback
33050 XIMUnderline, Preedit Draw Callback
33051 XIMVisibleToBackward, Preedit Draw Callback
33052 XIMVisibleToCenter, Preedit Draw Callback
33053 XIMVisibleToForward, Preedit Draw Callback
33054 XInitExtension, Hooking into Xlib
33055 XInitImage, Transferring Images between Client and Server
33056 XInitThreads, Using Xlib with Threads
33057 XINPreserveState, Reset State
33058 XInsertModifiermapEntry, Manipulating the Keyboard Encoding
33059 XInstallColormap, Managing Installed Colormaps
33060 XInternalConnectionNumbers, Using Internal Connections
33061 XInternAtom, Properties and Atoms
33062 XInternAtoms, Properties and Atoms
33063 XIntersectRegion, Computing with Regions
33064 XKeyboardState, Manipulating the Keyboard and Pointer Settings
33065 XKeycodeToKeysym, Using Keyboard Utility Functions
33066 XKeymapEvent, Key Map State Notification Events
33067 XKeysymToKeycode, Using Keyboard Utility Functions
33068 XKeysymToString, Using Keyboard Utility Functions
33069 XKillClient, Killing Clients
33070 XLastKnownRequestProcessed, Display Macros
33071 XLeaveWindowEvent, Window Entry/Exit Events
33072 XLFD, Glossary
33073 XlibSpecificationRelease, Standard Header Files
33074 XListDepths, Display Macros
33075 XListExtensions, Basic Protocol Support Routines
33076 XListFonts, Obtaining and Freeing Font Names and Information
33077 XListFontsWithInfo, Obtaining and Freeing Font Names and
33078 Information
33079
33080 XListHosts, Adding, Getting, or Removing Hosts
33081 XListInstalledColormaps, Managing Installed Colormaps
33082 XListPixmapFormats, Image Format Functions and Macros
33083 XListProperties, Obtaining and Changing Window Properties
33084 XLoadFont, Loading and Freeing Fonts
33085 XLoadQueryFont, Loading and Freeing Fonts
33086 XLocaleOfFontSet, Creating and Freeing a Font Set
33087 XLocaleOfIM, Input Method Functions
33088 XLocaleOfOM, Output Method Functions
33089 XLockDisplay, Using Xlib with Threads
33090 XLookUpAssoc, Associating User Data with a Value
33091 XLookupColor, Mapping Color Names to Values
33092 XLookupKeysym, Using Keyboard Utility Functions
33093 XLookupString, Using Latin-1 Keyboard Event Functions
33094 XLowerWindow, Changing Window Stacking Order
33095 XMakeAssoc, Associating User Data with a Value
33096 XMapEvent, MapNotify Events
33097 XMappingEvent, MappingNotify Events
33098 XMapRaised, Mapping Windows
33099 XMapRequestEvent, MapRequest Events
33100 XMapSubwindows, Mapping Windows, Mapping Windows
33101 XMapWindow, Window Attributes, Mapping Windows, Mapping Windows
33102 XMaskEvent, Selecting Events Using a Window or Event Mask
33103 XMatchVisualInfo, Determining the Appropriate Visual Type
33104 XMaxCmapsOfScreen, Screen Information Macros
33105 XMaxRequestSize, Display Macros
33106 XmbDrawImageString, Drawing Text Using Font Sets
33107 XmbDrawString, Drawing Text Using Font Sets
33108 XmbDrawText, Drawing Text Using Font Sets
33109 XmbLookupString, Getting Keyboard Input
33110 XmbResetIC, Input Context Functions
33111 XmbSetWMProperties, Using Window Manager Convenience Functions
33112 XmbTextEscapement, Obtaining Font Set Metrics
33113 XmbTextExtents, Obtaining Font Set Metrics
33114 XmbTextItem, Drawing Text Using Font Sets
33115 XmbTextListToTextProperty, Converting String Lists
33116 XmbTextPerCharExtents, Obtaining Font Set Metrics
33117 XmbTextPropertyToTextList, Converting String Lists
33118 XMinCmapsOfScreen, Screen Information Macros
33119 XModifierKeymap, Manipulating the Keyboard Encoding
33120 XMoveResizeWindow, Configuring Windows
33121 XMoveWindow, Configuring Windows
33122 XNArea, Area
33123 XNAreaNeeded, Area Needed
33124 XNBackground, Foreground and Background
33125 XNClientWindow, Client Window
33126 XNColormap, Colormap
33127 XNCursor, Cursor
33128 XNewModifiermap, Manipulating the Keyboard Encoding
33129 XNextEvent, Handling the Output Buffer, Returning the Next
33130 Event
33131
33132 XNextRequest, Display Macros
33133 XNFilterEvents, Filter Events
33134 XNFocusWindow, Focus Window
33135 XNFontSet, Font Set
33136 XNForeground, Foreground and Background
33137 XNGeometryCallback, Geometry Callback
33138 XNoExposeEvent, GraphicsExpose and NoExpose Events
33139 XNoOp, Generating a NoOperation Protocol Request
33140 XNPreeditAttributes, Preedit and Status Attributes
33141 XNPreeditCaretCallback, Preedit and Status Callbacks
33142 XNPreeditDoneCallback, Preedit and Status Callbacks
33143 XNPreeditDrawCallback, Preedit and Status Callbacks
33144 XNPreeditStartCallback, Preedit and Status Callbacks
33145 XNResourceClass, Resource Name and Class
33146 XNResourceName, Resource Name and Class
33147 XNSpotLocation, Spot Location
33148 XNStatusAttributes, Preedit and Status Attributes
33149 XNStatusDoneCallback, Preedit and Status Callbacks
33150 XNStatusDrawCallback, Preedit and Status Callbacks
33151 XNStatusStartCallback, Preedit and Status Callbacks
33152 XNStdColormap, Colormap
33153 XOffsetRegion, Moving or Shrinking Regions
33154 XOMCharSetList, Required Char Set
33155 XOMOfOC, Output Context Functions
33156 XOpenDisplay, Opening the Display
33157 XOpenIM, Input Method Functions
33158 XOpenOM, Output Method Functions
33159 XParseColor, Mapping Color Names to Values
33160 XParseGeometry, Parsing the Window Geometry
33161 XPeekEvent, Returning the Next Event
33162 XPeekIfEvent, Selecting Events Using a Predicate Procedure
33163 XPending, Handling the Output Buffer, Event Queue Management
33164 Xpermalloc, Allocating Permanent Storage
33165 XPixmapFormatValues, Image Format Functions and Macros
33166 XPlanesOfScreen, Screen Information Macros
33167 XPoint, Drawing Points, Lines, Rectangles, and Arcs
33168 XPointer, Generic Values and Types
33169 XPointInRegion, Locating a Point or a Rectangle in a Region
33170 XPolygonRegion, Creating, Copying, or Destroying Regions
33171 XProcessInternalConnection, Using Internal Connections
33172 XPropertyEvent, PropertyNotify Events
33173 XProtocolRevision, Display Macros
33174 XProtocolVersion, Display Macros
33175 XPutBackEvent, Putting an Event Back into the Queue
33176 XPutImage, Transferring Images between Client and Server
33177 XPutPixel, Manipulating Images
33178 XQLength, Display Macros
33179 XQueryBestCursor, Creating, Recoloring, and Freeing Cursors,
33180 Creating, Recoloring, and Freeing Cursors
33181
33182 XQueryBestSize, Setting the Fill Tile and Stipple
33183 XQueryBestStipple, Setting the Fill Tile and Stipple
33184 XQueryBestTile, Setting the Fill Tile and Stipple
33185 XQueryColor, Modifying and Querying Colormap Cells
33186 XQueryColors, Modifying and Querying Colormap Cells
33187 XQueryExtension, Basic Protocol Support Routines
33188 XQueryFont, Loading and Freeing Fonts
33189 XQueryKeymap, Manipulating the Keyboard and Pointer Settings
33190 XQueryPointer, Translating Screen Coordinates
33191 XQueryTextExtents, Querying Character String Sizes
33192 XQueryTextExtents16, Querying Character String Sizes
33193 XQueryTree, Obtaining Window Information
33194 XRaiseWindow, Changing Window Stacking Order
33195 XReadBitmapFile, Manipulating Bitmaps
33196 XReadBitmapFileData, Manipulating Bitmaps
33197 XRebindKeysym, Using Latin-1 Keyboard Event Functions
33198 XRecolorCursor, Creating, Recoloring, and Freeing Cursors
33199 XReconfigureWMWindow, Manipulating Top-Level Windows
33200 XRectangle, Drawing Points, Lines, Rectangles, and Arcs
33201 XRectInRegion, Locating a Point or a Rectangle in a Region
33202 XRefreshKeyboardMapping, Using Keyboard Utility Functions
33203 XRegisterIMInstantiateCallback, Input Method Functions
33204 XRemoveConnectionWatch, Using Internal Connections
33205 XRemoveFromSaveSet, Controlling the Lifetime of a Window
33206 XRemoveHost, Adding, Getting, or Removing Hosts
33207 XRemoveHosts, Adding, Getting, or Removing Hosts
33208 XReparentEvent, ReparentNotify Events
33209 XReparentWindow, Changing the Parent of a Window
33210 XResetScreenSaver, Controlling the Screen Saver
33211 XResizeRequestEvent, ResizeRequest Events
33212 XResizeWindow, Configuring Windows
33213 XResourceManagerString, Creating and Storing Databases
33214 xResourceReq, Request Format
33215 XRestackWindows, Changing Window Stacking Order
33216 XrmCombineDatabase, Merging Resource Databases
33217 XrmCombineFileDatabase, Merging Resource Databases
33218 XrmDatabase, Creating and Storing Databases
33219 XrmDestroyDatabase, Creating and Storing Databases
33220 XrmEnumerateDatabase, Enumerating Database Entries
33221 XrmGetDatabase, Creating and Storing Databases
33222 XrmGetFileDatabase, Creating and Storing Databases
33223 XrmGetResource, Looking Up Resources
33224 XrmGetStringDatabase, Creating and Storing Databases
33225 XrmInitialize, Creating and Storing Databases
33226 XrmLocaleOfDatabase, Creating and Storing Databases
33227 XrmMergeDatabases, Merging Resource Databases
33228 XrmOptionDescRec, Parsing Command Line Options
33229 XrmOptionKind, Parsing Command Line Options
33230 XrmParseCommand, Parsing Command Line Options
33231 XrmPermStringToQuark, Quarks
33232 XrmPutFileDatabase, Creating and Storing Databases
33233 XrmPutLineResource, Storing into a Resource Database
33234 XrmPutResource, Storing into a Resource Database
33235 XrmPutStringResource, Storing into a Resource Database
33236 XrmQGetResource, Looking Up Resources
33237 XrmQGetSearchList, Looking Up Resources
33238 XrmQGetSearchResource, Looking Up Resources
33239 XrmQPutResource, Storing into a Resource Database
33240 XrmQPutStringResource, Storing into a Resource Database
33241 XrmQuarkToString, Quarks
33242 XrmSetDatabase, Creating and Storing Databases
33243 XrmStringToBindingQuarkList, Quarks
33244 XrmStringToQuark, Quarks
33245 XrmStringToQuarkList, Quarks
33246 XrmUniqueQuark, Quarks
33247 XrmValue, Creating and Storing Databases
33248 XRootWindow, Display Macros
33249 XRootWindowOfScreen, Screen Information Macros
33250 XRotateBuffers, Using Cut Buffers
33251 XRotateWindowProperties, Obtaining and Changing Window
33252 Properties
33253
33254 XSaveContext, Using the Context Manager
33255 XScreenCount, Display Macros
33256 XScreenNumberOfScreen, Screen Information Macros
33257 XScreenOfDisplay, Display Macros
33258 XScreenResourceString, Creating and Storing Databases
33259 XSegment, Drawing Points, Lines, Rectangles, and Arcs
33260 XSelectInput, Selecting Events
33261 XSelectionClearEvent, SelectionClear Events
33262 XSelectionEvent, SelectionNotify Events
33263 XSelectionRequestEvent, SelectionRequest Events
33264 XSendEvent, Sending Events to Other Applications, Sending
33265 Events to Other Applications
33266
33267 XServerInterpretedAddress, Adding, Getting, or Removing Hosts
33268 XServerVendor, Display Macros
33269 XSetAccessControl, Changing, Enabling, or Disabling Access
33270 Control
33271
33272 XSetAfterFunction, Enabling or Disabling Synchronization
33273 XSetArcMode, Setting the Arc Mode, Subwindow Mode, and Graphics
33274 Exposure
33275
33276 XSetBackground, Setting the Foreground, Background, Function,
33277 or Plane Mask
33278
33279 XSetClassHint, Setting and Reading the WM_CLASS Property
33280 XSetClipMask, Setting the Clip Region
33281 XSetClipOrigin, Setting the Clip Region
33282 XSetClipRectangles, Setting the Clip Region
33283 XSetCloseDownMode, Closing the Display
33284 XSetCommand, Setting and Reading the WM_COMMAND Property
33285 XSetDashes, Setting the Line Attributes and Dashes
33286 XSetErrorHandler, Using the Default Error Handlers
33287 XSetFillRule, Setting the Fill Style and Fill Rule
33288 XSetFillStyle, Setting the Fill Style and Fill Rule
33289 XSetFont, Setting the Current Font
33290 XSetFontPath, Setting and Retrieving the Font Search Path
33291 XSetForeground, Setting the Foreground, Background, Function,
33292 or Plane Mask
33293
33294 XSetFunction, Setting the Foreground, Background, Function, or
33295 Plane Mask
33296
33297 XSetGraphicsExposures, Setting the Arc Mode, Subwindow Mode,
33298 and Graphics Exposure
33299
33300 XSetICFocus, Input Context Functions
33301 XSetIconName, Setting and Reading the WM_ICON_NAME Property
33302 XSetIconSizes, Setting and Reading the WM_ICON_SIZE Property
33303 XSetICValues, Input Context Functions
33304 XSetIMValues, Input Method Functions
33305 XSetInputFocus, Controlling Input Focus
33306 XSetIOErrorHandler, Using the Default Error Handlers
33307 XSetLineAttributes, Setting the Line Attributes and Dashes
33308 XSetLocaleModifiers, X Locale Management
33309 XSetModifierMapping, Manipulating the Keyboard Encoding
33310 XSetNormalHints, Setting and Getting Window Sizing Hints
33311 XSetOCValues, Output Context Functions
33312 XSetOMValues, Output Method Functions
33313 XSetPlaneMask, Setting the Foreground, Background, Function, or
33314 Plane Mask
33315
33316 XSetPointerMapping, Manipulating the Keyboard and Pointer
33317 Settings
33318
33319 XSetRegion, Creating, Copying, or Destroying Regions
33320 XSetRGBColormaps, Setting and Obtaining Standard Colormaps
33321 XSetScreenSaver, Controlling the Screen Saver
33322 XSetSelectionOwner, Selections
33323 XSetSizeHints, Setting and Getting Window Sizing Hints
33324 XSetStandardColormap, Getting and Setting an XStandardColormap
33325 Structure
33326
33327 XSetStandardProperties, Setting Standard Properties
33328 XSetState, Setting the Foreground, Background, Function, or
33329 Plane Mask
33330
33331 XSetStipple, Setting the Fill Tile and Stipple
33332 XSetSubwindowMode, Setting the Arc Mode, Subwindow Mode, and
33333 Graphics Exposure
33334
33335 XSetTextProperty, Setting and Reading Text Properties
33336 XSetTile, Setting the Fill Tile and Stipple
33337 XSetTransientForHint, Setting and Reading the WM_TRANSIENT_FOR
33338 Property
33339
33340 XSetTSOrigin, Setting the Fill Tile and Stipple
33341 XSetWindowAttributes, Window Attributes
33342 XSetWindowBackground, Changing Window Attributes
33343 XSetWindowBackgroundPixmap, Changing Window Attributes
33344 XSetWindowBorder, Changing Window Attributes
33345 XSetWindowBorderPixmap, Changing Window Attributes
33346 XSetWindowBorderWidth, Configuring Windows
33347 XSetWindowColormap, Changing Window Attributes
33348 XSetWMClientMachine, Setting and Reading the WM_CLIENT_MACHINE
33349 Property
33350
33351 XSetWMColormapWindows, Setting and Reading the
33352 WM_COLORMAP_WINDOWS Property
33353
33354 XSetWMHints, Setting and Reading the WM_HINTS Property
33355 XSetWMIconName, Setting and Reading the WM_ICON_NAME Property
33356 XSetWMName, Setting and Reading the WM_NAME Property
33357 XSetWMNormalHints, Setting and Reading the WM_NORMAL_HINTS
33358 Property
33359
33360 XSetWMProperties, Using Window Manager Convenience Functions
33361 XSetWMProtocols, Setting and Reading the WM_PROTOCOLS Property
33362 XSetWMSizeHints, Setting and Reading the WM_NORMAL_HINTS
33363 Property
33364
33365 XSetZoomHints, Setting and Getting Window Sizing Hints
33366 XShrinkRegion, Moving or Shrinking Regions
33367 XStoreBuffer, Using Cut Buffers
33368 XStoreBytes, Using Cut Buffers
33369 XStoreColor, Modifying and Querying Colormap Cells
33370 XStoreColors, Modifying and Querying Colormap Cells
33371 XStoreName, Setting and Reading the WM_NAME Property
33372 XStoreNamedColor, Modifying and Querying Colormap Cells
33373 XStringListToTextProperty, Converting String Lists
33374 XStringToKeysym, Using Keyboard Utility Functions
33375 XSubImage, Manipulating Images
33376 XSubtractRegion, Computing with Regions
33377 XSync, Overview of the X Window System, Overview of the X
33378 Window System, Handling the Output Buffer
33379
33380 XSynchronize, Enabling or Disabling Synchronization
33381 XTextExtents, Computing Logical Extents
33382 XTextExtents16, Computing Logical Extents
33383 XTextItem, Drawing Text
33384 XTextItem16, Drawing Text
33385 XTextProperty, Converting String Lists
33386 XTextPropertyToStringList, Converting String Lists
33387 XTextWidth, Computing Character String Sizes, Computing
33388 Character String Sizes
33389
33390 XTextWidth16, Computing Character String Sizes, Computing
33391 Character String Sizes
33392
33393 XTimeCoord, Getting Pointer Motion History
33394 XTranslateCoordinates, Translating Screen Coordinates
33395 XUndefineCursor, Changing Window Attributes
33396 XUngrabButton, Pointer Grabbing
33397 XUngrabKey, Keyboard Grabbing
33398 XUngrabKeyboard, Keyboard Grabbing
33399 XUngrabPointer, Pointer Grabbing
33400 XUngrabServer, Grabbing the Server
33401 XUninstallColormap, Managing Installed Colormaps
33402 XUnionRectWithRegion, Computing with Regions
33403 XUnionRegion, Computing with Regions
33404 XUnloadFont, Loading and Freeing Fonts
33405 XUnlockDisplay, Using Xlib with Threads
33406 XUnmapEvent, UnmapNotify Events
33407 XUnmapSubwindows, Unmapping Windows
33408 XUnmapWindow, Unmapping Windows, Unmapping Windows
33409 XUnregisterIMInstantiateCallback, Input Method Functions
33410 XUnsetICFocus, Input Context Functions
33411 XVaCreateNestedList, Variable Argument Lists
33412 XVendorRelease, Display Macros
33413 XVisibilityEvent, VisibilityNotify Events
33414 XVisualIDFromVisual, Visual Types
33415 XWarpPointer, Moving the Pointer
33416 XwcDrawImageString, Drawing Text Using Font Sets
33417 XwcDrawString, Drawing Text Using Font Sets
33418 XwcDrawText, Drawing Text Using Font Sets
33419 XwcFreeStringList, Converting String Lists
33420 XwcLookupString, Getting Keyboard Input
33421 XwcResetIC, Input Context Functions
33422 XwcTextEscapement, Obtaining Font Set Metrics
33423 XwcTextExtents, Obtaining Font Set Metrics
33424 XwcTextItem, Drawing Text Using Font Sets
33425 XwcTextListToTextProperty, Converting String Lists
33426 XwcTextPerCharExtents, Obtaining Font Set Metrics
33427 XwcTextPropertyToTextList, Converting String Lists
33428 XWhitePixel, Display Macros
33429 XWhitePixelOfScreen, Screen Information Macros
33430 XWidthMMOfScreen, Screen Information Macros
33431 XWidthOfScreen, Screen Information Macros
33432 XWindowAttributes, Obtaining Window Information
33433 XWindowChanges, Configuring Windows
33434 XWindowEvent, Handling the Output Buffer, Selecting Events
33435 Using a Window or Event Mask
33436
33437 XWithdrawWindow, Manipulating Top-Level Windows
33438 XWMGeometry, Parsing the Window Geometry
33439 XWriteBitmapFile, Manipulating Bitmaps, Manipulating Bitmaps
33440 XXorRegion, Computing with Regions
33441 XY format, Glossary
33442
33443Z
33444
33445 Z format, Glossary